KiCad - the KiCad Bridge

@@ -1,6 +1,14 @@ # The Rust port plan -Status: proposal, written 2026-09-11 from a full audit of the 0.9.350 source, the Adom Bridge (ab) verb surface, the KiCad 10.0.6 IPC API and the KiCad 11 roadmap. Nothing here is built yet. Decisions John needs to make are collected at the end.+Written 2026-09-11 from a full audit of the 0.9.350 source, the Adom Bridge (ab) verb surface, the KiCad 10.0.6 IPC API and the KiCad 11 roadmap. John approved it the same day ("do it"). Progress is logged in the Status section right below; the decisions section at the end records what was decided.++## Status++| Date | What |+|---|---|+| 2026-09-11 | Phase 0 shipped to insiders as 0.9.351: dialog pre-emption seeding, dead PowerShell and unused modules removed. Gate on ConfRoomROG: 71 pass, 1 fail (the known idle-box foreground grant on `kicad_launch`), 15 skip. |+| 2026-09-11 | Phase 1 started. Rust workspace under `rust/` on this page: `kicad-platform` (Windows, macOS, Linux implementations behind one trait), `kicad-core`, `kicad-bridge`. 13 headless verbs (describe, status, readiness with alternatives, list_versions, diagnostics, run_drc, run_erc, the five exports, uninstall). Windows exe is 598 KB with no runtime; smoke-tested on ConfRoomROG: KiCad 10.0.5 found, DRC on a real board in 2.5 s, SVG and Gerber exports. macOS and Linux targets type-check. |+| 2026-09-11 | The four ab-core asks filed as [adom/adom-bridge#184](https://wiki.adom.inc/adom/adom-bridge/issues/184). |  ## The goal in one sentence @@ -171,6 +179,16 @@ Three paths exist today and readiness should say so instead of reporting `not_in  Phase 1 adds a `backend` field to every headless verb (`local | service | target:<name>`) with `local` as default, and a `kicad_readiness.alternatives` block that lists the three paths with a one-line hint each when no local KiCad is found. +## One codebase, three operating systems++Kyle owns the macOS build of Hydrogen and Adom Bridge and will take this codebase to macOS; Barrett was doing the Ubuntu build of the bridge. The port is laid out so each OS compiles its own implementation in at build time and nobody forks:++- **`crates/kicad-platform`** is the only OS-specific crate. It defines one `Platform` trait (install discovery, settings and documents directories, quiet child processes, and later window control, UI automation, dialog sweep, focus etiquette, silent install) and three files: `windows.rs`, `macos.rs`, `linux.rs`. `cfg(target_os)` selects exactly one. Per-OS crates (winreg and later the windows and uiautomation crates; objc2 and accessibility on macOS; x11rb, zbus or atspi on Linux) are declared in that crate's `[target.'cfg(...)'.dependencies]` tables and nowhere else.+- **`crates/kicad-core`** (detection ordering, kicad-cli runner and parsers, file editing, the IPC client) and **`crates/kicad-bridge`** (server, catalog, verbs) never touch the OS directly. They call `kicad_platform::native()`.+- **Honest gaps.** A verb that needs something an OS has not implemented yet returns `errorCode: not_supported_on_platform` with the OS and the owner's name. Readiness and diagnostics carry a `platform.capabilities` block (kicadCli, windowControl, uiAutomation, dialogSweep, focusEtiquette, ipcApi, silentInstall) so an AI can tell what this build can do before it calls anything.+- **Today.** The headless half (kicad-cli, file editing, detection, settings paths) already works on all three because it only needs the paths each OS file provides. `cargo check --target aarch64-apple-darwin` and `--target x86_64-unknown-linux-musl` pass from the container; the Windows binary cross-builds from Linux with mingw-w64.+- **Publishing.** ab manifests are single-zip, so each OS ships from its own build until per-platform manifests exist. Windows first; macOS and Linux follow when their platform files reach parity, gated by the same verb runner.+ ## Target architecture  ```@@ -233,13 +251,13 @@ Total: roughly 18 to 21 weeks of one AI thread's time with human test time on th - **Single zip, one OS.** ab manifests have no per-platform assets, so the Rust bridge is Windows-only until per-platform manifests exist. macOS keeps the Python bridge (its window code is `open -a` and osascript, a fraction of the Windows surface). - **KiCad 11 timing is unannounced.** The plan makes us independent of SWIG before it matters. -## Decisions for John+## Decisions (recorded 2026-09-11) -1. **Windows first, macOS stays on Python until per-platform manifests land.** Recommended yes.-2. **Move the focus guardian into ab** (ab-core thread owns it, every bridge benefits) or keep it in the KiCad binary. Recommended: propose it to ab-core now; port it into the binary in phase 4 either way so we are not blocked.-3. **Audio verb in ab** for narration, or WinRT MediaPlayer in the binary. Recommended: ask ab, fall back to WinRT.-4. **Parallel threads.** One thread does the whole port in about four months; two threads finish in about two and a half.-5. **Source hosting.** The Rust source goes on the same wiki page as the Python source today, with `target/` ignored so the 50 MB registry limit never bites.+1. **Windows first**, with the platform crate ready for Kyle (macOS) and Barrett (Linux) to fill in. Their builds are not part of this thread's work; being ready for them is.+2. **Focus guardian**: proposed to ab-core as [adom/adom-bridge#184](https://wiki.adom.inc/adom/adom-bridge/issues/184); ported into the binary in phase 4 regardless so nothing blocks.+3. **Audio**: asked of ab in the same issue; WinRT MediaPlayer in the binary as the fallback.+4. **Threads**: this thread runs the port; a second thread can take phases 3 and 4 once the skeleton is stable.+5. **Source**: on this page under `rust/`, `target/` ignored.  ## Related