# Building + publishing this bridge

How to publish a new version of the Adom Desktop Puppeteer bridge. The wiki has TWO storage layers —
put each artifact in the right one (every pitfall here was hit live on the kicad/fusion bridges).

| Artifact | Where it goes | How |
|---|---|---|
| Source (`src/*`, `SKILL.md`, the **manifest JSON**, docs) | the page's **git repo** | `adom-wiki repo push --files ...` |
| The build **`.zip`** (binary runtime) | a **release asset** | `adom-wiki release upload ...` |

> ⛔ The `.zip` is a RELEASE, not a git file. `*.zip` is gitignored and `repo push --files X.zip`
> silently skips it (reports ok, the URL 404s). Only the small **manifest JSON** goes in the git repo,
> and it POINTS AT the release asset.

## 1 — bump the version (two files, lockstep)

```bash
printf '1.1.1' > src/BRIDGE_VERSION
sed -i 's/"version": "1.1.0"/"version": "1.1.1"/' src/bridge.json
```

## 2 — build the zip (the `src/` tree at the zip ROOT, no top-level dir)

`zip` may be absent — use Python. node_modules is NOT included (AD `npm install`s it on spawn; the
bundled seed ships it):

```python
import zipfile, os, hashlib
root = "src"
out = "adom-bridge-puppeteer-v1.1.1.zip"
with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
    for dirpath, dirs, files in os.walk(root):
        if "node_modules" in dirs: dirs.remove("node_modules")
        for f in files:
            full = os.path.join(dirpath, f)
            z.write(full, os.path.relpath(full, root))   # arcname relative to src/ → zip root
print("sha256:", hashlib.sha256(open(out,"rb").read()).hexdigest(), "size:", os.path.getsize(out))
```

## 3 — publish the zip as a RELEASE asset (preserves your sha)

```bash
adom-wiki release create  adom/adom-desktop-puppeteer-bridge 1.1.1                       # idempotent
adom-wiki release upload  adom/adom-desktop-puppeteer-bridge 1.1.1 adom-bridge-puppeteer-v1.1.1.zip --json
# JSON gives sha256, size, download_url (/download/adom/adom-desktop-puppeteer-bridge/1.1.1/<file>)
```

## 4 — point the manifest at the release + push it (text, git-ok)

`adom-bridge-puppeteer-manifest.json`:
```json
{ "manifest_version": 1, "name": "puppeteer", "version": "1.1.1",
  "url": "https://wiki.adom.inc/download/adom/adom-desktop-puppeteer-bridge/1.1.1/adom-bridge-puppeteer-v1.1.1.zip",
  "sha256": "<the release asset's sha256>", "size": <bytes>,
  "verbPrefixes": ["browser_","desktop_recorder_","desktop_record_"],
  "healthEndpoint": "/status", "statusVerb": "browser_readiness",
  "released_at": "<UTC ISO8601>" }
```
```bash
adom-wiki repo push adom/adom-desktop-puppeteer-bridge \
  --files adom-bridge-puppeteer-manifest.json src/bridge.json src/BRIDGE_VERSION src/server.js src/chrome.js SKILL.md \
  -m "v1.1.1: <what changed>"
```

> `sha256`/`size` MUST match the served asset or `bridge_install` rejects it. Re-download to confirm:
> `curl -sL <download_url> | sha256sum`.

## 5 — install into Adom Desktop + test

```bash
adom-desktop bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/adom-desktop-puppeteer-bridge/files/adom-bridge-puppeteer-manifest.json","force":true}'
# server-only change → AD reaps + respawns the bridge from the new cache on the next browser_* call.
# Then: adom-desktop browser_readiness '{}'   (confirms the new verbs/code are live)
```

(Multiple desktops on one relay → pass `--target <name>`; `adom-desktop targets` lists them.)

## Pitfall checklist

- `.zip` → `release upload`, never `repo push` (gitignored + silently skipped).
- Manifest JSON → `repo push`; its `url` is the RELEASE download URL, not `/files/`.
- `sha256`/`size` must match the SERVED asset (re-download to confirm).
- `zip` binary may be absent → Python `zipfile`.
- node_modules is NEVER in the zip (size/limits/native builds) — AD reconstructs it on spawn.
- Keep `src/BRIDGE_VERSION` and `src/bridge.json` version in lockstep, and > the bundled seed so
  cache-over-bundled wins.