@protoboardai/ext-tscircuit 0.0.0-stage → 0.2.1

package/lib/kicad/handoff.ts

@@ -0,0 +1,112 @@
+/**
+ * The handoff record of a locked board, `<board dir>/kicad/handoff.json`
+ * (docs/specs/pcb-kicad-handoff.md §3), and the comparison check makes with
+ * it (§4).
+ *
+ * A board is locked exactly when the record exists with state "locked". It
+ * holds the model and the KiCad files as netlists at lock, so check can tell
+ * a model change (record → model) from a hand edit in KiCad (record → KiCad),
+ * and a change made on both sides (applied) from one still pending.
+ */
+import type { CapabilityResult } from "@protoboardai/core";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { diffNetlists, type Change, type Netlist } from "./netlists.ts";
+
+export const HANDOFF_SCHEMA = "protoboard.kicad-handoff/v0";
+
+export interface Handoff {
+  schema: typeof HANDOFF_SCHEMA;
+  state: "locked" | "unlocked";
+  /** UHD board module id. */
+  board: string;
+  lockedAt: string;
+  unlockedAt?: string;
+  /** Re-recorded by circuit:lock --input refresh=true. */
+  refreshedAt?: string;
+  /** Digest of the board projection (core boardNetlist) at lock. */
+  netlistDigest: string;
+  /** Digest of the outline, holes, layers and thickness at lock. */
+  boardShape: string;
+  /** The model at lock, as the export named it. */
+  model: Netlist;
+  /** The KiCad board as exported (read back from the files written). */
+  kicad: Netlist;
+  /** Differences between the two at lock (converter limits), so they are not reported as hand edits later. */
+  exportedWith?: string[];
+  /** Where the exported schematic and board disagreed at lock (KiCad parity), so check reports only new ones. */
+  parityAtLock?: string[];
+  tscircuit: { sourceDigest: string; circuit: string; core: string };
+  tools: { kicad?: string; converter: string; provider: string };
+  /** Where KiCad had each footprint at lock (board frame, by instance): export measures moves made in KiCad from here (PB-1027). */
+  positions?: Record<string, { x: number; y: number; rot: number; side: "top" | "bottom" }>;
+  /** Digest of each KiCad file as exported, by path relative to kicad/. */
+  files: Record<string, string>;
+}
+
+export const kicadDir = (dir: string) => `${dir}/kicad`;
+export const handoffFile = (dir: string) => `${kicadDir(dir)}/handoff.json`;
+
+export function readHandoff(root: string, dir: string): Handoff | undefined {
+  const f = join(root, handoffFile(dir));
+  if (!existsSync(f)) return undefined;
+  try {
+    const h = JSON.parse(readFileSync(f, "utf8")) as Handoff;
+    return h?.schema === HANDOFF_SCHEMA ? h : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export const isLocked = (root: string, dir: string) => readHandoff(root, dir)?.state === "locked";
+
+type Diagnostic = NonNullable<CapabilityResult["diagnostics"]>[number];
+
+export interface Comparison {
+  /** Model changes since lock not yet in KiCad. */
+  pending: Change[];
+  /** Model changes since lock that KiCad has too. */
+  applied: Change[];
+  /** KiCad changes since lock that are not model changes (hand edits). */
+  handEdits: Change[];
+}
+
+/** Three-way: record → model and record → KiCad, matched by change key. */
+export function compare(record: Handoff, model: Netlist, kicad: Netlist): Comparison {
+  const dm = diffNetlists(record.model, model);
+  const dk = diffNetlists(record.kicad, kicad);
+  const km = new Set(dm.map((c) => c.key));
+  const kk = new Set(dk.map((c) => c.key));
+  return { pending: dm.filter((c) => !kk.has(c.key)), applied: dm.filter((c) => kk.has(c.key)), handEdits: dk.filter((c) => !km.has(c.key)) };
+}
+
+const few = (cs: Change[], n = 6) => `${cs.slice(0, n).map((c) => c.message).join("; ")}${cs.length > n ? `; (+${cs.length - n} more)` : ""}`;
+
+/** The comparison as check findings (spec §4 codes). */
+export function comparisonDiagnostics(c: Comparison, ctx: { board: string; file: string; shapeChanged: boolean; module: string }): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const add = (severity: Diagnostic["severity"], code: string, message: string, file = ctx.file) => out.push({ code, severity, message, entity: { kind: "definition", id: ctx.module }, source: { file } });
+  const pend = (k: Change["kind"][]) => c.pending.filter((x) => k.includes(x.kind));
+  const hand = (k: Change["kind"][]) => c.handEdits.filter((x) => k.includes(x.kind));
+  const stale = pend(["part_added", "part_removed", "footprint"]);
+  if (stale.length) add("error", "CIRCUIT_KICAD_STALE", `the model changed since lock and the KiCad layout does not have it yet: ${few(stale)}. Update the board in KiCad (add or remove the parts, swap the footprint), or unlock and regenerate`);
+  if (ctx.shapeChanged) add("error", "CIRCUIT_KICAD_STALE", "the outline, mounting holes, layer count or thickness in circuit.config.ts changed since lock; change the board in KiCad to match, or unlock and regenerate");
+  const conn = pend(["connection", "net_renamed"]);
+  if (conn.length) add("warning", "CIRCUIT_KICAD_MODEL_CHANGED", `connections between existing parts changed in the model since lock, not yet in KiCad: ${few(conn)}`);
+  const fields = pend(["field"]);
+  if (fields.length) add("warning", "CIRCUIT_KICAD_FIELDS", `part fields changed in the model since lock: ${few(fields)}; update the symbols' fields in KiCad`);
+  if (c.applied.length) add("info", "CIRCUIT_KICAD_APPLIED", `${c.applied.length} model change(s) since lock are already in KiCad (${few(c.applied, 3)}); record them with \`protoboard run circuit:lock --module ${ctx.board} --input refresh=true\``);
+  const missing = hand(["part_removed"]);
+  if (missing.length) add("error", "CIRCUIT_KICAD_PART_MISSING", `KiCad lacks part(s) the model has: ${few(missing)} (deleted in KiCad?)`);
+  const extra = hand(["part_added"]);
+  if (extra.length) add("warning", "CIRCUIT_KICAD_PART_EXTRA", `KiCad has part(s) the model does not: ${few(extra)}; a fiducial, test point or added part belongs in the UHD board module first`);
+  const fp = hand(["footprint"]);
+  if (fp.length) add("warning", "CIRCUIT_KICAD_FOOTPRINT_CHANGED", `footprint(s) changed in KiCad: ${few(fp)}; the land pattern of record is the provider's (footprints.json for a project override)`);
+  const ren = hand(["net_renamed"]);
+  if (ren.length) add("warning", "CIRCUIT_KICAD_NET_RENAMED", `net(s) renamed in KiCad: ${few(ren)}; the names of record are the UHD board's nets`);
+  const moved = hand(["connection"]);
+  if (moved.length) add("error", "CIRCUIT_KICAD_NET_CHANGED", `connections changed in KiCad that the model does not have: ${few(moved)}. Change the UHD board module if the change is wanted; nothing is written back`);
+  const hf = hand(["field"]);
+  if (hf.length) add("warning", "CIRCUIT_KICAD_FIELDS", `part fields edited in KiCad: ${few(hf)}; the values of record are the UHD parts'`);
+  return out;
+}

package/lib/kicad/netlists.ts

@@ -0,0 +1,311 @@
+/**
+ * The three netlists a locked board is compared through
+ * (docs/specs/pcb-kicad-handoff.md §4), in one shape: parts by UHD instance
+ * (designator, footprint, fields) and nets as pins `<instance>.<pad>`.
+ *
+ *   model   the UHD board now, projected the way the export wrote it
+ *   kicad   the KiCad files now: the board's footprints and pads, the
+ *           schematic's symbols, and the schematic's nets from kicad-cli
+ *   record  both of these as they were at lock (handoff.json)
+ *
+ * Reading KiCad needs no KiCad: the files are S-expressions (sexpr.ts).
+ */
+import type { BoardNetlist } from "@protoboardai/core";
+import type { FootprintOverrides } from "../footprints.ts";
+import { resolveFootprint } from "../footprints.ts";
+import type { NameMap } from "../source.ts";
+import { EXTRA_FIELDS, type ComponentFields } from "./fields.ts";
+import { libItemName } from "./project.ts";
+import { child, children, head, isList, parse, property, text, type List } from "./sexpr.ts";
+
+export interface PartRecord {
+  refdes: string;
+  /** Footprint library id, `<lib>:<entry>`. */
+  footprint: string;
+  /** Value, MPN, Manufacturer, LCSC (those set). */
+  fields: Record<string, string>;
+}
+
+export interface Netlist {
+  parts: Record<string, PartRecord>;
+  /** net name → pins `<instance>.<pad>`, sorted */
+  nets: Record<string, string[]>;
+}
+
+const COMPARED_FIELDS = ["Value", "MPN", "Manufacturer", "LCSC"] as const;
+
+const sortNets = (nets: Record<string, Set<string>>): Record<string, string[]> =>
+  Object.fromEntries(
+    Object.entries(nets)
+      .filter(([, pins]) => pins.size > 0)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => [k, [...v].sort()]),
+  );
+
+/** The model's netlist, as an export of it would name parts, footprints and pads. */
+export function modelNetlist(input: { netlist: BoardNetlist; map?: NameMap; refdes: Record<string, string>; fields: Record<string, ComponentFields>; lib: string; overrides?: FootprintOverrides }): Netlist {
+  const { netlist, map, refdes, fields, lib } = input;
+  // instance → interface → pads, from the build's name map (tscircuit's pad numbers are KiCad's)
+  const pads = new Map<string, Map<string, string[]>>();
+  for (const m of Object.values(map?.components ?? {})) {
+    const byIface = new Map<string, string[]>();
+    for (const [port, iface] of Object.entries(m.ports)) {
+      if (!iface) continue;
+      const pad = port.replace(/^pin/, "");
+      byIface.set(iface, [...(byIface.get(iface) ?? []), pad]);
+    }
+    pads.set(m.instance, byIface);
+  }
+  const mapped = new Map(Object.values(map?.components ?? {}).map((m) => [m.instance, m]));
+  const parts: Record<string, PartRecord> = {};
+  for (const c of netlist.components) {
+    const entry = mapped.get(c.instance)?.footprint ?? resolveFootprint(c.instance, c.package ? { ...c.package, manufacturer: c.manufacturer } : undefined, input.overrides).entry?.id ?? c.instance;
+    const f = fields[c.instance];
+    parts[c.instance] = {
+      refdes: refdes[c.instance] ?? "",
+      footprint: `${lib}:${libItemName(entry)}`,
+      fields: Object.fromEntries(COMPARED_FIELDS.filter((k) => f?.[k]).map((k) => [k, f![k] as string])),
+    };
+  }
+  const nets: Record<string, Set<string>> = {};
+  for (const n of netlist.nets) {
+    const set = (nets[n.id] = new Set<string>());
+    for (const p of n.pins) {
+      const [inst, iface] = [p.slice(0, p.lastIndexOf(":")), p.slice(p.lastIndexOf(":") + 1)];
+      if (!inst) continue; // the board's own edge
+      const comp = netlist.components.find((c) => c.instance === inst);
+      const known = pads.get(inst)?.get(iface);
+      const pin = known ?? [comp?.pins.find((x) => x.interface === iface)?.pin ?? iface];
+      for (const pad of pin) set.add(`${inst}.${pad}`);
+    }
+  }
+  return { parts, nets: sortNets(nets) };
+}
+
+/** Which instance a KiCad part is: its UHD_Instance field, else its designator through the record. */
+const instanceOf = (fields: Record<string, string>, ref: string, byRef: Map<string, string>) => fields.UHD_Instance || byRef.get(ref) || `?${ref}`;
+
+const fieldsOfNode = (n: List): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const k of [...COMPARED_FIELDS, ...EXTRA_FIELDS]) {
+    const v = property(n, k);
+    if (v) out[k] = v;
+  }
+  return out;
+};
+
+const compared = (f: Record<string, string>) => Object.fromEntries(COMPARED_FIELDS.filter((k) => f[k]).map((k) => [k, f[k]]));
+
+/** The board file: footprints (designator, library id, fields) and the copper nets on their pads. */
+export function readBoardNetlist(pcbText: string, refdes: Record<string, string>): Netlist {
+  const pcb = parse(pcbText);
+  if (head(pcb) !== "kicad_pcb") throw new Error("not a KiCad board file (no kicad_pcb)");
+  const byRef = new Map(Object.entries(refdes).map(([i, r]) => [r, i]));
+  // KiCad 6–9 number nets: (net 3 "sda") in the header, (net 3 "sda") on pads; KiCad 10 names them: (net "sda")
+  const parts: Record<string, PartRecord> = {};
+  const nets: Record<string, Set<string>> = {};
+  for (const fp of children(pcb, "footprint")) {
+    const ref = property(fp, "Reference") ?? text(children(fp, "fp_text").find((t) => text(t.items[1]) === "reference")?.items[2]) ?? "";
+    const f = fieldsOfNode(fp);
+    // board-only footprints (mounting holes, fiducials) are not components
+    if (!f.UHD_Instance && child(fp, "attr")?.items.some((x) => text(x) === "board_only")) continue;
+    const inst = instanceOf(f, ref, byRef);
+    parts[inst] = { refdes: ref, footprint: text(fp.items[1]) ?? "", fields: compared(f) };
+    for (const pad of children(fp, "pad")) {
+      const num = text(pad.items[1]) ?? "";
+      const net = child(pad, "net");
+      if (!num || !net) continue;
+      const name = text(net.items[net.items.length - 1]) ?? "";
+      if (!name || /^unconnected-/.test(name)) continue;
+      (nets[name] ??= new Set()).add(`${inst}.${num}`);
+    }
+  }
+  return { parts, nets: sortNets(nets) };
+}
+
+/** The schematic file: its symbols (power symbols, `#…`, left out). Its nets need KiCad (readKicadNetlist). */
+export function readSchematicParts(schText: string, refdes: Record<string, string>): Record<string, PartRecord> {
+  const sch = parse(schText);
+  if (head(sch) !== "kicad_sch") throw new Error("not a KiCad schematic file (no kicad_sch)");
+  const byRef = new Map(Object.entries(refdes).map(([i, r]) => [r, i]));
+  const out: Record<string, PartRecord> = {};
+  for (const s of children(sch, "symbol")) {
+    const ref = property(s, "Reference") ?? "";
+    if (!ref || ref.startsWith("#")) continue;
+    const f = fieldsOfNode(s);
+    out[instanceOf(f, ref, byRef)] = { refdes: ref, footprint: property(s, "Footprint") ?? "", fields: compared(f) };
+  }
+  return out;
+}
+
+/** `kicad-cli sch export netlist --format kicadsexpr`: the schematic's nets (and its parts). */
+export function readKicadNetlist(netText: string, refdes: Record<string, string>): Netlist {
+  const doc = parse(netText);
+  const byRef = new Map(Object.entries(refdes).map(([i, r]) => [r, i]));
+  const refToInst = new Map<string, string>();
+  const parts: Record<string, PartRecord> = {};
+  for (const comps of children(doc, "components")) {
+    for (const c of children(comps, "comp")) {
+      const ref = text(child(c, "ref")?.items[1]) ?? "";
+      const f: Record<string, string> = {};
+      for (const p of children(c, "property")) {
+        const k = text(child(p, "name")?.items[1]);
+        const v = text(child(p, "value")?.items[1]);
+        if (k && v) f[k] = v;
+      }
+      const fieldsNode = child(c, "fields");
+      for (const fld of fieldsNode ? children(fieldsNode, "field") : []) {
+        const k = text(child(fld, "name")?.items[1]);
+        const v = fld.items.slice(2).find((x) => !isList(x));
+        if (k && v !== undefined && text(v)) f[k] = text(v)!;
+      }
+      const value = text(child(c, "value")?.items[1]);
+      if (value) f.Value = value;
+      const inst = instanceOf(f, ref, byRef);
+      refToInst.set(ref, inst);
+      parts[inst] = { refdes: ref, footprint: text(child(c, "footprint")?.items[1]) ?? "", fields: compared(f) };
+    }
+  }
+  const nets: Record<string, Set<string>> = {};
+  for (const ns of children(doc, "nets")) {
+    for (const n of children(ns, "net")) {
+      const name = text(child(n, "name")?.items[1]) ?? "";
+      if (!name || /^unconnected-/.test(name)) continue;
+      for (const node of children(n, "node")) {
+        const ref = text(child(node, "ref")?.items[1]) ?? "";
+        const pin = text(child(node, "pin")?.items[1]) ?? "";
+        if (!ref || ref.startsWith("#") || !pin) continue;
+        (nets[name] ??= new Set()).add(`${refToInst.get(ref) ?? byRef.get(ref) ?? `?${ref}`}.${pin}`);
+      }
+    }
+  }
+  return { parts, nets: sortNets(nets) };
+}
+
+// ---------------------------------------------------------------------------
+// Differences
+// ---------------------------------------------------------------------------
+
+export type ChangeKind = "part_added" | "part_removed" | "footprint" | "field" | "net_renamed" | "connection";
+
+export interface Change {
+  kind: ChangeKind;
+  /** Identity across the model and KiCad sides: the same change made on both has the same key. */
+  key: string;
+  instance?: string;
+  message: string;
+}
+
+const normNet = (s: string) => s.replace(/^\//, "").toLowerCase().replace(/[^a-z0-9]+/g, "_");
+const instOfPin = (p: string) => p.slice(0, p.lastIndexOf("."));
+
+/** pin → its net's name and its peers (pins sharing the net), over pins whose part is in `keep`; nets of one such pin dropped. */
+function groups(n: Netlist, keep: Set<string>): Map<string, { net: string; peers: string[] }> {
+  const out = new Map<string, { net: string; peers: string[] }>();
+  for (const [name, pins] of Object.entries(n.nets)) {
+    const kept = pins.filter((p) => keep.has(instOfPin(p)));
+    if (kept.length < 2) continue;
+    for (const p of kept) {
+      const prev = out.get(p);
+      const peers = kept.filter((x) => x !== p);
+      // a pin on two nets (cannot happen in copper; a hand-edited file): keep the larger group
+      if (!prev || prev.peers.length < peers.length) out.set(p, { net: name, peers });
+    }
+  }
+  return out;
+}
+
+/**
+ * Pins that changed nets from `a` to `b`. Nets are matched one to one by the
+ * pins they share (largest overlap first), so moving one pin reports that pin,
+ * not every pin of the two nets it touched. `to` identifies the destination
+ * the same way on any side: the pins of the matched net in `a`, or `new:` and
+ * the pins of a net `a` has no match for.
+ */
+function movedPins(a: Map<string, { net: string; peers: string[] }>, b: Map<string, { net: string; peers: string[] }>): { pin: string; fromNet?: string; toNet?: string; to: string; with: string[] }[] {
+  const nets = (g: Map<string, { net: string; peers: string[] }>) => {
+    const m = new Map<string, Set<string>>();
+    for (const [p, { net }] of g) (m.get(net) ?? m.set(net, new Set()).get(net)!).add(p);
+    return m;
+  };
+  const [na, nb] = [nets(a), nets(b)];
+  const pairs: { x: string; y: string; n: number }[] = [];
+  for (const [y, pins] of nb) {
+    const count = new Map<string, number>();
+    for (const p of pins) {
+      const x = a.get(p)?.net;
+      if (x !== undefined) count.set(x, (count.get(x) ?? 0) + 1);
+    }
+    for (const [x, n] of count) pairs.push({ x, y, n });
+  }
+  pairs.sort((p, q) => q.n - p.n || p.x.localeCompare(q.x) || p.y.localeCompare(q.y));
+  const match = new Map<string, string>(); // b net → a net
+  const taken = new Set<string>();
+  for (const { x, y } of pairs) if (!match.has(y) && !taken.has(x)) (match.set(y, x), taken.add(x));
+  const out: { pin: string; fromNet?: string; toNet?: string; to: string; with: string[] }[] = [];
+  for (const p of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+    const from = a.get(p)?.net;
+    const toNet = b.get(p)?.net;
+    const origin = toNet === undefined ? undefined : match.get(toNet);
+    if (from === origin && (from !== undefined || toNet === undefined)) continue;
+    const to = toNet === undefined ? "none" : origin !== undefined ? [...na.get(origin)!].sort().join("|") : `new:${[...nb.get(toNet)!].sort().join("|")}`;
+    out.push({ pin: p, fromNet: from, toNet, to, with: b.get(p)?.peers ?? [] });
+  }
+  return out;
+}
+
+const list3 = (xs: string[], n = 4) => `${xs.slice(0, n).join(", ")}${xs.length > n ? ` (+${xs.length - n})` : ""}`;
+
+/** What changed from `base` to `now`: parts, footprints, fields, renamed nets and moved pins. */
+export function diffNetlists(base: Netlist, now: Netlist): Change[] {
+  const out: Change[] = [];
+  const both = new Set(Object.keys(base.parts).filter((i) => now.parts[i]));
+  for (const i of Object.keys(now.parts).sort()) if (!base.parts[i]) out.push({ kind: "part_added", key: `part+:${i}`, instance: i, message: `${i} (${now.parts[i].refdes || "no designator"}) added` });
+  for (const i of Object.keys(base.parts).sort()) if (!now.parts[i]) out.push({ kind: "part_removed", key: `part-:${i}`, instance: i, message: `${i} (${base.parts[i].refdes}) removed` });
+  for (const i of [...both].sort()) {
+    const [a, b] = [base.parts[i], now.parts[i]];
+    if (a.footprint !== b.footprint) out.push({ kind: "footprint", key: `fp:${i}:${b.footprint}`, instance: i, message: `${i} (${b.refdes}) footprint ${a.footprint} → ${b.footprint}` });
+    for (const k of COMPARED_FIELDS) {
+      if ((a.fields[k] ?? "") !== (b.fields[k] ?? "")) out.push({ kind: "field", key: `field:${i}:${k}:${b.fields[k] ?? ""}`, instance: i, message: `${i} (${b.refdes}) ${k} "${a.fields[k] ?? ""}" → "${b.fields[k] ?? ""}"` });
+    }
+  }
+  // nets, over the parts on both sides
+  const ga = groups(base, both);
+  const gb = groups(now, both);
+  const pinSet = (n: Netlist, name: string) => (n.nets[name] ?? []).filter((p) => both.has(instOfPin(p))).join("|");
+  const renamedFrom = new Set<string>();
+  const baseByPins = new Map<string, string>();
+  for (const name of Object.keys(base.nets)) {
+    const k = pinSet(base, name);
+    if (k.includes("|")) baseByPins.set(k, name);
+  }
+  for (const name of Object.keys(now.nets).sort()) {
+    const k = pinSet(now, name);
+    const was = baseByPins.get(k);
+    if (was !== undefined && was !== name && normNet(was) !== normNet(name)) {
+      out.push({ kind: "net_renamed", key: `rename:${k}:${normNet(name)}`, message: `net ${was} renamed ${name} (${list3(k.split("|"))})` });
+      renamedFrom.add(was);
+    }
+  }
+  for (const m of movedPins(ga, gb)) {
+    out.push({ kind: "connection", key: `conn:${m.pin}:${m.to}`, instance: instOfPin(m.pin), message: `pin ${m.pin}: ${m.fromNet ?? "no net"} → ${m.toNet ?? "no net"}${m.toNet && m.with.length ? ` (with ${list3(m.with, 3)})` : ""}` });
+  }
+  return out;
+}
+
+/** The parts a schematic and a board disagree on (missing on one side, other footprint). */
+export function parityProblems(sch: Record<string, PartRecord>, pcb: Record<string, PartRecord>): string[] {
+  const out: string[] = [];
+  for (const i of Object.keys(sch).sort()) {
+    if (!pcb[i]) out.push(`${sch[i].refdes} (${i}) is in the schematic but not on the board`);
+    else if (sch[i].footprint && sch[i].footprint !== pcb[i].footprint) out.push(`${sch[i].refdes} (${i}): schematic footprint ${sch[i].footprint}, board ${pcb[i].footprint}`);
+  }
+  for (const i of Object.keys(pcb).sort()) if (!sch[i]) out.push(`${pcb[i].refdes} (${i}) is on the board but not in the schematic`);
+  return out;
+}
+
+/** Nets the schematic and the board group differently (names aside). */
+export function netParity(sch: Netlist, pcb: Netlist): string[] {
+  const keep = new Set([...Object.keys(sch.parts), ...Object.keys(pcb.parts)]);
+  return movedPins(groups(sch, keep), groups(pcb, keep)).map((m) => `pin ${m.pin}: schematic ${m.fromNet ?? "no net"}, board ${m.toNet ?? "no net"}`);
+}

package/lib/kicad/probe.cjs

@@ -0,0 +1,21 @@
+// Tool probe for kicad-cli (KiCad 10), found as lib/kicad/cli.ts finds it:
+// PROTOBOARD_KICAD_CLI, PATH, then KiCad's usual install places. Prints one
+// line; exits 1 when there is none, or when it is older than KiCad 10.
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+
+const places = [process.env.PROTOBOARD_KICAD_CLI, "kicad-cli", "/usr/bin/kicad-cli", "/usr/local/bin/kicad-cli", "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli", "C:\\Program Files\\KiCad\\10.0\\bin\\kicad-cli.exe"].filter(Boolean);
+for (const c of places) {
+  if (c !== "kicad-cli" && !existsSync(c)) continue;
+  const r = spawnSync(c, ["version"], { encoding: "utf8", timeout: 20000 });
+  const v = (r.stdout || "").trim();
+  if (r.status !== 0 || !/^\d+\./.test(v)) continue;
+  if (Number(v.split(".")[0]) < 10) {
+    console.error(`kicad-cli ${v} at ${c}: the KiCad handoff writes KiCad 10 files; install KiCad 10`);
+    process.exit(1);
+  }
+  console.log(`kicad-cli ${v} (${c})`);
+  process.exit(0);
+}
+console.error("kicad-cli not found: install KiCad 10, or set PROTOBOARD_KICAD_CLI to its kicad-cli");
+process.exit(1);