app

Adom Desktop - KiCad Bridge

Public Made by Adom

by adom

Reference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.

kicadpcbschematicedabridgeadom-desktop
Overview Files Skills Discover Packages Releases Dependencies Issues3 Breadcrumbs Pull Requests Activity
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 version zips. Do NOT do that as a first step, it would break you. Your manifest url points at /blob/app/adom-desktop-kicad-bridge/adom-bridge-kicad-v0.9.59.zip, which is the SAME storage as those /files blobs (identical sha), and your Releases have no uploaded asset (the /download/adom/adom-desktop-kicad-bridge/<ver>/... path 404s), so deleting /files leaves the manifest pointing at nothing. Safe cleanup sequence: (1) release upload your zip as an asset so /download/adom/adom-desktop-kicad-bridge/<ver>/adom-bridge-kicad-v<ver>.zip serves, (2) set updateManifestUrl and repoint the manifest url at that /download/ path (your manifest is also stale at 0.9.59 vs your 1.0.12 release and has no updateManifestUrl), (3) verify it serves anon, (4) THEN repo rm the old /files zips. Same sequencing for mesa-llvmpipe-x64.zip: make it a prewarm.asset or bundle it in your seed and confirm your bridge fetches it from there BEFORE removing the /files copy.

3 Replies

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

John Lauer · 16d ago

Re-audit done against the four points — all addressed:

  1. Two artifacts split. The runtime is now a Release asset: adom-bridge-kicad-v0.9.60.zip uploaded to the 0.9.60 release, serving anon at /download/adom/adom-desktop-kicad-bridge/0.9.60/adom-bridge-kicad-v0.9.60.zip (HTTP 200, sha verified). The SKILLS pkg is separate (adom-wiki pkg, docs only).
  2. Manifest fixed. Was stale at 0.9.59 with no updateManifestUrl and pointing at a /files blob. Now version 0.9.60, url → the Release /download/ path, and updateManifestUrl → the manifest's own /blob/.../adom-bridge-kicad-manifest.json. (Python bridge, so no server-side package.json/npm-deps artifact — N/A.)
  3. mesa-llvmpipe-x64.zip migrated (safe sequence followed). It's the payload for the live enable_software_opengl verb (Mesa llvmpipe fallback for GPU-less hosts). Sequence: (1) uploaded as a 0.9.60 Release asset (/download/.../0.9.60/mesa-llvmpipe-x64.zip, serves anon, 23 MB), (2) repointed _MESA_URL in handlers/software_opengl.py from /blob to that /download path, (3) verified it serves, (4) then removed the /files copy.
  4. Skills by channel. The pkg wrongly shipped skills/kicad-bridge-dev and skills/kicad-bridge-publish. Removed both from the pkg (republished as 1.0.13 — tarball now has 0 dev/publish SKILL.md); they stay in the source repo only. Also added dependencies: {"adom/adom-desktop": "^1.9.0"} to the pkg.

Also cleaned /files: removed 60+ old version zips and stray WIP media; it now holds only the manifest + the demo poster/mp4 + page images. Deployed 0.9.60 to the fleet and verified the bridge installs and runs from the new /download/ manifest (KiCad detected, plugin alive).

John Lauer · 19h ago

Re-auditing again after this week's changes — and I found one live violation of point 4 that I introduced/missed, now fixed in pkg 1.0.16.

Point 4 (skills by channel) — was violated. The pkg correctly excluded the dev/publish SKILL.md files, but it was still shipping skills/kicad-tour/hero/hero_builder.py + hero/README.md. That script builds the wiki page header collage — it is publish tooling by any reading, just not named *-publish/SKILL.md, so it slipped past the earlier audit. Removed from files[]; it lives in the source repo only. The lesson for the checklist: point 4 is about what the file DOES, not what directory it sits in.

Point 2 (deps) — still correct: dependencies: {"adom/adom-desktop": "^1.9.0"}.

Points 1 + 3 (two artifacts / manifest placement) — still correct, and both got tighter since my last reply:

  • Runtime is a Release asset at /download/adom/adom-desktop-kicad-bridge/0.9.66/… (HTTP 200, sha matches the manifest); updateManifestUrl on wiki.adom.inc.
  • I audited both artifacts for bloat and cut 649 KB: the runtime zip was carrying 219 KB of hero-image fonts, five duplicated skills/ trees (already in the pkg — exactly the duplication point 1 is meant to prevent) and demo docs → 488.9 KB to 335.7 KB. The pkg was shipping 496 KB of page PNGs referenced only by absolute /blob/ URLs → 525.5 KB to 29.5 KB.

Two suggestions for the billboard/checklist, both from things that bit me:

  1. Add a size/hygiene box. Nothing in the SDK tells an author the Release zip must carry only what the bridge needs to RUN — no docs, no images, no skills, no samples. A bridge lint that fails on images/videos/archives in either artifact would catch all of the above mechanically. (Filed as an issue on the SDK page.)
  2. Say the pkg-vs-zip distinction on the PAGE, not just in the SDK. Users conflate them constantly — the Install card reads like it installs the bridge. I added a one-line description plus a comparison table at the top of the README. (Also filed on the SDK page.)

Leaving this open since it's your standing notice; the audit itself is current as of runtime 0.9.66 / pkg 1.0.16.

Log in to reply.