Pup - the AI's own browser

@@ -1,121 +0,0 @@-----name: pup-bridge-publish-user-invocable: false-description: "DEVELOPER skill — the exact, battle-tested recipe for publishing a new version of the Adom Desktop Puppeteer (pup) bridge to wiki.adom.inc, plus every gotcha hit live. NOT for general users. Read before cutting a release: which artifact goes where (pkg=skills, release=bridge zip), the version-lockstep rules, the `files` allowlist + `skills/**` glob trap, the hero-bloat fix, sha matching, and the verify steps. Trigger words: publish pup bridge, ship pup bridge, release pup, pkg publish, repo push, adom-wiki release, bridge manifest, pup version bump, adom-desktop-puppeteer-bridge publish."------# pup-bridge-publish — shipping a new pup bridge version--The pup bridge is cloud-owned at `wiki.adom.inc/adom/adom-desktop-puppeteer-bridge`. This is the-step-by-step ship recipe + the traps that cost real time. Companion: `pup-bridge-dev` (architecture /-ownership), `PUBLISHING.md` (terse recipe), `CLAUDE.md` (ownership boundary).--## What goes WHERE — three artifacts, three homes (memorize this)--| Artifact | Home | Command | Carries |-|---|---|---|---|-| **bridge runtime `.zip`** | a **Release** asset | `adom-wiki release upload` | `src/` at zip-root (server.js, chrome.js, bridge.json, node deps). The thing AD runs. |-| **streaming manifest JSON** | the **git repo** | `adom-wiki repo push` | points at the release zip URL + its sha256/size |-| **container skills tarball** | a **Package** | `adom-wiki pkg publish` | `SKILL.md` + `skills/*` (the Claude skills). NO runtime. |--> The `.zip` is a RELEASE, never a git file: `*.zip` is gitignored and `repo push --files X.zip`-> reports `ok` but silently skips it (the URL then 404s). Binaries → `release upload`.--## Auth (once per container)--```bash-export ADOM_WIKI_TOKEN=$(cat /var/run/adom/api-key 2>/dev/null)   # container default; or session.json's session_token-adom-wiki whoami    # MUST show a real user (e.g. [email protected]). Strict-auth rejects the shared "Developer" token.-```-Every mutation needs a real `--changelog` / `-m` (≥10 chars, ≥2 words) or the server 400s.--## The recipe--### 1. Bump version IN LOCKSTEP, and keep it > the AD bundled seed--```bash-printf '1.1.1' > src/BRIDGE_VERSION-sed -i 's/"version": "1.1.0"/"version": "1.1.1"/' src/bridge.json    # bridge runtime-sed -i 's/"version": "1.1.0"/"version": "1.1.1"/' package.json       # adompkg descriptor (the pkg)-```-`src/BRIDGE_VERSION` and `src/bridge.json` MUST match (AD uses BRIDGE_VERSION to detect a stale running-process). Keep the number **above** the seed in `adom-desktop/plugins/puppeteer` so cache-over-bundled wins.--### 2. Build the bridge zip (source-only, `src/` at zip ROOT — no top-level dir)--`zip` may be absent → Python. node_modules is NEVER included (AD `npm install`s it on spawn; the seed-ships it; an 88 MB zip would blow wiki limits):--```python-import zipfile, os, hashlib-root, out = "src", "adom-bridge-puppeteer-v1.1.1.zip"-with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:-    for dp, dirs, files in os.walk(root):-        for skip in ("node_modules","screenshots","profiles"):-            if skip in dirs: dirs.remove(skip)-        for f in files: z.write(os.path.join(dp,f), os.path.relpath(os.path.join(dp,f), root))-print("sha256:", hashlib.sha256(open(out,"rb").read()).hexdigest(), "size:", os.path.getsize(out))-# SANITY: assert chrome.js + your change are inside before shipping.-```--### 3. Publish the zip as a Release (releases PRESERVE your sha)--```bash-adom-wiki release create adom/adom-desktop-puppeteer-bridge 1.1.1 --title "..." --changelog "<≥2 words>"-adom-wiki release upload adom/adom-desktop-puppeteer-bridge 1.1.1 adom-bridge-puppeteer-v1.1.1.zip --json-# the response's assets[].sha256/size are what the manifest MUST carry. Then VERIFY the PUBLIC url:-curl -sL https://wiki.adom.inc/download/adom/adom-desktop-puppeteer-bridge/1.1.1/adom-bridge-puppeteer-v1.1.1.zip | sha256sum-```--### 4. Point the manifest at the release + push it (git repo)--Edit `adom-bridge-puppeteer-manifest.json` → `version`, `url` (the release download URL), `sha256`,-`size` (from step 3 — **must match the served asset or `bridge_install` rejects it**). Then:--```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 \-  -m "v1.1.1: <what changed>"-```--### 5. Publish the container skills as a pkg — keep it LEAN, and MIND THE TRAPS--```bash-adom-wiki pkg pack            # ALWAYS pack + inspect BEFORE publish-tar tzf *.tgz                 # confirm: SKILL.md + skills/*/SKILL.md + install.sh, and NOTHING heavy-adom-wiki pkg publish --org adom --version 1.1.1-adom-wiki pkg notes adom/[email protected] -m "Container skills: <what changed>"-```--The pkg description lives in the root **`package.json`** `description` — keep it explicit that this is-**container-side skills only; the bridge runtime is the Release zip + bundled in Adom Desktop.**--## Traps hit live (don't relearn these)--- **`pkg pack` includes EVERYTHING by default** → a 16 MB tarball (all the hero PNGs + `src/` runtime).-  Fix: the heroes are gitignored (`*.png`) since they're already page assets, AND `package.json` has a-  **`files` allowlist**. With both, the tarball drops to ~12 KB.-- **`files` directory entries need a GLOB.** Listing `"skills"` (bare dir) silently includes ZERO skill-  files. Use **`"skills/**"`** (and/or the explicit `"skills/<name>/SKILL.md"`). Always `tar tzf` to-  confirm your skills actually made it in — a missing skill = an empty Skills tab.-- **`pkg pack` honors `.gitignore`, not a separate npmignore.** So you can't gitignore something you-  need in git (e.g. `src/`) to drop it from the pkg — use the `files` allowlist for that.-- **A RELEASE shows up in `adom-wiki pkg info` as a row with `type:null`** (wiki UI conflation). The real-  pkg rows are `type:"app"`. Use `adom-wiki release list` for true releases; don't think your pkg shipped-  just because a version appears in `pkg info`.-- **sha/size mismatch → `bridge_install` rejects the manifest.** Releases preserve the uploaded sha, so-  use the `release upload` response values verbatim and re-download to confirm.-- **The Skills tab is populated from the published PKG, not `page.json`** (`page.skills` is null even on-  pages with a full Skills tab). If skills aren't showing, you didn't `pkg publish` them (or the `files`-  glob dropped them).--## Verify (every ship)--```bash-# manifest serves at the updateManifestUrl path:-curl -s https://wiki.adom.inc/api/v1/pages/adom-desktop-puppeteer-bridge/files/adom-bridge-puppeteer-manifest.json | jq .sha256-# live install + new verbs on a real desktop (multi-desktop → --target; `adom-desktop targets` lists them):-adom-desktop --target <name> bridge_install '{"manifestUrl":".../files/adom-bridge-puppeteer-manifest.json","force":true}'-adom-desktop --target <name> browser_readiness '{}'-# render the page in pup + READ the screenshot (curl 200 is NOT verification). Confirm version + Skills tab.-```