@huaqiu/dsh-kicad 0.4.2

package/lib/index.mjs

@@ -0,0 +1,957 @@
+import { getLogger } from "@huaqiu/dsh-plugin-log";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_DIAGNOSTIC_TIMEOUT_MS = 15e3;
+/** `refill_zones.py` polls zone fills; the script itself documents ~120 s. */
+const DEFAULT_REFILL_TIMEOUT_MS = 15e4;
+function firstNonEmpty(...values) {
+	for (const value of values) if (typeof value === "string" && value.trim().length > 0) return value;
+}
+/**
+* Resolve the effective configuration.
+*
+* Precedence matches the rest of the Huaqiu DSH package set: explicit plugin
+* config wins over the environment, which wins over the default.
+*/
+function resolveKicadConfig(input = {}) {
+	const pythonPath = firstNonEmpty(input.pythonPath, process.env["DSH_KICAD_PYTHON"]) ?? "python3";
+	const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const diagnosticTimeoutMs = input.diagnosticTimeoutMs ?? DEFAULT_DIAGNOSTIC_TIMEOUT_MS;
+	const refillTimeoutMs = input.refillTimeoutMs ?? DEFAULT_REFILL_TIMEOUT_MS;
+	return {
+		pythonPath,
+		...input.skillsDir ? { skillsDir: input.skillsDir } : {},
+		timeoutMs,
+		diagnosticTimeoutMs,
+		refillTimeoutMs
+	};
+}
+/** Whether any host configuration was supplied (used for startup logging). */
+function hasHostConfig(input = {}) {
+	return Boolean(input.pythonPath ?? process.env["DSH_KICAD_PYTHON"] ?? input.skillsDir ?? process.env["DSH_KICAD_SKILLS_DIR"]);
+}
+//#endregion
+//#region src/scripts.ts
+/**
+* Every bundled script, keyed by id.
+*
+* Mirrors `skills/kicad-ipc/scripts/` 1:1. Adding a script to the skill means
+* adding it here (and exposing it in `./tools.ts`) — the bundling test asserts
+* that all three stay consistent.
+*/
+const KICAD_SCRIPTS = {
+	diagnose_ipc_connection: {
+		id: "diagnose_ipc_connection",
+		file: "diagnose_ipc_connection.py",
+		summary: "Check the KiCad IPC connection, API version and open board.",
+		effect: "read",
+		supportsSave: false
+	},
+	verify_live_ipc: {
+		id: "verify_live_ipc",
+		file: "verify_live_ipc.py",
+		summary: "Live create/update/clone/zone/delete smoke test inside one dropped commit.",
+		effect: "probe",
+		supportsSave: false
+	},
+	create_track: {
+		id: "create_track",
+		file: "create_track.py",
+		summary: "Create one straight track on an existing net.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	create_via: {
+		id: "create_via",
+		file: "create_via.py",
+		summary: "Create one through via on an existing net.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	update_selected_track_width: {
+		id: "update_selected_track_width",
+		file: "update_selected_track_width.py",
+		summary: "Resize the currently selected tracks and arc tracks.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	remove_selected_items: {
+		id: "remove_selected_items",
+		file: "remove_selected_items.py",
+		summary: "Delete the current KiCad selection.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	move_rotate_footprint: {
+		id: "move_rotate_footprint",
+		file: "move_rotate_footprint.py",
+		summary: "Move and/or rotate one footprint selected by reference.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	add_footprint_from_board_template: {
+		id: "add_footprint_from_board_template",
+		file: "add_footprint_from_board_template.py",
+		summary: "Clone an on-board footprint as a template for a new reference.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	create_copper_zone: {
+		id: "create_copper_zone",
+		file: "create_copper_zone.py",
+		summary: "Create an unfilled copper zone from a closed polygon.",
+		effect: "mutate",
+		supportsSave: true
+	},
+	refill_zones: {
+		id: "refill_zones",
+		file: "refill_zones.py",
+		summary: "Wait for existing copper zone fills to complete.",
+		effect: "mutate",
+		supportsSave: true
+	}
+};
+/** The bundled script ids, in registration order. */
+const KICAD_SCRIPT_IDS = Object.keys(KICAD_SCRIPTS);
+/**
+* Look up one script by id.
+* @throws when the id is not part of the bundled set.
+*/
+function kicadScript(id) {
+	const script = KICAD_SCRIPTS[id];
+	if (!script) throw new Error(`@huaqiu/dsh-kicad: unknown bundled KiCad script "${id}"`);
+	return script;
+}
+/** The canonical skill directory name shipped by this package. */
+const KICAD_SKILL_NAME = "kicad-ipc";
+//#endregion
+//#region src/paths.ts
+/**
+* Resolution of the bundled KiCad skill directory at runtime.
+*
+* The skill ships inside the installed package (`<pkg>/skills/kicad-ipc/`), not
+* beside the source tree, so it is located relative to the loaded module. That
+* makes one resolver correct for every install shape:
+*
+*   - built artifact:   `<pkg>/lib/index.mjs`   -> `<pkg>/skills/kicad-ipc`
+*   - source (vitest):  `<pkg>/src/index.ts`    -> `<pkg>/skills/kicad-ipc`
+*   - npm / git install: identical to the built artifact case
+*
+* `skills` must stay in `package.json` `files[]` or npm strips it and this
+* resolver fails loudly — which is the intended signal, because a `dsh-kicad`
+* without its skill is a broken delivery boundary.
+*
+* @module
+*/
+/**
+* Absolute path of the bundled `kicad-ipc` skill directory.
+*
+* Resolution order: an explicit override (config / `DSH_KICAD_SKILLS_DIR`),
+* then the package-relative location.
+*
+* @param moduleUrl - `import.meta.url` of the calling module.
+* @param override - explicit directory (plugin config or env var).
+* @returns the resolved directory, whether or not it exists yet.
+*/
+function resolveSkillDir(moduleUrl, override) {
+	if (override && override.trim().length > 0) return resolve(override);
+	const envOverride = process.env["DSH_KICAD_SKILLS_DIR"];
+	if (envOverride && envOverride.trim().length > 0) return resolve(envOverride);
+	const here = dirname(new URL(moduleUrl).pathname);
+	return resolve(here, "..", "skills", KICAD_SKILL_NAME);
+}
+/**
+* Resolve the skill directory and assert the skill is actually present.
+*
+* @throws when `SKILL.md` is missing — this is a packaging failure, not a
+* runtime condition, so it must be loud rather than silently degraded.
+*/
+function requireSkillDir(moduleUrl, override) {
+	const dir = resolveSkillDir(moduleUrl, override);
+	const skillFile = join(dir, "SKILL.md");
+	if (!existsSync(skillFile)) throw new Error(`@huaqiu/dsh-kicad: bundled skill missing at ${skillFile}. The installed package is incomplete — reinstall @huaqiu/dsh-kicad so that its skills/ directory is present.`);
+	return dir;
+}
+/** Absolute path of the bundled Python script directory. */
+function scriptsDir(skillDir) {
+	return join(skillDir, "scripts");
+}
+//#endregion
+//#region src/ipc.ts
+/**
+* KiCad IPC adapter.
+*
+* ── Boundary (task: dsh-kicad-skill-plugin §13) ──────────────────────────────
+*
+*   DSH tool  ->  KiCad IPC adapter (this module)  ->  bundled script  ->  KiCad
+*
+* This module is the *only* place that knows how a KiCad capability is reached.
+* It does not implement KiCad IPC and must never grow a second, competing
+* representation of board state: every call returns what KiCad said, verbatim
+* (§12 — KiCad is the single source of truth).
+*
+* The adapter deliberately runs the migrated `kicad-agent` scripts rather than
+* re-implementing the protocol in TypeScript. Those scripts are the preserved
+* implementation: they own `kipy` usage, commit/rollback, unit conversion and
+* post-mutation verification. Rewriting them would be a redesign (§27).
+*
+* @module
+*/
+/**
+* Run one bundled KiCad script.
+*
+* Never throws for script-level failures — the outcome is reported, so a
+* missing `kipy` or a closed KiCad degrades into a typed error the agent can
+* act on instead of crashing the plugin. It only throws when the script itself
+* is not part of the package.
+*/
+async function runKicadScript(options) {
+	const { scriptsDir, pythonPath, script, args = [], timeoutMs, signal } = options;
+	const argv = [join(scriptsDir, script.file), ...args];
+	return new Promise((resolvePromise) => {
+		let child;
+		try {
+			child = spawn(pythonPath, argv, {
+				cwd: scriptsDir,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			resolvePromise({
+				script: script.id,
+				exitCode: null,
+				stdout: "",
+				stderr: String(err?.message ?? err),
+				argv: [pythonPath, ...argv],
+				timedOut: false
+			});
+			return;
+		}
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let settled = false;
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			resolvePromise(result);
+		};
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+			setTimeout(() => {
+				if (!settled) child.kill("SIGKILL");
+			}, 2e3).unref();
+		}, timeoutMs);
+		const onAbort = () => {
+			timedOut = true;
+			child.kill("SIGTERM");
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		child.stdout?.setEncoding("utf8");
+		child.stderr?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.on("error", (err) => {
+			finish({
+				script: script.id,
+				exitCode: null,
+				stdout,
+				stderr: stderr || String(err?.message ?? err),
+				argv: [pythonPath, ...argv],
+				timedOut
+			});
+		});
+		child.on("close", (code) => {
+			finish({
+				script: script.id,
+				exitCode: code,
+				stdout: stdout.trim(),
+				stderr: stderr.trim(),
+				argv: [pythonPath, ...argv],
+				timedOut
+			});
+		});
+	});
+}
+/**
+* Translate a raw run into a semantic error, or `undefined` on success.
+*
+* Exit codes are part of the scripts' contract:
+*
+*   - `diagnose_ipc_connection.py`: 0 ok, 1 unreachable, 2 `kipy` missing,
+*     3 API version mismatch, 4 no board open.
+*   - every argparse script: 2 = rejected arguments (KiCad untouched).
+*   - anything else non-zero: a real KiCad/script failure.
+*/
+function classifyRun(run) {
+	if (run.timedOut) return {
+		kind: "DEADLINE_EXCEEDED",
+		message: `KiCad script "${run.script}" did not finish within its timeout. KiCad may be busy (a GUI operation in progress); retry a read once, and re-read board state before retrying a write.`
+	};
+	if (run.exitCode === 0) return void 0;
+	if (run.exitCode === null) return {
+		kind: "FAILED_PRECONDITION",
+		message: `Could not start the Python interpreter for KiCad IPC. Set dsh-kicad \`pythonPath\` (or \$DSH_KICAD_PYTHON) to an interpreter that has the official kicad-python package installed. ${detail(run)}`
+	};
+	const stdout = run.stdout || run.stderr;
+	if (run.script === "diagnose_ipc_connection") switch (run.exitCode) {
+		case 1: return {
+			kind: "UNAVAILABLE",
+			message: "KiCad IPC is unreachable. Open PCB Editor (the project manager is not enough), enable the KiCad API service in Preferences → Plugins, restart PCB Editor, and confirm DSH runs with Full Access. A permission denial is not a retryable connection failure. " + detail(run)
+		};
+		case 2: return {
+			kind: "FAILED_PRECONDITION",
+			message: "The kicad-python package (kipy) is not installed for the configured Python interpreter. Install the version matching the running KiCad. " + detail(run)
+		};
+		case 3: return {
+			kind: "FAILED_PRECONDITION",
+			message: "kicad-python and the connected KiCad disagree on the API version. Do not work around it — install the matching official package. " + detail(run)
+		};
+		case 4: return {
+			kind: "FAILED_PRECONDITION",
+			message: "Connected to KiCad, but no .kicad_pcb is open in PCB Editor. Open a board and retry. " + detail(run)
+		};
+		default: return {
+			kind: "INTERNAL",
+			message: `KiCad IPC diagnostic failed. ${detail(run)}`
+		};
+	}
+	if (run.exitCode === 2) return {
+		kind: "INVALID_ARGUMENT",
+		message: `KiCad script "${run.script}" rejected its arguments before touching the board. Check units (mm), required flags and value ranges. ${detail(run)}`
+	};
+	if (/ModuleNotFoundError|No module named/i.test(run.stderr)) return {
+		kind: "FAILED_PRECONDITION",
+		message: "kicad-python (kipy) is missing for the configured Python interpreter. " + detail(run)
+	};
+	return {
+		kind: "INTERNAL",
+		message: `KiCad script "${run.script}" failed (exit ${run.exitCode}). The commit was dropped, so the board is unchanged. ${detail(run, stdout)}`
+	};
+}
+/** Compact, single-line diagnostic tail appended to error messages. */
+function detail(run, preferred = run.stdout || run.stderr) {
+	const text = preferred.replace(/\s+/g, " ").trim();
+	return text.length > 0 ? `KiCad said: ${text}` : "";
+}
+/** Convenience: run a script and return its semantic outcome. */
+async function invokeKicadScript(options) {
+	const script = kicadScript(options.script.id);
+	const run = await runKicadScript({
+		...options,
+		script
+	});
+	const error = classifyRun(run);
+	return {
+		ok: error === void 0,
+		run,
+		...error ? { error } : {}
+	};
+}
+//#endregion
+//#region src/tools.ts
+/**
+* Agent tools for `@huaqiu/dsh-kicad`.
+*
+* Ten tools, one per migrated `kicad-agent` script — a 1:1 preserve mapping
+* (task §10): no script is split, merged or invented. The tools are the
+* *executable interface*; `skills/kicad-ipc/SKILL.md` is the *reasoning* around
+* them (§11). Tool descriptions therefore describe board-level intent and
+* outcomes, never RPC mechanics.
+*
+* Every tool returns the same envelope:
+*
+*   { ok: true,  script, effect, output }      KiCad's own report, verbatim
+*   { ok: false, script, effect, error: { kind, message } }
+*
+* Nothing here fabricates board state. A successful call means the script
+* exited 0 and *verified* its own result inside KiCad — but per §9.5 the agent
+* must still re-read affected state after an important mutation rather than
+* trusting the return value alone.
+*
+* @module
+*/
+function asJson(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+function renderJson(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+}
+/**
+* Shared failure semantics appended to every description.
+*
+* Kept in one place so the prompt contract cannot drift between tools — the
+* same idiom as `@huaqiu/dsh-eda-host`.
+*/
+const ERROR_SEMANTICS = "IMPORTANT SEMANTICS: on ok:false, error.kind distinguishes the cause: \"FAILED_PRECONDITION\" (KiCad IPC cannot run at all — no kipy, API version mismatch, or no .kicad_pcb open; ask the user to fix the environment, do NOT retry), \"UNAVAILABLE\" (KiCad is installed but unreachable — retry once after checking PCB Editor is open, the KiCad API service is enabled, and DSH has Full Access), \"DEADLINE_EXCEEDED\" (KiCad did not answer in time — retry a read once; for a write, re-read board state first), \"INVALID_ARGUMENT\" (the board was not touched — fix units/ranges and retry), \"INTERNAL\" (KiCad or the script failed; the commit was dropped so the board is unchanged). Do NOT fabricate board state from a failed call.";
+/** Reading-only tools are safe to run alongside each other. */
+const READ_ONLY = { isConcurrencySafe: () => true };
+/** Mutating tools must never be batched into a parallel group. */
+const MUTATING = { isConcurrencySafe: () => false };
+/** Build a semantic failure envelope from a raw script run. */
+function failureEnvelope(scriptId, effect, error, run) {
+	return {
+		ok: false,
+		script: scriptId,
+		effect,
+		error,
+		...run ? { diagnostics: {
+			exitCode: run.exitCode,
+			stderr: run.stderr
+		} } : {}
+	};
+}
+/** Reject arguments the script would reject, before spawning a process. */
+function invalidArgument(scriptId, effect, message) {
+	return failureEnvelope(scriptId, effect, {
+		kind: "INVALID_ARGUMENT",
+		message
+	});
+}
+/** Format millimetres compactly without trailing float noise. */
+function mm(value) {
+	return String(Number.isInteger(value) ? value : Number(value.toFixed(6)));
+}
+/** Build `--flag value` pairs, skipping undefined optionals. */
+function flags(pairs) {
+	const argv = [];
+	for (const [flag, value] of pairs) if (value !== void 0) argv.push(flag, value);
+	return argv;
+}
+/** Build a bare `--flag` for boolean switches. */
+function switchFlag(flag, on) {
+	return on === true ? [flag] : [];
+}
+/**
+* All KiCad tools contributed by this plugin.
+*/
+function createKicadTools(env) {
+	const { scriptsDir, pythonPath, config } = env;
+	/**
+	* Shared executor: run one script and translate it into the envelope.
+	*/
+	async function run(scriptId, args, timeoutMs, signal) {
+		const script = kicadScript(scriptId);
+		const run_ = await runKicadScript({
+			scriptsDir,
+			pythonPath,
+			script,
+			args,
+			timeoutMs,
+			...signal ? { signal } : {}
+		});
+		const error = classifyRun(run_);
+		if (error) return failureEnvelope(scriptId, script.effect, error, run_);
+		return {
+			ok: true,
+			script: scriptId,
+			effect: script.effect,
+			output: run_.stdout
+		};
+	}
+	const saveFlag = (save) => switchFlag("--save", save);
+	return [
+		defineTool({
+			name: "kicad_ipc_diagnose",
+			description: "Check whether KiCad IPC is usable right now: reports the KiCad version, whether kicad-python matches it, and the name of the currently open PCB. Returns { ok, script, effect, output } where output is KiCad's own report. Use this FIRST before any KiCad read or write, and whenever a KiCad tool fails — it separates \"environment is wrong\" from \"KiCad is busy\". Read-only: it never modifies or saves the board. " + ERROR_SEMANTICS,
+			parameters: {},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.diagnosticTimeoutMs,
+			...READ_ONLY,
+			async execute(_args, exec) {
+				return asJson(await run("diagnose_ipc_connection", [], config.diagnosticTimeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_ipc_verify_live",
+			description: "Run the bundled KiCad IPC smoke test: it creates, updates, clones, zones and deletes objects — then DROPS the commit, so nothing is persisted and the board is left exactly as it was. Use it to prove a KiCad IPC installation can really mutate before attempting a real edit. Requires an existing GND net and at least one footprint on the board, and must not be run while the GUI holds unsaved edits. " + ERROR_SEMANTICS,
+			parameters: {},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(_args, exec) {
+				return asJson(await run("verify_live_ipc", [], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_create_track",
+			description: "Create one straight copper track on an EXISTING net of the open KiCad PCB. All coordinates and the width are millimetres. The net must already exist on the board — this tool never invents one; sync nets from the schematic first if a name does not resolve. The change is committed as a single KiCad undo step and verified against KiCad's returned object; the board file is only written when save is true. Returns the created track id in output. " + ERROR_SEMANTICS,
+			parameters: {
+				net: {
+					type: "string",
+					required: true,
+					description: "Existing PCB net name, e.g. \"GND\"."
+				},
+				start_x_mm: {
+					type: "number",
+					required: true,
+					description: "Start X in millimetres."
+				},
+				start_y_mm: {
+					type: "number",
+					required: true,
+					description: "Start Y in millimetres."
+				},
+				end_x_mm: {
+					type: "number",
+					required: true,
+					description: "End X in millimetres."
+				},
+				end_y_mm: {
+					type: "number",
+					required: true,
+					description: "End Y in millimetres."
+				},
+				width_mm: {
+					type: "number",
+					required: true,
+					description: "Track width in millimetres, > 0."
+				},
+				layer: {
+					type: "string",
+					description: "Target copper layer, e.g. \"F.Cu\" or \"B.Cu\". Defaults to F.Cu. Must be enabled on the board."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after a verified success. Default false — the edit stays in KiCad only."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if (!(a.width_mm > 0)) return asJson(invalidArgument("create_track", "mutate", "width_mm must be greater than 0."));
+				return asJson(await run("create_track", [...flags([
+					["--net", a.net],
+					["--start", `${mm(a.start_x_mm)},${mm(a.start_y_mm)}`],
+					["--end", `${mm(a.end_x_mm)},${mm(a.end_y_mm)}`],
+					["--width-mm", mm(a.width_mm)],
+					["--layer", a.layer]
+				]), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_create_via",
+			description: "Create one through-hole via on an EXISTING net of the open KiCad PCB. All dimensions are millimetres and must satisfy 0 < drill < diameter. The net must already exist on the board. The change is a single KiCad undo step and is verified against KiCad's returned object. Returns the created via id in output. " + ERROR_SEMANTICS,
+			parameters: {
+				net: {
+					type: "string",
+					required: true,
+					description: "Existing PCB net name, e.g. \"GND\"."
+				},
+				x_mm: {
+					type: "number",
+					required: true,
+					description: "Via X position in millimetres."
+				},
+				y_mm: {
+					type: "number",
+					required: true,
+					description: "Via Y position in millimetres."
+				},
+				diameter_mm: {
+					type: "number",
+					required: true,
+					description: "Outer diameter in millimetres."
+				},
+				drill_mm: {
+					type: "number",
+					required: true,
+					description: "Drill diameter in millimetres, must be < diameter_mm."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after a verified success. Default false."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if (!(0 < a.drill_mm && a.drill_mm < a.diameter_mm)) return asJson(invalidArgument("create_via", "mutate", "Require 0 < drill_mm < diameter_mm."));
+				return asJson(await run("create_via", [...flags([
+					["--net", a.net],
+					["--x-mm", mm(a.x_mm)],
+					["--y-mm", mm(a.y_mm)],
+					["--diameter-mm", mm(a.diameter_mm)],
+					["--drill-mm", mm(a.drill_mm)]
+				]), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_create_copper_zone",
+			description: "Create one UNFILLED copper zone on an EXISTING net of the open KiCad PCB from a closed polygon. The polygon is given as ordered vertices in millimetres; a closing vertex is added automatically. The zone is created for review only — run kicad_pcb_refill_zones afterwards to fill it. The net must already exist on the board. " + ERROR_SEMANTICS,
+			parameters: {
+				net: {
+					type: "string",
+					required: true,
+					description: "Existing PCB net name, e.g. \"GND\"."
+				},
+				points: {
+					type: "array",
+					required: true,
+					description: "Outline vertices in millimetres, in order; at least three distinct points.",
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							x_mm: {
+								type: "number",
+								required: true,
+								description: "Vertex X in millimetres."
+							},
+							y_mm: {
+								type: "number",
+								required: true,
+								description: "Vertex Y in millimetres."
+							}
+						}
+					}
+				},
+				layer: {
+					type: "string",
+					description: "Target copper layer, e.g. \"F.Cu\". Defaults to F.Cu. Must be enabled on the board."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after a verified success. Default false."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if (!Array.isArray(a.points) || a.points.length < 3) return asJson(invalidArgument("create_copper_zone", "mutate", "points needs at least three vertices."));
+				const polygon = a.points.map((p) => `${mm(p.x_mm)},${mm(p.y_mm)}`).join(";");
+				return asJson(await run("create_copper_zone", [...flags([
+					["--net", a.net],
+					["--points", polygon],
+					["--layer", a.layer]
+				]), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_add_footprint_from_template",
+			description: "Add a new footprint to the open KiCad PCB by cloning an existing on-board footprint as the template, then offsetting the clone. Use this when the user wants another instance of a footprint already placed; there is no public API to place directly from a library — report that gap instead of editing board files. new_reference must be unique on the board and different from source_reference. " + ERROR_SEMANTICS,
+			parameters: {
+				source_reference: {
+					type: "string",
+					required: true,
+					description: "Reference of the existing footprint to clone, e.g. \"R1\"."
+				},
+				new_reference: {
+					type: "string",
+					required: true,
+					description: "Unique reference for the new footprint, e.g. \"R2\"."
+				},
+				dx_mm: {
+					type: "number",
+					required: true,
+					description: "X offset from the template, millimetres."
+				},
+				dy_mm: {
+					type: "number",
+					required: true,
+					description: "Y offset from the template, millimetres."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after a verified success. Default false."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if (a.new_reference === a.source_reference) return asJson(invalidArgument("add_footprint_from_board_template", "mutate", "new_reference must differ from source_reference."));
+				return asJson(await run("add_footprint_from_board_template", [...flags([
+					["--source-reference", a.source_reference],
+					["--new-reference", a.new_reference],
+					["--dx-mm", mm(a.dx_mm)],
+					["--dy-mm", mm(a.dy_mm)]
+				]), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_move_rotate_footprint",
+			description: "Move and/or rotate one footprint on the open KiCad PCB, selected by its reference designator. Offsets are relative, rotation is incremental, in degrees. At least one of dx_mm / dy_mm / rotation_deg must be non-zero. The footprint is re-read from the board before the change, so KiCad's UUID and the rest of its properties are preserved. " + ERROR_SEMANTICS,
+			parameters: {
+				reference: {
+					type: "string",
+					required: true,
+					description: "Footprint reference designator, e.g. \"R1\". Must match exactly one footprint."
+				},
+				dx_mm: {
+					type: "number",
+					description: "Relative X offset in millimetres. Default 0."
+				},
+				dy_mm: {
+					type: "number",
+					description: "Relative Y offset in millimetres. Default 0."
+				},
+				rotation_deg: {
+					type: "number",
+					description: "Incremental rotation in degrees. Default 0."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after a verified success. Default false."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if ((a.dx_mm ?? 0) === 0 && (a.dy_mm ?? 0) === 0 && (a.rotation_deg ?? 0) === 0) return asJson(invalidArgument("move_rotate_footprint", "mutate", "Specify at least one non-zero dx_mm, dy_mm or rotation_deg."));
+				return asJson(await run("move_rotate_footprint", [...flags([
+					["--reference", a.reference],
+					["--dx-mm", mm(a.dx_mm ?? 0)],
+					["--dy-mm", mm(a.dy_mm ?? 0)],
+					["--rotation-deg", mm(a.rotation_deg ?? 0)]
+				]), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_update_selected_track_width",
+			description: "Resize the tracks and arc tracks currently SELECTED in KiCad's PCB Editor to a new width in millimetres. This operates on KiCad's live selection, so inspect the selection first and confirm it contains exactly what the user meant — the tool cannot narrow a vague scope for you. Objects are re-read from the board before the update. " + ERROR_SEMANTICS,
+			parameters: {
+				width_mm: {
+					type: "number",
+					required: true,
+					description: "Target track width in millimetres, > 0."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after a verified success. Default false."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if (!(a.width_mm > 0)) return asJson(invalidArgument("update_selected_track_width", "mutate", "width_mm must be greater than 0."));
+				return asJson(await run("update_selected_track_width", [...flags([["--width-mm", mm(a.width_mm)]]), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_refill_zones",
+			description: "Wait for the copper zones on the open KiCad PCB to be filled. Call this after reviewing a zone created with kicad_pcb_create_copper_zone, or after any edit that invalidated fills. Filling is a board mutation and can legitimately take up to about two minutes, so the timeout is longer than for the other tools. Re-read the zones afterwards to confirm. " + ERROR_SEMANTICS,
+			parameters: { save: {
+				type: "boolean",
+				description: "Persist the board to disk via KiCad once fills complete. Default false."
+			} },
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.refillTimeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				return asJson(await run("refill_zones", saveFlag(args.save), config.refillTimeoutMs, exec?.signal));
+			}
+		}),
+		defineTool({
+			name: "kicad_pcb_remove_selected_items",
+			description: "Delete everything currently SELECTED in KiCad's PCB Editor. confirm must be explicitly true — this is the guard against accidental bulk deletion. Before calling it, report to the user exactly what is selected and how many objects will go; never default the scope to \"all tracks\" or \"all objects\". Prefer keeping user hand-routing unless it is explicitly in scope. " + ERROR_SEMANTICS,
+			parameters: {
+				confirm: {
+					type: "boolean",
+					required: true,
+					description: "Must be true to authorise deleting the current selection."
+				},
+				save: {
+					type: "boolean",
+					description: "Persist the board to disk via KiCad after the deletion. Default false."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: config.timeoutMs,
+			...MUTATING,
+			async execute(args, exec) {
+				const a = args;
+				if (a.confirm !== true) return asJson(invalidArgument("remove_selected_items", "mutate", "Deletion requires confirm: true, once the selection has been reported to the user."));
+				return asJson(await run("remove_selected_items", [...switchFlag("--yes", true), ...saveFlag(a.save)], config.timeoutMs, exec?.signal));
+			}
+		})
+	];
+}
+/**
+* Names of every tool this plugin registers — asserted by the tests and used
+* for startup logging.
+*/
+function kicadToolNames() {
+	return [
+		"kicad_ipc_diagnose",
+		"kicad_ipc_verify_live",
+		"kicad_pcb_create_track",
+		"kicad_pcb_create_via",
+		"kicad_pcb_create_copper_zone",
+		"kicad_pcb_add_footprint_from_template",
+		"kicad_pcb_move_rotate_footprint",
+		"kicad_pcb_update_selected_track_width",
+		"kicad_pcb_refill_zones",
+		"kicad_pcb_remove_selected_items"
+	];
+}
+//#endregion
+//#region src/index.ts
+/** Plugin id — matches package.json. */
+const name = "@huaqiu/dsh-kicad";
+/**
+* Cordis services this half depends on.
+*
+* `skills` is REQUIRED: it is the DSH runtime's skill registry, and registering
+* the bundled `kicad-ipc` skill is this plugin's core job. Without the inject,
+* `apply()`'s `ctx.skills` access would throw
+* `cannot get property "skills" without inject`.
+*
+* `tools` is the DSH node runtime tool registry used for the KiCad tools.
+*
+* Note what is NOT here: `hqEdge`. Unlike `@huaqiu/dsh-eda-host`, this plugin
+* talks to KiCad directly, so it must never depend on the edge bridge.
+*/
+const inject = ["skills", "tools"];
+const log = getLogger("dsh-kicad");
+log.info("dsh-kicad: module loaded (waiting for the skills + tools services)");
+/**
+* Used only when the bundled SKILL.md has no parseable `description`
+* frontmatter. The real value always comes from the shipped file, so the skill
+* catalog cannot drift away from the skill body.
+*/
+const FALLBACK_SKILL_DESCRIPTION = "Operate a KiCad PCB through the official KiCad IPC API: inspect the live board and create, modify or delete objects. Use for PCB automation and autorouter-result import — not for editing .kicad_pcb files directly.";
+/**
+* Extract the `description` field from SKILL.md YAML frontmatter.
+*
+* Only the single-line form is supported (quoted or bare), which is what the
+* migrated skill uses. Returns `undefined` when absent so the caller can fall
+* back rather than registering a skill with an empty description — DSH ignores
+* frontmatter-less skills entirely, so an empty description would silently
+* break discovery.
+*/
+function skillDescription(markdown) {
+	const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
+	if (!frontmatter?.[1]) return void 0;
+	const line = frontmatter[1].split(/\r?\n/).find((candidate) => /^\s*description\s*:/.test(candidate));
+	if (!line) return void 0;
+	const unquoted = line.slice(line.indexOf(":") + 1).trim().replace(/^["']/, "").replace(/["']$/, "");
+	return unquoted.length > 0 ? unquoted : void 0;
+}
+/**
+* Read the bundled `kicad-ipc` SKILL.md.
+*
+* Exposed for tests and for callers that want the skill body without loading
+* the plugin (e.g. a packaging check).
+*/
+function readBundledSkill(moduleUrl, override) {
+	const dir = requireSkillDir(moduleUrl, override);
+	const content = readFileSync(join(dir, "SKILL.md"), "utf8");
+	return {
+		dir,
+		name: KICAD_SKILL_NAME,
+		description: skillDescription(content) ?? FALLBACK_SKILL_DESCRIPTION,
+		content
+	};
+}
+/**
+* Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
+*
+* Both halves are registered here so that one installation delivers both. The
+* skill's `resourceBase` points at the bundled skill directory, which is how
+* the agent reaches `references/ipc-pcb-workflows.md` and `scripts/` as
+* progressive-disclosure resources.
+*
+* @param ctx - real cordis context (node side).
+* @param config - plugin overlay config (python interpreter, timeouts).
+* @returns disposer — unregisters the skill and the tools on plugin dispose.
+*/
+function apply(ctx, config = {}) {
+	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-kicad requires the DSH `tools` service (ctx.tools.register).");
+	if (!ctx.skills || typeof ctx.skills.register !== "function") throw new Error("@huaqiu/dsh-kicad requires the DSH `skills` service (ctx.skills.register).");
+	const resolved = resolveKicadConfig(config);
+	const skill = readBundledSkill(import.meta.url, config.skillsDir);
+	log.info("applying dsh-kicad node half", {
+		hasConfigHost: hasHostConfig(config),
+		pythonPath: resolved.pythonPath,
+		skillDir: skill.dir,
+		timeoutMs: resolved.timeoutMs
+	});
+	const disposers = [];
+	disposers.push(ctx.skills.register({
+		name: skill.name,
+		description: skill.description,
+		content: skill.content,
+		resourceBase: {
+			kind: "directory",
+			path: skill.dir
+		}
+	}));
+	const tools = createKicadTools({
+		scriptsDir: scriptsDir(skill.dir),
+		pythonPath: resolved.pythonPath,
+		config: resolved
+	});
+	for (const tool of tools) disposers.push(ctx.tools.register(tool));
+	log.info("dsh-kicad node half ready", {
+		skill: skill.name,
+		tools: tools.length,
+		expectedTools: kicadToolNames().length
+	});
+	return () => {
+		for (const dispose of disposers.reverse()) try {
+			dispose();
+		} catch (err) {
+			log.warn("dsh-kicad disposer failed", { error: String(err?.message ?? err) });
+		}
+	};
+}
+//#endregion
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription };