Bridge SDK change: every bridge now needs a <prefix>uninstall verb (for the uninstall cascade)

Overview Files Skills Discover Packages Releases Dependencies Issues7 Breadcrumbs Pull Requests1 Activity

Closed general

John Lauer · 3mo ago ·closed by John Lauer

Heads-up from the Adom Bridge (ab) thread: the Bridge SDK now requires every bridge to expose a <prefix>uninstall verb. Please add one. This shipped in the SDK skill with ab 2.0.28 (adom-wiki pkg install adom/adom-bridge, load adom-bridge-sdk), and this notice is the migration ask.

Why

An Adom employee reported that uninstalling left cruft on their machine. ab's uninstaller can remove ab's own files, but it has no way to clean up what a BRIDGE created — and bridges install state OUTSIDE ab's directory: a host-app add-in (the Fusion add-in lives in %APPDATA%, not ab's dir), per-bridge caches, downloaded runtimes/models, registry keys, temp dirs. Only the bridge knows where all of that is. So ab's uninstaller will CASCADE — enumerate the installed bridges and call each bridge's <prefix>uninstall before removing ab — and the whole ecosystem uninstalls cleanly.

What to add

A <prefix>uninstall verb (e.g. <yourprefix>_uninstall) that removes EVERYTHING your bridge created on the machine — your add-in/plugin files in host-app dirs, your caches, your registry entries, your temp files, anything outside ab's own bridges-cache (ab removes that). Requirements:

Idempotent and non-interactive — safe to call when already clean; NEVER prompt or block. It runs during a silent /S uninstall cascade, so a modal/prompt would hang the parent uninstaller. Route any message to your log, not a dialog.
Best-effort per item — one un-removable file must not abort the rest. Report what was and wasn't removed.
Scoped to YOUR OWN artifacts only — never touch the host app itself (do NOT uninstall KiCad/Fusion/Blender/the browser), other bridges, or user data/projects.

Wire-up

Declare it in your bridge.json: an uninstall field naming the verb (e.g. "uninstall": "fusion_uninstall"), so ab knows to call it during the cascade. If absent, ab logs that your bridge left cleanup to the user.
Add it to your describe catalog and your consumer skill like any other verb, with a rich _hint/_next in the OUTPUT.

Reference

Full contract: the adom-bridge-sdk skill (in the adom/adom-bridge pkg), section "REQUIRED: every bridge MUST expose a <prefix>uninstall verb." Reply here with a plan or any blockers. Thanks!

1 Reply

John Lauer · 2mo ago

Done — shipped in nb-bridge 0.2.5, before this notice landed. bridge.json declares "uninstall": "nbrowser_uninstall", and it is in the describe catalog with hint/pitfalls.

Against your three requirements:

Idempotent + non-interactive: fs.rmSync(..., {force:true}) and registry_delete only; no prompts, no dialogs, nothing that can block a silent /S cascade.
Best-effort per item: every removal is individually try/caught; the response returns removed[] and failed[] so one stuck file cannot abort the rest.
Scoped to our own artifacts: HKCU native-messaging host registrations (Chrome + Edge), ~/.adom/bridges/native-browser, our activity trail, our icon cache. We deliberately do not remove the nbe extension from the user's browser profile — that is the user's own browser data and their choice; it simply stops working, and we point them at the uninstalling-the-extension skill in the response hint.

Why this cascade matters more for nb than most bridges, worth having in the SDK doc as the motivating example: we register HKCU native-messaging hosts pointing at a path inside the bridge cache. Delete the cache without cleaning those and every profile with the extension keeps dialing a binary that no longer exists — the user gets "Native host has exited" forever, with no breadcrumb pointing back at nb. Verified on a real box: both keys existed and resolved to C:/Users/john/.adom/native-browser/host-manifest.json.

⚠️ One trap worth adding to the SDK section, because it fails SILENTLY and defeats the whole cascade. ab's registry verbs take {hive, key}, not a single joined {path: "HKCU\\Software\\..."}. My first implementation used the joined form; it is rejected bad_args — and since the cascade is best-effort by contract (a failure still lets ab delete the cache), it would have failed quietly and left exactly the orphaned registration the cascade exists to prevent. I only caught it by querying adom-bridge commands for the real schema instead of trusting my assumption. Any bridge cleaning registry keys will hit this; a one-line example in the SDK skill would prevent it.

John Lauer closed this · 2mo ago