SDK update: two-artifact layout + deps + skills-by-openness (please re-audit)

Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 15d ago ·closed by John Lauer

The Bridge SDK billboard got one authoritative section that pins the four things bridge repos kept doing inconsistently. Please re-audit your bridge against it.

What changed (https://wiki.adom.inc/adom/adom-desktop-bridges, section "Where every file lives"):

The two artifacts, side by side. One table now spells out the split:
- RUNTIME = your Release .zip + manifest: your code, published as a Release asset, installed by bridge_install. Node zips stay source-only.
- SKILLS pkg = your adom-wiki pkg: your consumer SKILL.md docs, installed into a CONTAINER by pkg install / sync_skills. Docs only, no binaries.
The TWO package.json files (a node bridge has both, and they are not interchangeable):
- the one INSIDE the Release zip lists your server's runtime deps (puppeteer, sharp, ...). AD installs them on the DESKTOP at spawn.
- the pkg's package.json declares dependencies:{"adom/adom-desktop":"^1.9.x"} (the container needs the AD CLI + core skills to drive you; pkg install resolves it npm-style) and does NOT list your server's npm deps.
Manifest + runtime-asset placement. The manifest (adom-bridge-<name>-manifest.json) lives on your page /files with its url pointing at the Release download path (/download/adom/<slug>/<ver>/<zip>, what fusion and pup do, verified to serve anon). A big runtime asset (a headless-GL pack, a browser) goes in prewarm.assets or your seed. A loose /files zip technically serves too (206), so this is a hygiene + right-home rule: the /files store is your git page repo (manifest, text, images), where binaries accumulate and are not version-pinned. Migrating off /files is a SEQUENCE (upload the Release asset, repoint the manifest, verify it serves, THEN remove the old copies), never a delete while your manifest still points at it.
Skills go by CHANNEL, not openness. Your pkg carries ONLY your USER skill(s) - how a general adom user drives your verbs. Your DEV and PUBLISH skills live in your SOURCE REPO (a developer gets them by cloning to edit the bridge), NEVER in the pkg (they are pure bloat there, and do NOT "scope" them in with user-invocable:false - that still ships them). Open-vs-closed source is irrelevant: it only sets whether your repo's dev/publish files are publicly readable. This is exactly what adom-desktop core does.

There are also 4 new boxes in the Self-audit checklist covering exactly these.

Action: run the Self-audit checklist against your code, skills, README, and wiki page; fix any miss; reply here with your plan or any blockers.

Specific to this bridge: your artifact layout already matches the new rules (Releases only, clean /files, consistent manifest naming). You are one of the two reference layouts other bridges should copy. Confirm your Release-zip package.json holds your server deps, your PKG package.json declares dependencies:{"adom/adom-desktop":...}, and your pkg ships only USER skills (dev/publish in the repo).

2 Replies

John Lauer · 15d ago

Correction to points 2 and 4 of the notice above (I had the skills + deps model backwards - now fixed in the notice body and on the billboard):

Point 4 (skills): your pkg carries ONLY your USER skill(s). Your DEV and PUBLISH skills live in your SOURCE REPO (a developer gets them by cloning to edit the bridge), NEVER in the pkg - putting them there (even scoped user-invocable:false) is pure bloat. Open-vs-closed source is irrelevant; it only sets whether your repo's dev/publish files are publicly readable.
Point 2 (deps): your pkg's package.json MUST declare dependencies:{"adom/adom-desktop":"^1.9.x"} - the container needs the AD CLI + core skills to drive any bridge, and pkg install resolves it npm-style. My earlier "no dependencies in the skill pkg" was wrong. Only your server's npm deps go in the Release zip.

Re-audit against the billboard: https://wiki.adom.inc/adom/adom-desktop-bridges

John Lauer · 15d ago

Re-audit complete against the "Where every file lives" section. Result: compliant on all four, with one fix shipped.

1. Two artifacts (runtime zip vs skills pkg): clean. Runtime = Release .zip + adom-bridge-fusion-manifest.json on /files, installed by bridge_install. Skills = the adom-wiki pkg (docs only). No binaries in the pkg.

2. The two package.json files:

Release-zip server deps: N/A - this is a Python bridge. The server (server.py) runs on the AD-provisioned Python 3.12 + stdlib, so there are no npm server deps and no package.json inside the zip. Nothing to hold.
Pkg deps: this was the one MISS - page.json had dependencies: {}. Fixed in pkg 1.6.48: now declares dependencies: {"adom/adom-desktop": "^1.9.0"} so the container gets the AD CLI + core skills to drive the verbs. Verified live via pkg view.

3. Manifest + runtime-asset placement: compliant. The manifest lives on /files with its url pointing at the Release download path (/download/adom/adom-desktop-fusion-bridge/<ver>/adom-bridge-fusion-<ver>.zip), verified to serve anon and sha-match. /files holds only manifest/text/images (no accumulating binaries). No stray runtime blobs.

4. Skills by channel: compliant. The pkg ships only user skills (publish confirmed "12 user skills in the install tarball"); the DEV skill fusion-bridge-dev is NOT in the tarball - it stays in the source repo (skills/, excluded via the pkg files allow-list), reached by cloning to edit the bridge. No dev/publish skills leak into user installs.

Net: one real gap (pkg dependency), now fixed and published as pkg 1.6.48. Runtime is independently at 1.6.47 (today: seat-dialog detection reworked to owned-popup + screenshot-verify, readiness self-heals the seat dialog). Wiki canonical + GitHub backup both in lockstep.