NB - Native Browser Bridge

@@ -1,90 +0,0 @@-----name: shipping-the-bridge-description: How to ship an update to the native-browser BRIDGE so adom-desktop (AD) actually picks it up. The cardinal fact AIs get wrong: AD reads ONLY the bridge RELEASE ARTIFACT (a manifest + a zip), NEVER the git Files tab - so `adom-wiki repo push` of bridge/server.js updates what humans browse but does NOT reach AD. Covers building the manifest + versioned zip, the wiki .zip-upload trap (host the bytes as .bin), the canonical owner-scoped file URL, bridge_install (first time, records the manifest URL) vs refresh_bridges (after; no manual kill on AD 1.9.27+), verifying with bridge_check_updates + nbrowser_describe, and the "when you add a verb, update three places" rule. Use when changing bridge/server.js or bridge.json, cutting a new bridge version, adding an nbrowser_ verb, or when "AD is still running the old bridge". Part of the adom-browser-extension. See also cross-platform-dev (the OS/dev flow) and installing-the-extension (the bridge_install precondition).-----Part of **adom-browser-extension**. OS/dev flow: **cross-platform-dev**. Install precondition: **installing-the-extension**.--# Shipping a bridge update (so adom-desktop picks it up)--The bridge (`bridge/server.js` + `bridge/bridge.json`) runs on the user's laptop, spawned by AD from-its writable **`bridges-cache`**. Updating it is NOT a normal git push.--## ⛔ The cardinal fact: AD reads the RELEASE ARTIFACT, not the git Files-There are two independent wiki layers (same split as README vs the package registry):-- **Git Files** (`adom-wiki repo push`) - what humans browse. **AD never reads this for bridge code.**-- **The bridge release artifact** - a `native-browser-bridge-manifest.json` (version + zip url + sha256)-  plus a **versioned zip**. This is the ONLY thing AD pulls.--So pushing `bridge/server.js` to the repo changes nothing for AD. You must publish a new artifact.--## The artifact-- `native-browser-bridge-manifest.json` = `{ "manifest_version":1, "version", "url", "sha256", "size", "released_at" }`.-- A zip with `bridge.json` + `server.js` + `package.json` + `BRIDGE_VERSION` **at the ZIP ROOT** (no-  `bridge/` prefix). AD requires `bridge.json` at the zip root.--## ⛔ The wiki silently rejects `.zip` uploads-`POST .../files` with a `.zip` returns `{ok:true, commit:null}` but the file **never lands** (a `.png`-through the same path commits fine). So host the zip **bytes** under a **`.bin`** name-(`native-browser-bridge-v<ver>.bin`) and point the manifest `url` at that. AD just HTTP-GETs the `url`-and unzips the bytes - the extension is cosmetic. (`adom-wiki repo push` also drops binaries except PNG;-use `adom-wiki api` for the `.bin`.)--## Steps-1. **Bump the version in ALL THREE files** (or AD sees no update): `bridge/bridge.json` `version`,-   `bridge/package.json` `version`, `bridge/BRIDGE_VERSION`.-2. **Build the zip** - there is NO `zip` binary in the container; use Python `zipfile`, files at root:-   ```python-   import zipfile,hashlib,os,json,datetime-   src="bridge"; out="/tmp/native-browser-bridge-v<ver>.zip"-   with zipfile.ZipFile(out,"w",zipfile.ZIP_DEFLATED) as z:-       for f in ["server.js","bridge.json","package.json","BRIDGE_VERSION"]:-           z.write(os.path.join(src,f), arcname=f)        # arcname = root-   raw=open(out,"rb").read(); sha=hashlib.sha256(raw).hexdigest(); size=len(raw)-   ```-3. **Write the manifest** with `url:"native-browser-bridge-v<ver>.bin"`, the `sha256`, `size`,-   `released_at` (UTC, e.g. `datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")`).-4. **Upload the payload as `.bin`** (base64) via `adom-wiki api`:-   `adom-wiki api -X POST /api/pages/adom/adom-browser-extension/files --body '<json with files[0]={path,content(base64),encoding:"base64"}>'`.-   (CLI args cap ~128KB each; the bridge zip is ~25KB so inline is fine. For bigger payloads write the-   body to a file and pass it.)-5. **Push the manifest + the bumped source** as text: `adom-wiki repo push adom-browser-extension --files-   native-browser-bridge-manifest.json bridge/bridge.json bridge/package.json bridge/BRIDGE_VERSION bridge/server.js -m "..."`.-6. **Verify the artifact is live + intact** (AD sha256-checks on download): GET the `.bin`, confirm bytes-   == `size` and `sha256sum` == the manifest sha.--## Use the CANONICAL file URL (not the legacy alias)-The durable, documented route is **owner-scoped, no `/v1`**:-```-https://wiki.adom.inc/api/pages/<owner>/<slug>/files/<file>-  e.g. https://wiki.adom.inc/api/pages/adom/adom-browser-extension/files/native-browser-bridge-manifest.json-```-The `/api/v1/pages/<slug>/...` form is a legacy slug-only alias that still resolves but is fragile (breaks-on fork / when v1 retires). Always give AD the canonical URL.--## Make AD pick it up-- **First time on a machine:** `adom-desktop bridge_install '{"manifestUrl":"<canonical manifest url>"}'`.-  This downloads + sha-verifies + extracts the zip into `bridges-cache`, AND **persists the manifest URL**-  so the bridge auto-updates from its own page (AD 1.9.26+ tracks per-bridge manifest URLs).-- **Every update after that:** `adom-desktop refresh_bridges '{"name":"native-browser"}'` (or AD's-  on-launch + 4-hourly auto-sync). **AD 1.9.27+ auto-reaps the running process and respawns on the new-  code - NO manual `bridge_kill` needed.** (`action:"updated", from, to`.)-- The running bridge respawns on the new code on the next `nbrowser_*` call.--## Verify the update landed-- `adom-desktop bridge_check_updates` -> for `native-browser`: `current` == new version,-  `wikiHosted:true`, `updateAvailable:false`.-- A live `adom-desktop nbrowser_describe '{}'` -> serves the current verb set (proves the new code is running).--## When you ADD or change a verb, update THREE places (or it breaks)-1. `bridge/bridge.json` `verbs[]` - so AD ROUTES the verb to this bridge.-2. The `VERB_META` table in `server.js` - `hint` / `related` / `pitfalls` (feeds both the response `_hint`-   and `nbrowser_describe`).-3. The `nbrowser_describe` entry in `server.js` - the input/output schema for AD's Verbs tab (AD 1.9.23+).-Miss (1) and AD won't route it; miss (2)/(3) and it ships undocumented.--## Mental model + gotchas-- **Two layers:** git Files = humans; release artifact = AD. Don't confuse a `repo push` with shipping.-- **`.zip` is blocked** on the wiki API (silent) - always `.bin`.-- **No `zip` binary** in the container - Python `zipfile`.-- **Bump all three version files** together; a half-bump means AD sees no update or a mismatched runtime-  version string.