service-kicad

@@ -1,59 +1,225 @@-# service-kicad — Shared Headless KiCad CLI+# service-kicad — shared headless KiCad -Rust CLI that wraps the remote service-kicad container. The production-URL is baked into the binary at compile time — no env vars needed.+**The shared service.** `service-kicad` is a headless KiCad 10 service Adom+runs as free shared infrastructure — DRC/ERC, Gerber/SVG/STEP export,+Altium library conversion, and symbol/footprint/3D-model lookups with no+local KiCad install. Every Adom tool and user container shells to the+`service-kicad` CLI rather than hitting the HTTP API raw. -## Install+**Fair use.** It's free today and we intend to keep it that way. We reserve+the right to rate-limit or block abusive usage, and if scale ever demands+it, heavy usage may become paid. Nothing about your designs is retained+beyond the job lifecycle. -Paste into Claude Code:+**Self-hosting.** The service is a single container you can run yourself —+full source on this page (Files tab / `adom-wiki repo clone+adom/service-kicad`). If the shared instance doesn't fit, spin up your own+and point the CLI at it. See [Self-hosting](#self-hosting) below. -```-Install service-kicad. Download from-https://wiki-ufypy5dpx93o.adom.cloud/static/apps/service-kicad/service-kicad-→ /tmp/service-kicad, chmod +x, sudo install to /usr/local/bin/service-kicad,-then run `service-kicad install` to deploy the skill + bash completions.-Verify with `service-kicad health`.+## Install++```bash+adom-wiki pkg install adom/service-kicad ``` -Or manually:+That installs the CLI to your PATH, the Claude skill, and bash+completions. Verify:  ```bash-curl -fsSL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/service-kicad/service-kicad \-  -o /tmp/service-kicad && chmod +x /tmp/service-kicad \-  && sudo install -m 0755 /tmp/service-kicad /usr/local/bin/service-kicad \-  && service-kicad install+service-kicad health ```  ## Usage  ```bash-# Health check-service-kicad health+# Health / diagnostics+service-kicad health                  # service + KiCad version + running git_sha+service-kicad config                  # effective service URL and where it came from  # DRC / ERC service-kicad pcb drc board.kicad_pcb service-kicad sch erc schematic.kicad_sch -# Export+# PCB export service-kicad pcb export gerbers board.kicad_pcb --out ./gerbers/-service-kicad pcb export glb board.kicad_pcb --out board.glb service-kicad pcb export step board.kicad_pcb --out board.step+service-kicad pcb export svg board.kicad_pcb --out board.svg+service-kicad pcb export svg board.kicad_pcb --layers F.Cu,F.Mask,Edge.Cuts --out board.svg++# Schematic export+service-kicad sch export svg schematic.kicad_sch --out sch.svg+service-kicad sch export svg-project ./project-dir --out ./sheets/   # hierarchical: one SVG per sheet+service-kicad sch export pdf schematic.kicad_sch --out sch.pdf+service-kicad sch export bom schematic.kicad_sch --out bom.csv -# Symbol / footprint SVG+# Altium → KiCad library conversion+service-kicad altium sym part.SchLib      # → part.kicad_sym+service-kicad altium fp part.PcbLib       # → part.kicad_mod++# Symbol / footprint / 3D lookups (KiCad official libraries) service-kicad sym svg Connector_Generic Conn_01x04 service-kicad fp svg Connector_PinHeader_2.54mm PinHeader_1x04_P2.54mm_Vertical--# 3D model download service-kicad model fetch Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x04_P2.54mm_Vertical.step ``` -## Override URL (dev only)+### 3D models: STEP is the contract++For board 3D models, export **STEP** here and convert with+`adom-step2glb` / service-occt — that is the only supported GLB path.+KiCad-native GLB export is gated (page issue #106) because it bypasses the+molecule pipeline: no MP-marker anchoring, no gold machine-pin material,+no meter normalization, no footprint emit. The endpoints remain for+legacy callers, but every GLB that leaves this service is+provenance-stamped in its glTF JSON+(`asset.extras.adom.provenance = "kicad-native-glb"`, plus an+`X-Adom-Provenance` response header) so importers and humans can catch it+downstream, and the CLI verb requires an explicit+`--i-know-this-skips-the-pipeline` acknowledgment.++The shared instance carries the official KiCad symbol/footprint/packages3D+libraries only. Adom's machine-pin 3D libraries are **not** installed+server-side, so molecule STEP export for boards using Adom library parts+still runs on the laptop (see the `kicad-export-molecule` skill); boards+built purely from the official libraries can use `pcb export step` here+directly.++## Service URLs — channels++Two channels run in parallel. The default URL serves KiCad 10; KiCad 9 is+opt-in for callers that need to pin to the older toolchain.++| Channel | URL | KiCad | When to use |+|---|---|---|---|+| **default (v10)** | `https://kicad-rk5ue5pcfemi.adom.cloud` | 10.0.x | every consumer, all the time |+| **v9 fallback** | `https://kicad-v9-7f1gq8j5ohbq.adom.cloud` | 9.0.x | only if your project explicitly pins to v9 (e.g., file-format compat for an older kicad-symbols revision) |++The default URL is baked into the CLI. To pin a run to v9 (or any other+instance):  ```bash-export KICAD_SERVICE_API=http://127.0.0.1:8780+SERVICE_KICAD_URL=https://kicad-v9-7f1gq8j5ohbq.adom.cloud service-kicad pcb drc board.kicad_pcb ``` -## Container+(`KICAD_SERVICE_API` is honored as a legacy alias.) Health probe shape is+the same on both channels; `kicad_version` and `git_sha` differ:++```bash+curl -sf https://kicad-rk5ue5pcfemi.adom.cloud/health+# → {"git_sha":"…","git_sha_short":"…","kicad_version":"10.0.2","ok":true,"service":"service-kicad","version":"1.1.0"}+``` -Production: `https://kicad-rk5ue5pcfemi.adom.cloud` (KiCad 10.0.2,-56 cores, 125 GB RAM, auto-deploys from `adom-inc/service-kicad` main).+## Self-hosting++The whole service is one container: a Rust API binary shelling to+`kicad-cli`, plus the official KiCad libraries. Everything you need is in+this repo.++1. **Provision a container.** Follow the+   [standalone service guide](https://wiki.adom.inc/adom/standalone-service)+   for creating a dedicated lightweight container with SSH. Any Ubuntu+   24.04 host with ~10 GB free (KiCad + libraries) works too.+2. **Get the source and deploy.**+   ```bash+   adom-wiki repo clone adom/service-kicad && cd service-kicad+   bash deploy.sh+   ```+   `deploy.sh` is the canonical one-shot setup: installs KiCad 10 from the+   official PPA, overlays the upstream symbol/footprint/packages3D+   libraries (see [library staleness](#library-staleness) below), builds+   the API, and installs the watchdog cron. `Dockerfile` documents the+   same steps as a reference image. KiCad 9 fallback: `deploy-v9.sh` on a+   separate host — the two PPAs ship the same `kicad` package, so it's one+   channel per host.+3. **The watchdog keeps it running.** `watchdog.sh` (cron, every 2 min)+   fetches origin, rebuilds on new commits, and health-checks the running+   service. It kills the old process by `/proc/PID/exe` readlink — not+   `pkill -f` path matching, which self-kills SSH sessions and can match+   unrelated processes. Keep that.+4. **Expose the port.** The API listens on `PORT` (default 8780). On an+   Adom container: `adom-cli carbon containers port-add <slug> --port 8780+   --prefix kicad`. Health check: `curl <url>/health` — `git_sha` tells+   you exactly what's deployed.+5. **Point the CLI at it.**+   ```bash+   export SERVICE_KICAD_URL=https://your-instance.example+   service-kicad config   # confirms: source = SERVICE_KICAD_URL env+   ```+   Same commands, your container.++### Service configuration++| Env var | Default | Purpose |+|---|---|---|+| `PORT` | `8780` | API listen port |+| `KICAD_CLI` | `kicad-cli` | kicad-cli binary to shell to |+| `KICAD_SYMBOLS_DIR` | `/usr/share/kicad/symbols` | symbol library root |+| `KICAD_FOOTPRINTS_DIR` | `/usr/share/kicad/footprints` | footprint library root |+| `KICAD_PACKAGES3D_DIR` | `/usr/share/kicad/3dmodels` | 3D model library root |++Uploads are capped at 100 MB per request.++### Library staleness++The Ubuntu apt packages of `kicad-symbols` / `kicad-footprints` /+`kicad-packages3d` lag the upstream KiCad GitHub repos by *years* (24.04+ships a ~2020 snapshot). `Dockerfile` + `deploy.sh` overlay shallow git+clones of the upstream libraries at `/opt/kicad-*-upstream`, point the+`KICAD_*_DIR` env vars at them, and refresh weekly via+`/etc/cron.d/kicad-lib-pull`. The apt packages stay installed — they bring+`kicad-cli` itself — but their library data is shadowed by the upstream+clones.++## HTTP API++Full contract: [docs/service-kicad-api.md](docs/service-kicad-api.md).+Prefer the CLI over curling the API — it has the production URL baked in+and insulates you from container reprovisions. Major endpoints:++| Endpoint | Body | Returns |+|---|---|---|+| `GET  /health`                              | — | `{ok, service, version, kicad_version, git_sha}` |+| `GET  /version`                             | — | `{service, version, api_version, git_sha}` |+| `POST /kicad/pcb/drc`                       | `.kicad_pcb` bytes | JSON |+| `POST /kicad/sch/erc`                       | `.kicad_sch` bytes | JSON |+| `POST /kicad/pcb/export/svg?side=top\|bottom&layers=F.Cu,…` | `.kicad_pcb` bytes | `image/svg+xml` |+| `POST /kicad/pcb/export/gerbers`            | `.kicad_pcb` bytes | tarball |+| `POST /kicad/pcb/export/step`               | `.kicad_pcb` bytes | `model/step` |+| `POST /kicad/pcb/export/glb[-zup]`          | `.kicad_pcb` bytes | `model/gltf-binary` — legacy; provenance-stamped, see [STEP is the contract](#3d-models-step-is-the-contract) |+| `POST /kicad/pcb/export/glb-package[-zup]`  | tar.gz (board + 3dmodels) | `model/gltf-binary` — legacy; provenance-stamped |+| `POST /kicad/sch/export/svg`                | `.kicad_sch` bytes | `image/svg+xml` |+| `POST /kicad/sch/export/svg-project`        | tar (project dir) | tar of per-sheet SVGs |+| `POST /kicad/sch/export/pdf`                | `.kicad_sch` bytes | `application/pdf` |+| `POST /kicad/sch/export/bom`                | `.kicad_sch` bytes | `text/csv` |+| `POST /kicad/altium/sym`                    | `.SchLib` bytes | `.kicad_sym` bytes |+| `POST /kicad/altium/fp`                     | `.PcbLib` bytes | `.kicad_mod` bytes |+| `GET  /sym/export/svg/:library/:name`       | — | `image/svg+xml` |+| `GET  /fp/export/svg/:library/:name`        | — | `image/svg+xml` |+| `GET  /models/<path>`                       | — | static file from `kicad-packages3d` |+| `GET  /footprints/<path>`                   | — | static file from `kicad-footprints` |+| `GET  /symbols/<path>`                      | — | static file from `kicad-symbols` |++## Design doctrine++- **Tool-agnostic by design.** Zero `aci-*` deps — nothing in this+  repo imports `adom-circuit`. Bug fixes land once for every consumer.+- **Body is the file.** Every POST endpoint takes the raw `.kicad_*`+  bytes as the request body, not a multipart upload. Keeps clients+  trivial (`curl --data-binary @file`).+- **Shell out; don't reimplement.** `kicad-cli` is the source of truth.+  We're a thin HTTP layer over subprocess calls, not a KiCad reimpl.+- **All exports pass `KICAD{6,7,8,9,10}_3DMODEL_DIR`** so component 3D+  models resolve during STEP export, regardless of which kicad-cli+  major version is on the host.+- **Static library mounts are read-only** — nobody writes back through+  the service.+- **`$PORT` configurable** so the same binary can host side-by-side+  dev/prod instances on one container.++## Contributing++Every change on `main` triggers the prod watchdog: on the next 2-minute+cycle the container pulls, rebuilds, and relaunches — `/health`'s+`git_sha` confirms what's actually serving. Breaking changes bump+`api_version` in `service.json` + `docs/service-kicad-api.md`. Open PRs+against the wiki page (`adom-wiki pr`) so review happens where users+look; the GitHub repo (`adom-inc/service-kicad`) is the working origin.

@@ -2,12 +2,13 @@ name: service-kicad description: >   Shared headless KiCad service for every Adom tool and user container.-  Run DRC, ERC, export to SVG/Gerber/STEP/GLB, look up symbols,-  footprints, and 3D models — all via the `service-kicad` CLI.-  No local KiCad install needed.+  Run DRC, ERC, export to SVG/Gerber/STEP, convert Altium libraries,+  look up symbols, footprints, and 3D models — all via the+  `service-kicad` CLI. No local KiCad install needed.   Trigger words: kicad service, service-kicad, kicad-cli remote,-  kicad DRC, kicad ERC, export gerbers, export step, export glb,-  kicad-packages3d, shared kicad library, headless kicad.+  kicad DRC, kicad ERC, export gerbers, export step, board svg,+  schematic svg, altium to kicad, schlib, pcblib, kicad-packages3d,+  shared kicad library, headless kicad. ---  # service-kicad — shared headless KiCad@@ -18,67 +19,85 @@ shells to the `service-kicad` CLI instead of installing KiCad locally.  ## Installation -Paste into Claude Code:--```-Install service-kicad. Download the binary from-https://wiki.adom.inc/static/apps/service-kicad/service-kicad-→ /tmp/service-kicad, chmod +x, sudo install to /usr/local/bin/service-kicad,-then run `service-kicad install` to deploy the skill + bash completions.-Verify with `service-kicad health`.+```bash+adom-wiki pkg install adom/service-kicad ``` +Installs the CLI, this skill, and bash completions. Verify with+`service-kicad health`.+ ## When to use  **Always use the `service-kicad` CLI** — never curl the service URL-directly, and never `import` or `require` `kicad-api-client.js` from-Node.js scripts. The CLI has the production endpoint baked in and-insulates you from container reprovisions that change the URL.+directly. The CLI has the production endpoint baked in and insulates you+from container reprovisions that change the URL.  ```bash # Good — shell to the CLI service-kicad pcb drc board.kicad_pcb-service-kicad pcb export glb board.kicad_pcb -o board.glb+service-kicad pcb export step board.kicad_pcb --out board.step service-kicad sym svg Connector_Generic Conn_01x04  # Bad — hardcoded URL, breaks on reprovision curl -X POST --data-binary @board.kicad_pcb https://...adom.cloud/kicad/pcb/drc--# Bad — JS client is for browser-only webviews, not Node.js-import { pcbDrc } from './kicad-api-client.js'; ```  **Don't** apt-install `kicad` on your container just to render one SVG. +**Board GLB is not exported here.** For a board 3D model, export STEP and+convert with `adom-step2glb` (molecule mode when the board has machine+pins). KiCad-native GLB bypasses the molecule pipeline — no anchoring,+gold pins, normalization, or footprint emit — and is gated behind+`--i-know-this-skips-the-pipeline`; anything it produces is+provenance-stamped (`asset.extras.adom.provenance = "kicad-native-glb"`).+ ## CLI commands  ```bash # Diagnostics-service-kicad health+service-kicad health          # includes running git_sha service-kicad version-service-kicad config+service-kicad config          # effective URL + which override is active  # PCB service-kicad pcb drc board.kicad_pcb [--format json] [--out report.json]-service-kicad pcb export svg board.kicad_pcb [--out board.svg]+service-kicad pcb export svg board.kicad_pcb [--side top|bottom] [--layers F.Cu,F.Mask,Edge.Cuts] [--out board.svg] service-kicad pcb export gerbers board.kicad_pcb [--out ./gerbers/]-service-kicad pcb export step board.kicad_pcb [--out board.step]-service-kicad pcb export glb board.kicad_pcb [--out board.glb]+service-kicad pcb export step board.kicad_pcb [--out board.step] [-F --include-pads ...]  # Schematic service-kicad sch erc schematic.kicad_sch [--format json] service-kicad sch export svg schematic.kicad_sch [--out sch.svg]+service-kicad sch export svg-project ./project-dir [--out ./sheets/]   # hierarchical: one SVG per sheet service-kicad sch export pdf schematic.kicad_sch [--out sch.pdf] service-kicad sch export bom schematic.kicad_sch [--out bom.csv] -# Symbol / footprint SVG+# Altium → KiCad library conversion+service-kicad altium sym part.SchLib [--out part.kicad_sym]+service-kicad altium fp part.PcbLib [--out part.kicad_mod]++# Symbol / footprint SVG + raw fetch service-kicad sym svg LIBRARY NAME [--out symbol.svg]+service-kicad sym fetch LIBRARY [--out lib.kicad_sym] service-kicad fp svg LIBRARY NAME [--out footprint.svg]+service-kicad fp fetch LIBRARY NAME [--out fp.kicad_mod] -# 3D model download+# 3D model download (official kicad-packages3d) service-kicad model fetch PATH [--out model.step] ``` +## Pointing at another instance (v9 pin, self-host)++```bash+export SERVICE_KICAD_URL=https://kicad-v9-7f1gq8j5ohbq.adom.cloud   # KiCad 9 fallback channel+export SERVICE_KICAD_URL=https://your-own-instance.example          # self-hosted+```++`service-kicad config` shows which URL is in effect and why.+(`KICAD_SERVICE_API` still works as a legacy alias.) Self-hosting is a+one-script deploy — see the README on the wiki page+(`adom-wiki repo clone adom/service-kicad`).+ ## Troubleshooting  | Exit | Meaning | Fix |@@ -88,9 +107,3 @@ service-kicad model fetch PATH [--out model.step] | **2** | service unreachable | `service-kicad health` to confirm; the container may be restarting | | **3** | auth failed (401/403) | `adom-cli auth refresh` | | **4** | service-side error | CLI prints stderr; usually input-specific |--## Override URL (dev only)--```bash-export KICAD_SERVICE_API=http://127.0.0.1:8780-```