Adom Bridge

@@ -0,0 +1,109 @@+---+name: adom-desktop-kicad+public: true+description: "Launch and drive KiCad on the user's laptop (KiCad 7/8/9/10 supported, multi-version side-by-side) from this container via the adom-desktop CLI. Open schematics/boards/symbols/footprints, run DRC, install sym-lib-table / fp-lib-table libraries, show the 3D viewer, capture KiCad window screenshots, send keyboard shortcuts and click coordinates. Trigger words: kicad, open schematic, open board, open pcb, open symbol, open footprint, KiCad symbol editor, KiCad footprint editor, KiCad 3D viewer, run DRC, install KiCad library, sym-lib-table, fp-lib-table, KiCad screenshot, kicad_send_key, kicad_click, kicad_window_info, kicad_screenshot_all, close KiCad, kicad versions, kicad_list_versions, KiCad bridge."+---++# adom-desktop — KiCad bridge++All commands dispatch to the KiCad Python bridge running alongside the desktop app. Invoke from this container via Bash:++```bash+adom-desktop kicad_<action> '<json_args>'+```++The leading `kicad_` routes the call to the KiCad plugin; the `<action>` names below are the plugin-side command names.++## Multi-version (KiCad 9 + KiCad 10 side-by-side)++Users can have multiple KiCad versions installed at the same time. The bridge auto-discovers everything under `C:/Program Files/KiCad/<version>/` and **defaults to the newest installed version** if you don't specify one.++```bash+# Discover what's installed (run this first if unsure)+adom-desktop kicad_list_versions '{}'+# → {"versions":[{"version":"10.0", "default":true, ...}, {"version":"9.0", ...}], "default":"10.0", "count":2}+```++Every `kicad_open_*` (and `install_*`, `run_drc`) command accepts an optional **`kicadVersion`** arg to pin a specific install:++```bash+# Open in KiCad 10 (newest — default if you omit kicadVersion)+adom-desktop kicad_open_board '{"filePath":"C:/designs/foo.kicad_pcb"}'++# Open in KiCad 9 explicitly (e.g. to check that an older project still works)+adom-desktop kicad_open_board '{"filePath":"C:/designs/foo.kicad_pcb","kicadVersion":"9.0"}'+```++If you pass a version that's not installed, the bridge returns a hint listing the installed versions. The success response includes `kicadVersionUsed` so you can confirm which install actually ran.++> **Note on libraries / config**: each KiCad version has its own `sym-lib-table` and `fp-lib-table` (in `%APPDATA%/kicad/<version>/`). `kicad_install_library` writes to the table of whichever version was selected — so if the user installs a library and then asks "open it in KiCad 9", you may need to install it under both versions.++## Commands++| CLI form | Action | Purpose | Key args |+|---|---|---|---|+| `kicad_list_versions` | `list_versions` | Enumerate every installed KiCad version with paths and which one is the default | — |+| `kicad_open_schematic` | `open_schematic` | Open a `.kicad_sch` in the Schematic Editor | `filePath`, optional `kicadVersion` |+| `kicad_open_board` | `open_board` | Open a `.kicad_pcb` in the PCB Editor | `filePath`, optional `kicadVersion` |+| `kicad_open_symbol_editor` | `open_symbol_editor` | Launch Symbol Editor (optional: open specific library/symbol) | `libraryName`, `symbolName`, optional `kicadVersion` |+| `kicad_open_footprint_editor` | `open_footprint_editor` | Launch Footprint Editor | `libraryName`, `footprintName`, optional `kicadVersion` |+| `kicad_open_3d_viewer` | `open_3d_viewer` | Show the board in 3D viewer | optional `kicadVersion` |+| `kicad_close_symbol_editor` | `close_symbol_editor` | Close Symbol Editor | — |+| `kicad_close_footprint_editor` | `close_footprint_editor` | Close Footprint Editor | — |+| `kicad_close_3d_viewer` | `close_3d_viewer` | Close 3D viewer | — |+| `kicad_close` | `close` | Close KiCad (all editors) | — |+| `kicad_window_info` | `window_info` | Enumerate open KiCad windows (HWND, title, bounds, editor type) | — |+| `kicad_install_library` | `install_library` | Register a `.kicad_sym` + `.pretty/` pair in sym-lib-table + fp-lib-table | `libraryPath`, `libraryType`, `libraryName`, optional `kicadVersion` |+| `kicad_install_symbol` | `install_symbol` | Add a single symbol to an existing library | `fileName`, `fileContent`, optional `kicadVersion` |+| `kicad_install_footprint` | `install_footprint` | Add a single footprint to an existing library | `library`, `footprint_path`, optional `kicadVersion` |+| `kicad_run_drc` | `run_drc` | Run DRC on the current board, return violations | `filePath`, optional `kicadVersion` |+| `kicad_fix_keyboard` | `fix_keyboard` | Workaround stuck-modifier bug after screen lock | — |+| `kicad_screenshot_all` | `screenshot_all` | Capture every open KiCad window (lossless PNGs) | — |+| `kicad_send_key` | `send_key` | Send a keyboard shortcut to a KiCad window | `hwnd`, `key` |+| `kicad_click` | `click` | Send a click at (x, y) in a KiCad window | `hwnd`, `x`, `y` |+| `kicad_adom_library_status` | `adom_library_status` | Report whether the Adom shared library is registered | — |++## Quick examples++```bash+# Open a schematic+adom-desktop kicad_open_schematic '{"path":"C:/designs/foo.kicad_sch"}'++# List open KiCad windows+adom-desktop kicad_window_info '{}'++# Screenshot every KiCad window+adom-desktop kicad_screenshot_all '{}'++# Run DRC+adom-desktop kicad_run_drc '{"board_path":"C:/designs/foo.kicad_pcb"}'++# Install a library pair+adom-desktop kicad_install_library '{+  "name":"my-lib",+  "sym_path":"C:/libs/my-lib.kicad_sym",+  "fp_path":"C:/libs/my-lib.pretty"+}'+```++## Error shape++Every failing response includes a `_hint` field with a human-readable next step — surface it to the user verbatim when a KiCad command fails.++## Bridge architecture (v1.8.31+) — you don't need to know any port++Earlier versions of the KiCad bridge listened on hardcoded port `8772`. **As of v1.8.31, bridges use OS-assigned ephemeral ports** — every spawn gets a new free port. You never need to know it.++- The CLI (`adom-desktop kicad_*`) automatically routes through adom-desktop's direct API (default port 47200 as of v1.8.33, with auto-fallback to 47201-47209 if 47200 is taken). adom-desktop then forwards to the bridge's actual runtime port.+- The bridge port is internal plumbing and can change every spawn. `bridge_list` reports it as `spawn.runtimePort` for debugging only — do NOT hardcode that anywhere.+- Why: this lets adom-desktop coexist with Hydrogen Desktop (which used to claim 8772 itself) and any other tool that grabs ports in the 8000 range. Side-by-side bridges from different apps no longer collide.+- The relay path (Docker → wss proxy → Windows GUI) is unchanged — same `adom-desktop kicad_*` verbs, same JSON shape.++If you ever find yourself wanting to talk directly to the KiCad bridge process: don't. Go through the verb dispatch. If the verb you need doesn't exist, request a feature in `adom-inc/adom-desktop`.++## Related++- `adom-desktop-discovery` (gallia) — ensures the CLI + relay are installed.+- `adom-desktop-fusion` — sibling bridge for Fusion 360.+- `adom-desktop-direct-api` — the direct API contract (port 47200 + 47201-47209 fallback, discovery file at `~/.adom/direct-api-port`).+- Repo: `adom-inc/adom-desktop/plugins/kicad/`