@huaqiu/dsh-kicad 0.4.12 → 0.4.13

package/src/index.ts

@@ -5,19 +5,24 @@
  * This plugin ships TWO things that used to need two installations:
  *
  *   1. ten KiCad tools, registered with `ctx.tools.register(defineTool(...))`
- *   2. the `kicad-ipc` skill, registered with `ctx.skills.register(...)`
+ *   2. every bundled skill under `skills/`, registered with
+ *      `ctx.skills.register(...)` — currently `kicad-ipc` (the reasoning around
+ *      the tools) and `hardware-design-brief` (requirements → design inputs)
  *
  * Installing the Huaqiu DSH PCB/EDA bundle therefore makes KiCad agent
- * capabilities AND the skill that teaches the agent to use them available out of
+ * capabilities AND the skills that teach the agent to use them available out of
  * the box. There is no separate skill installation step, and this plugin adds no
  * second skill-registration mechanism — `ctx.skills.register()` is the DSH
  * runtime's own plugin-bundled skill channel.
  *
+ * The skill set is data, not code: `./skills.ts` owns the registry, so adding a
+ * skill from `kicad-agent` is a copy plus a registry entry.
+ *
  * ── Boundaries ──────────────────────────────────────────────────────────────
  * KiCad IPC is reached through the bundled Python scripts under
- * `skills/kicad-ipc/scripts/` (see `./ipc.ts`). This package holds no HQ Edge
- * dependency of any kind — no runtime, executable, service, port, config or
- * artifact dependency (§3, §21) — and no `@hqedge/*` import.
+ * `skills/<KICAD_SCRIPT_SKILL_ID>/scripts/` (see `./ipc.ts`). This package holds
+ * no HQ Edge dependency of any kind — no runtime, executable, service, port,
+ * config or artifact dependency (§3, §21) — and no `@hqedge/*` import.
  *
  * @module @huaqiu/dsh-kicad
  */
@@ -32,8 +37,8 @@ import {
   type KicadConfig,
   type KicadConfigInput,
 } from './config.js'
-import { requireSkillDir, resolveSkillDir, scriptsDir } from './paths.js'
-import { KICAD_SKILL_NAME } from './scripts.js'
+import { requireSkillDir, resolveSkillDir, scriptsDir, skillsRoot } from './paths.js'
+import { KICAD_SCRIPT_SKILL_ID, KICAD_SKILL_IDS, kicadSkill } from './skills.js'
 import { createKicadTools, kicadToolNames } from './tools.js'
 
 /** Plugin id — matches package.json. */
@@ -43,7 +48,7 @@ export 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,
+ * the bundled skills is this plugin's core job. Without the inject,
  * `apply()`'s `ctx.skills` access would throw
  * `cannot get property "skills" without inject`.
  *
@@ -57,9 +62,16 @@ export const inject = ['skills', 'tools'] as const
 export type { KicadConfig, KicadConfigInput } from './config.js'
 export type { KicadError, KicadErrorKind, ScriptRun } from './ipc.js'
 export type { KicadScript, ScriptEffect } from './scripts.js'
-export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, kicadScript } from './scripts.js'
+export type { KicadBundledSkill } from './skills.js'
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, kicadScript } from './scripts.js'
+export {
+  KICAD_SCRIPT_SKILL_ID,
+  KICAD_SKILL_IDS,
+  KICAD_SKILLS,
+  kicadSkill,
+} from './skills.js'
 export { kicadToolNames } from './tools.js'
-export { resolveSkillDir, requireSkillDir, scriptsDir } from './paths.js'
+export { resolveSkillDir, requireSkillDir, scriptsDir, skillsRoot } from './paths.js'
 export { runKicadScript, classifyRun, invokeKicadScript } from './ipc.js'
 export { createKicadTools } from './tools.js'
 
@@ -110,21 +122,11 @@ const log = getLogger(COMPONENT)
 // `@huaqiu/dsh-eda-host`.
 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
+ * migrated skills use. 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.
@@ -141,31 +143,48 @@ export function skillDescription(markdown: string): string | undefined {
   return unquoted.length > 0 ? unquoted : undefined
 }
 
-/**
- * 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).
- */
-export function readBundledSkill(moduleUrl: string, override?: string): {
-  dir: string
+/** One bundled skill, as read from disk and ready for `ctx.skills.register()`. */
+export interface BundledSkill {
+  /** Skill id — equals the directory name and the DSH-catalogued id. */
   name: string
+  /** Directory holding SKILL.md, `references/` and `scripts/`. */
+  dir: string
+  /** Catalogue description (from SKILL.md frontmatter, else the registry). */
   description: string
+  /** Full SKILL.md body. */
   content: string
-} {
-  const dir = requireSkillDir(moduleUrl, override)
+}
+
+/**
+ * Read one bundled SKILL.md.
+ *
+ * Exposed for tests and for callers that want a skill body without loading the
+ * plugin (e.g. a packaging check).
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param skillId - bundled skill id (see `./skills.ts`).
+ * @param override - explicit skills root (plugin config or env var).
+ */
+export function readBundledSkill(
+  moduleUrl: string,
+  skillId: string,
+  override?: string,
+): BundledSkill {
+  const dir = requireSkillDir(moduleUrl, skillId, override)
   const content = readFileSync(join(dir, 'SKILL.md'), 'utf8')
   return {
     dir,
-    name: KICAD_SKILL_NAME,
-    description: skillDescription(content) ?? FALLBACK_SKILL_DESCRIPTION,
+    name: skillId,
+    // The shipped frontmatter is authoritative; the registry summary is only a
+    // safety net so the catalog can never drift away from the skill body.
+    description: skillDescription(content) ?? kicadSkill(skillId).summary,
     content,
   }
 }
 
 /**
- * Read the bundled skill, or `null` when the installed package does not carry
- * one.
+ * Read one bundled skill, or `null` when the installed package does not carry
+ * it.
  *
  * ── Why this degrades instead of throwing ──────────────────────────────────
  * A missing `skills/` tree is a PACKAGING failure, and the honest signal for a
@@ -177,25 +196,29 @@ export function readBundledSkill(moduleUrl: string, override?: string): {
  * That actually happened: HQ Edge's builtin-plugin staging copied only
  * `package.json` + `lib/`, so `skills/` never reached the bundle and the
  * server could not start at all. The correct blast radius for "this plugin's
- * skill is missing" is "this plugin is degraded", so we log at error level
- * with the exact path and remedy, skip skill registration, and keep the tools
- * (which fail per-call with a typed `FAILED_PRECONDITION` rather than at load).
+ * skill is missing" is "this skill is unavailable", so we log at error level
+ * with the exact path and remedy and skip that skill — per skill, so a broken
+ * `kicad-ipc` never hides a perfectly good `hardware-design-brief`. The tools
+ * are always kept (they fail per-call with a typed `FAILED_PRECONDITION`
+ * rather than at load).
  *
  * @param moduleUrl - `import.meta.url` of the calling module.
- * @param override - explicit skill directory (plugin config or env var).
+ * @param skillId - bundled skill id (see `./skills.ts`).
+ * @param override - explicit skills root (plugin config or env var).
  */
 export function tryReadBundledSkill(
   moduleUrl: string,
+  skillId: string,
   override?: string,
-): { dir: string; name: string; description: string; content: string } | null {
+): BundledSkill | null {
   try {
-    return readBundledSkill(moduleUrl, override)
+    return readBundledSkill(moduleUrl, skillId, override)
   } catch (err) {
     log.error(
-      'dsh-kicad: bundled skill unavailable — continuing degraded, the KiCad ' +
-        'tools are registered but will fail until the package is reinstalled',
+      `dsh-kicad: bundled skill "${skillId}" unavailable — continuing degraded, ` +
+        'the KiCad tools are registered but will fail until the package is reinstalled',
       {
-        expectedDir: resolveSkillDir(moduleUrl, override),
+        expectedDir: resolveSkillDir(moduleUrl, skillId, override),
         error: String((err as Error)?.message ?? err),
       },
     )
@@ -204,16 +227,16 @@ export function tryReadBundledSkill(
 }
 
 /**
- * Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
+ * Host plugin body — register every bundled 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.
+ * Both halves are registered here so that one installation delivers both. Each
+ * skill's `resourceBase` points at its own bundled directory, which is how the
+ * agent reaches `references/` 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.
+ * @returns disposer — unregisters every skill and tool on plugin dispose.
  */
 export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
   if (!ctx.tools || typeof ctx.tools.register !== 'function') {
@@ -225,26 +248,35 @@ export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
 
   const resolved = resolveKicadConfig(config)
 
-  // Degraded rather than fatal: see tryReadBundledSkill. A null skill means
-  // the installed package is incomplete, not that the host is unusable.
-  const skill = tryReadBundledSkill(import.meta.url, config.skillsDir)
-  // Tools resolve their Python scripts under the skill directory, so they use
-  // the same path even when the skill itself is missing — a call then fails
-  // with a typed FAILED_PRECONDITION naming the exact script it needed.
-  const skillDir = skill?.dir ?? resolveSkillDir(import.meta.url, config.skillsDir)
+  // Degraded rather than fatal, per skill: see tryReadBundledSkill.
+  const skills = new Map<string, BundledSkill>()
+  for (const skillId of KICAD_SKILL_IDS) {
+    const skill = tryReadBundledSkill(import.meta.url, skillId, config.skillsDir)
+    if (skill) skills.set(skillId, skill)
+  }
+
+  // The tools resolve their Python scripts under the script-owning skill's
+  // directory, so they use the same path even when that skill itself failed to
+  // load — a call then fails with a typed FAILED_PRECONDITION naming the exact
+  // script it needed.
+  const scriptSkillDir =
+    skills.get(KICAD_SCRIPT_SKILL_ID)?.dir ??
+    resolveSkillDir(import.meta.url, KICAD_SCRIPT_SKILL_ID, config.skillsDir)
 
   log.info('applying dsh-kicad node half', {
     hasConfigHost: hasHostConfig(config),
     pythonPath: resolved.pythonPath,
-    skillDir,
-    skillPresent: skill !== null,
+    skillsRoot: skillsRoot(import.meta.url, config.skillsDir),
+    skillsRegistered: [...skills.keys()],
+    skillsMissing: KICAD_SKILL_IDS.filter((id) => !skills.has(id)),
+    scriptSkillDir,
     timeoutMs: resolved.timeoutMs,
   })
 
   const disposers: Array<() => void> = []
 
-  // ── Skill (bundled, no separate installation) ────────────────────────────
-  if (skill) {
+  // ── Skills (bundled, no separate installation) ───────────────────────────
+  for (const skill of skills.values()) {
     disposers.push(
       ctx.skills.register({
         name: skill.name,
@@ -258,7 +290,7 @@ export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
 
   // ── Tools ────────────────────────────────────────────────────────────────
   const tools = createKicadTools({
-    scriptsDir: scriptsDir(skillDir),
+    scriptsDir: scriptsDir(scriptSkillDir),
     pythonPath: resolved.pythonPath,
     config: resolved,
   })
@@ -267,8 +299,8 @@ export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
   }
 
   log.info('dsh-kicad node half ready', {
-    skill: skill?.name ?? null,
-    degraded: skill === null,
+    skills: [...skills.keys()],
+    degraded: skills.size < KICAD_SKILL_IDS.length,
     tools: tools.length,
     expectedTools: kicadToolNames().length,
   })

package/src/paths.ts

@@ -1,17 +1,23 @@
 /**
- * Resolution of the bundled KiCad skill directory at runtime.
+ * Resolution of the bundled skill directories 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:
+ * Every bundled skill ships inside the installed package
+ * (`<pkg>/skills/<skill-id>/`), 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`
+ *   - built artifact:   `<pkg>/lib/index.mjs`   -> `<pkg>/skills/<skill-id>`
+ *   - source (vitest):  `<pkg>/src/index.ts`    -> `<pkg>/skills/<skill-id>`
  *   - 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.
+ * without its skills is a broken delivery boundary.
+ *
+ * The override (`skillsDir` config / `DSH_KICAD_SKILLS_DIR`) is the **skills
+ * root**, i.e. the directory that *contains* the skill directories — not one
+ * skill's directory. One override therefore relocates the whole set, and the
+ * per-skill layout below it is unchanged.
  *
  * @module
  */
@@ -19,19 +25,17 @@ import { existsSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { KICAD_SKILL_NAME } from './scripts.js'
-
 /**
- * Absolute path of the bundled `kicad-ipc` skill directory.
+ * Absolute path of the directory holding every bundled skill.
  *
  * 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).
+ * @param override - explicit skills root (plugin config or env var).
  * @returns the resolved directory, whether or not it exists yet.
  */
-export function resolveSkillDir(moduleUrl: string, override?: string): string {
+export function skillsRoot(moduleUrl: string, override?: string): string {
   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)
@@ -44,17 +48,29 @@ export function resolveSkillDir(moduleUrl: string, override?: string): string {
   const here = dirname(fileURLToPath(moduleUrl))
   // One level up is right for both `lib/` (built) and `src/` (vitest) because
   // both sit directly under the package root next to `skills/`.
-  return resolve(here, '..', 'skills', KICAD_SKILL_NAME)
+  return resolve(here, '..', 'skills')
+}
+
+/**
+ * Absolute path of one bundled skill directory.
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param skillId - bundled skill id; MUST equal the directory name.
+ * @param override - explicit skills root (plugin config or env var).
+ * @returns the resolved directory, whether or not it exists yet.
+ */
+export function resolveSkillDir(moduleUrl: string, skillId: string, override?: string): string {
+  return join(skillsRoot(moduleUrl, override), skillId)
 }
 
 /**
- * Resolve the skill directory and assert the skill is actually present.
+ * Resolve one 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.
  */
-export function requireSkillDir(moduleUrl: string, override?: string): string {
-  const dir = resolveSkillDir(moduleUrl, override)
+export function requireSkillDir(moduleUrl: string, skillId: string, override?: string): string {
+  const dir = resolveSkillDir(moduleUrl, skillId, override)
   const skillFile = join(dir, 'SKILL.md')
   if (!existsSync(skillFile)) {
     throw new Error(
@@ -66,7 +82,7 @@ export function requireSkillDir(moduleUrl: string, override?: string): string {
   return dir
 }
 
-/** Absolute path of the bundled Python script directory. */
+/** Absolute path of the bundled Python script directory inside a skill. */
 export function scriptsDir(skillDir: string): string {
   return join(skillDir, 'scripts')
 }

package/src/scripts.ts

@@ -2,9 +2,10 @@
  * Registry of the KiCad IPC script templates bundled with this package.
  *
  * The scripts are the migrated `kicad-agent` executable surface. They live
- * under `skills/kicad-ipc/scripts/` and are shipped verbatim — this module only
- * describes them so the DSH tools and the skill stay in sync. Nothing here
- * reimplements KiCad IPC: the scripts own it (see `./ipc.ts`).
+ * under `skills/<KICAD_SCRIPT_SKILL_ID>/scripts/` — the `kicad-ipc` skill (see
+ * `./skills.ts`, which owns the skill ids) — and are shipped verbatim: this
+ * module only describes them so the DSH tools and the skill stay in sync.
+ * Nothing here reimplements KiCad IPC: the scripts own it (see `./ipc.ts`).
  *
  * @module
  */
@@ -126,6 +127,3 @@ export function kicadScript(id: string): KicadScript {
   }
   return script
 }
-
-/** The canonical skill directory name shipped by this package. */
-export const KICAD_SKILL_NAME = 'kicad-ipc'

package/src/skills.ts

@@ -0,0 +1,94 @@
+/**
+ * Registry of the skills bundled with this package.
+ *
+ * The skills under `skills/` are the migrated `kicad-agent` knowledge, shipped
+ * verbatim (see `README.md` and `docs/dsh-kicad-migration.md`) — this module
+ * only *describes* them, so `apply()` can register each one with
+ * `ctx.skills.register()` without hardcoding paths or names.
+ *
+ * The registry is the single source of truth for three things that must not
+ * drift apart:
+ *
+ *   - the DSH skill id, which MUST equal the directory name under `skills/`
+ *     (the bundling tests assert this, because a mismatch silently produces a
+ *     skill whose `resourceBase` points somewhere else);
+ *   - the fallback catalogue description, used only when SKILL.md frontmatter
+ *     has no parseable `description` (the shipped file always wins);
+ *   - which skill owns the Python script templates the KiCad tools run.
+ *
+ * Adding a skill from `kicad-agent` means: copy the directory, add an entry
+ * here, and register it — nothing else in `src/` is skill-specific.
+ *
+ * @module
+ */
+
+/** A skill this package bundles and registers at load time. */
+export interface KicadBundledSkill {
+  /** DSH skill id — must match the directory name under `skills/`. */
+  readonly id: string
+  /**
+   * Agent-facing catalogue description, used ONLY when the bundled SKILL.md has
+   * no parseable `description` frontmatter. The shipped file is authoritative,
+   * so this cannot be the normal path — DSH ignores a skill without a
+   * description, so an empty value here would silently break discovery.
+   */
+  readonly summary: string
+  /**
+   * Whether this skill owns `skills/<id>/scripts/` — the runnable Python
+   * templates that back the DSH tools. Exactly one bundled skill does; the
+   * tools resolve their interpreter scripts through it (`./paths.ts`).
+   */
+  readonly ownsScripts: boolean
+}
+
+/**
+ * The skill that owns the script templates behind the KiCad tools.
+ *
+ * The tools are the *executable* half of this skill: `kicad_pcb_*` shells out
+ * to `skills/kicad-ipc/scripts/*.py`. Kept as a named constant because the
+ * tools must keep resolving correctly even when that particular skill fails to
+ * load (they then fail per-call with a typed `FAILED_PRECONDITION` instead of
+ * silently pointing at another skill's directory).
+ */
+export const KICAD_SCRIPT_SKILL_ID = 'kicad-ipc'
+
+/**
+ * Every skill bundled with `@huaqiu/dsh-kicad`, keyed by id.
+ *
+ * Mirrors `skills/` 1:1 — the bundling test asserts that every entry exists on
+ * disk with a valid SKILL.md, and that no directory is left unregistered.
+ */
+export const KICAD_SKILLS: Readonly<Record<string, KicadBundledSkill>> = {
+  [KICAD_SCRIPT_SKILL_ID]: {
+    id: KICAD_SCRIPT_SKILL_ID,
+    summary:
+      '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.',
+    ownsScripts: true,
+  },
+  'hardware-design-brief': {
+    id: 'hardware-design-brief',
+    summary:
+      'Turn a market need into verifiable hardware requirements: clarify them ' +
+      'through staged questioning and write the market MRD, the hardware PRD ' +
+      'and the schematic/PCB design inputs. Use when defining requirements for ' +
+      'a new board project.',
+    ownsScripts: false,
+  },
+}
+
+/** The bundled skill ids, in registration order. */
+export const KICAD_SKILL_IDS: readonly string[] = Object.keys(KICAD_SKILLS)
+
+/**
+ * Look up one bundled skill by id.
+ * @throws when the id is not part of the bundled set.
+ */
+export function kicadSkill(id: string): KicadBundledSkill {
+  const skill = KICAD_SKILLS[id]
+  if (!skill) {
+    throw new Error(`@huaqiu/dsh-kicad: unknown bundled skill "${id}"`)
+  }
+  return skill
+}