Open general

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

John Lauer · 16d ago

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"):

  1. 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.
  2. 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.
  3. 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.
  4. 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 (correction to my earlier version of this post): I first said to repo rm your loose /files zips and ship as a Release only. Do it as a sequence, not a delete-first. Your manifest url is currently the relative adom-bridge-blender-v1.0.1.zip (resolves to your /files blob) and your 1.0.0 Release has no uploaded asset, so removing /files now breaks bridge_install. Safe order: (1) release upload the zip as an asset, (2) repoint the manifest url at /download/adom/adom-desktop-blender-bridge/<ver>/adom-bridge-blender-v<ver>.zip, (3) verify it serves anon, (4) THEN repo rm the loose /files copies.

1 Reply

John Lauer · 16d 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

Log in to reply.