--- name: adom-desktop-bridge-author description: Use this skill when the user says they want to write/author/build a third-party bridge for adom-desktop, integrate a new desktop app (Altium, MATLAB, SolidWorks, an oscilloscope, etc.) with cloud Claude, fork the hello sample bridge, ship a bridge to the wiki, or asks how custom CLI verbs get routed into adom-desktop. Walks them through scaffolding a fresh bridge from the canonical template, wiring `bridge.json`, writing the HTTP server, packaging the zip, hosting it, and verifying install via `adom-desktop bridge_install`. --- # Authoring an Adom Desktop bridge A bridge is a small HTTP server (Python, Node, or any executable) that adom-desktop spawns on demand and proxies cloud CLI requests to. Once installed, every `adom-desktop ''` whose verb starts with your bridge's prefix routes to your server. Adom Desktop v1.8.0+ supports dynamic bridges installed at runtime from a wiki manifest URL — no fork of adom-desktop required. ## When to use this skill The user wants to write a bridge if they say any of: - "I want to integrate Altium / MATLAB / Eagle / SolidWorks / OrCAD / my oscilloscope / our internal CAD tool with adom-desktop" - "Help me build a third-party adom-desktop bridge" - "How do I add a new CLI verb to adom-desktop?" (the answer is almost always "ship it as a bridge, not by forking adom-desktop") - "Fork the hello sample bridge" - "Make my bridge installable via the install modal" If they want to USE existing bridges (kicad, fusion, puppeteer), that's the `adom-desktop` skill, not this one. ## Prerequisites The user needs adom-desktop installed + running on their laptop and reachable from this container: ```bash adom-desktop ping ``` If that fails, walk them through the install flow at https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop first. ## Workflow ### Step 1 — pick a bridge name + verb prefix Ask the user: - What's the host app this bridge integrates? (e.g. "Altium Designer") - What lowercase one-word name should the bridge use? (e.g. `altium`) — this is the cache directory name + the manifest key - What verb prefix should they own? Conventionally `_*`, e.g. `altium_open_project`, `altium_export_step`. Prefixes are first-come-first-served across the registry; check existing bridges with `adom-desktop bridge_list` so you don't collide. Reserved prefixes that are already taken: - `kicad_*` (kicad bridge) - `browser_*`, `desktop_recorder_*`, `desktop_record_*` (puppeteer bridge) - `fusion_*` (fusion360 bridge) - `hello_*` (sample bridge) Reserved bridge ports: 8770–8779 (Adom-owned), 8851 (puppeteer). Pick something in 8800–9000 for new bridges. ### Step 2 — scaffold from the hello sample The hello sample bridge is the minimum viable example — a ~80-line stdlib-Python HTTP server. Have the user download + extract it: ```bash # On the user's laptop (run via adom-desktop shell_execute or have them run it themselves): curl -L https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-bridge-v1.0.0.zip \ -o /tmp/hello-bridge.zip mkdir -p ~/my-bridge && cd ~/my-bridge python3 -c "import zipfile; zipfile.ZipFile('/tmp/hello-bridge.zip').extractall()" ls -la ``` They now have `bridge.json`, `BRIDGE_VERSION`, `server.py`, `README.md`. Rename the directory + edit each file to match the new bridge name/verbs. For Node-based bridges, look at the puppeteer bridge zip instead: `https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/puppeteer-bridge-v1.0.0.zip` For app-with-plugin-API bridges (Altium / SolidWorks / etc.), the fusion360 bridge is the right reference — it has both a bridge process AND an in-host add-in: `https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/fusion360-bridge-v1.0.0.zip` ### Step 3 — edit `bridge.json` The schema is documented at https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges#bridgejson-schema. Minimum required fields: ```json { "manifest_version": 1, "name": "", "displayName": "", "version": "1.0.0", "description": "One-line description that shows up in bridge_list.", "spawn": { "kind": "python", "entrypoint": "server.py", "port": 8XXX, "healthEndpoint": "http://127.0.0.1:8XXX/status", "stopMethod": "kill", "killImageName": "python.exe" }, "verbPrefixes": ["_"], "verbs": ["_verb1", "_verb2"] } ``` Keep `verbs` accurate — `bridge_list` advertises this to discovery. Don't list verbs you haven't implemented. If your bridge supports project-watching (file watcher → auto-resync to Docker), add a `watcher` block: ```json "watcher": { "supports": true, "displayName": "", "defaultGlobs": ["*.your-ext"], "configKey": "project_watch" } ``` The GUI renders an eye-pip on the chip when watching is active. ### Recommended: `docs` URL + `platforms` map (v1.8.14+) These two optional fields make your bridge a first-class citizen of the GUI: ```json "docs": "https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/your-bridge-name", "platforms": { "windows": { "supported": true }, "macos": { "supported": false, "reason": "Mac port pending — Win32 deps in handlers/window_automation.py need a Quartz equivalent." }, "linux": { "supported": false, "reason": "Same as macOS." } } ``` - **`docs`**: surfaces in the chip's right-click context menu as "View on wiki" (top item). Use it. If you don't have a wiki page yet, publish one first (see `adom-wiki page publish` via the `adom-wiki` skill). - **`platforms`**: an honest declaration of which OSes the bridge actually works on. Keys are `windows` / `macos` / `linux`. The GUI shows the support status in the tooltip + warns (non-blocking) in the install modal if the user is on a `supported: false` OS. Provide a `reason` string when something doesn't work — the user sees it verbatim, so explain why. Tell the user **don't lie in `platforms`**. If they haven't tested macOS, leave it as `{"supported": false, "reason": "Untested on macOS so far"}` rather than claiming support. The whole point of the field is honesty — better to set expectations than burn a user who installs a bridge that silently fails. ### Step 4 — implement the server The HTTP contract is two endpoints: - `GET /status` → `{"ok": true, "version": "..."}` — used by adom-desktop to confirm the bridge is alive - `POST /command` body `{"verb": "_", "args": {...}}` → `{"success": true, "output": "..."}` or `{"success": false, "error": "..."}` The hello sample's `server.py` is the canonical shape — fork it and replace the verb handlers with yours. When implementing handlers: - Validate `args` strictly. Return `{"success": false, "error": "..."}` for invalid input; don't 500. - Keep responses small. If returning large payloads (file contents, binary blobs), write to disk first and return the path; Docker will use `pull_file` to fetch. - Long-running operations (>5s) should return immediately with a job handle, then expose a `_status` verb for polling. ### Step 5 — test locally via a localhost manifest Before publishing to the wiki, test with a local HTTP server: ```bash # Build the zip cd ~/my-bridge python3 -c " import zipfile, os, fnmatch EXCLUDE = ['*/__pycache__/*', '*.pyc', '.history/*'] with zipfile.ZipFile('../my-bridge-v1.0.0.zip', 'w', zipfile.ZIP_DEFLATED) as zf: for root, dirs, files in os.walk('.'): for f in files: rel = os.path.relpath(os.path.join(root, f), '.') if any(fnmatch.fnmatch(rel.replace(os.sep, '/'), g) for g in EXCLUDE): continue zf.write(os.path.join(root, f), rel) " # Compute sha256 + size SHA=$(sha256sum ../my-bridge-v1.0.0.zip | awk '{print $1}') SIZE=$(stat -c%s ../my-bridge-v1.0.0.zip) # Write the manifest cat > ../my-bridge-manifest.json <_ '{...}' # Stop the local server when done kill $LOCAL_SERVE_PID ``` This roundtrip exercises the entire install path (download + sha256 verify + extract + registry rescan + spawn-on-first-call) without uploading anything yet. ### Step 6 — ship to the wiki (recommended) or any HTTPS host Two options: **Option A — Adom Wiki** (recommended for bridges they want the community to find): ```bash adom-wiki asset upload apps/adom-desktop \ --asset-type file \ --file ../my-bridge-v1.0.0.zip \ --caption "my-bridge v1.0.0" # Then upload a manifest pointing at that zip's wiki URL # (Replace the local-server URL with the wiki static URL the upload command prints.) adom-wiki asset upload apps/adom-desktop \ --asset-type file \ --file ../my-bridge-manifest.json \ --caption "my-bridge manifest v1.0.0" ``` Suggest the user also write a dedicated `apps/-bridge` wiki page documenting their bridge — same shape as the [reference bridges](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges#reference-implementations). Use the `adom-wiki` skill for the publish flow. **Option B — any HTTPS host** (GitHub Releases, your own CDN, S3): ```bash # Upload both files anywhere reachable by HTTPS, then: adom-desktop bridge_install '{"manifestUrl":"https://your-host/my-bridge-manifest.json"}' ``` Cloud users can install from any reachable URL — they're not locked to the wiki. ### Step 7 — verify end-to-end + iterate ```bash # See it in the registry adom-desktop bridge_list # Trigger your verbs adom-desktop _ '{...}' # Inspect the install dir (right-click the chip in the GUI → Open install folder) # OR programmatically: adom-desktop shell_execute '{"command":"powershell -NoProfile -Command \"Get-ChildItem $env:LOCALAPPDATA\\\\\\\"Adom Desktop\\\\\\\"\\\\bridges-cache\\\\\"","timeout_secs":5}' # After edits, bump bridge.json's version + BRIDGE_VERSION, rebuild the zip, re-upload, then: adom-desktop refresh_bridges ``` To ship a breaking change without leaving users on the old version: bump the manifest's `version` field. On next launch + refresh, adom-desktop fetches the new manifest, compares versions, downloads + verifies the new zip, atomically swaps the cache dir. ## Lifecycle controls available to your bridge users These verbs are built into adom-desktop — you don't implement them, just know they exist so you can mention them when users ask: | Verb | What it does | |---|---| | `bridge_list` | List all installed bridges + their metadata | | `bridge_install` | Install from a manifest URL | | `bridge_uninstall` | Remove from cache (returns to the bundled version if there was one) | | `bridge_pause` | Stop routing verbs (process stays running, verbs return "paused") | | `bridge_resume` | Resume routing | | `refresh_bridges` | Re-poll all known manifest URLs for updates | From the Adom Desktop GUI: right-click any chip in the bridge bar for Pause / Resume / Open install folder / Uninstall. ## Reference pages on the wiki These pages contain full architecture writeups for the three bundled bridges. Use them when the user is stuck on a pattern you've already seen one of these solve: - **[Bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges)** — schema, packaging, lifecycle, trust model - **[KiCad bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-kicad-bridge)** — multi-instance, reverse-bridge into the host app - **[Puppeteer bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-puppeteer-bridge)** — single-instance Node + session-profile isolation + recording - **[Fusion 360 bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-fusion-bridge)** — passthrough-to-add-in pattern (use for Altium, SolidWorks, Eagle) ## Trust + security gotchas to warn users about - The trust model is SHA256-verification of the zip against the manifest. **Users install with their own privileges** — bridges can read/write any file the user can. Tell them to install only from sources they trust. - If you publish to the wiki, anyone in the org can see it. For internal-only bridges, host the manifest behind auth (HTTPS basic, signed URLs, etc.) — adom-desktop's `bridge_install` honors HTTP redirects + auth headers passed via `--auth-header`. - Don't put secrets in the bridge zip. The unpacked cache dir is readable by anyone on the same machine. Read secrets at runtime from env vars / OS keychain / a `.env` next to the bridge cache that the user populates manually. ## When something goes wrong 1. **`bridge_install` says SHA mismatch** — the zip you uploaded doesn't match the manifest's `sha256`. Recompute and re-upload the manifest. 2. **Verb returns "bridge not found"** — the prefix you declared doesn't match the verb. Check `adom-desktop bridge_list` to see what prefixes you actually registered. 3. **Bridge process won't start** — adom-desktop reports the spawn failure. Common causes: wrong `entrypoint`, `spawn.kind` mismatch (Python file as `node`), missing dependencies. Check the GUI's activity log. 4. **Bridge runs but verbs return "process exited"** — your handler probably crashed. Add `try/except` around your dispatcher and log to stderr; adom-desktop forwards stderr lines to the GUI log. 5. **Open install folder shows a "Location is not available" dialog** — the cache dir doesn't exist on the user's real filesystem (probably installed from a sandboxed context). Uninstall + reinstall from a clean session. See https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges for the full troubleshooting.