@huaqiu/dsh-kicad 0.4.2 → 0.4.3

package/lib/index.d.mts

@@ -267,6 +267,33 @@ declare function readBundledSkill(moduleUrl: string, override?: string): {
   description: string;
   content: string;
 };
+/**
+ * Read the bundled skill, or `null` when the installed package does not carry
+ * one.
+ *
+ * ── Why this degrades instead of throwing ──────────────────────────────────
+ * A missing `skills/` tree is a PACKAGING failure, and the honest signal for a
+ * packaging failure is a loud error — but not a dead server. `apply()` runs
+ * inside the DSH plugin tree: throwing here aborts the whole loader
+ * (`plugin tree failed to load`), kills the DSH process, and takes every other
+ * plugin and the entire EDA session down with it, for one missing asset.
+ *
+ * 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).
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param override - explicit skill directory (plugin config or env var).
+ */
+declare function tryReadBundledSkill(moduleUrl: string, override?: string): {
+  dir: string;
+  name: string;
+  description: string;
+  content: string;
+} | null;
 /**
  * Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
  *
@@ -281,4 +308,4 @@ declare function readBundledSkill(moduleUrl: string, override?: string): {
  */
 declare function apply(ctx: Context, config?: KicadConfigInput): () => void;
 //#endregion
-export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, type KicadConfig, type KicadConfigInput, type KicadError, type KicadErrorKind, type KicadScript, type ScriptEffect, type ScriptRun, SkillRegistration, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription };
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, type KicadConfig, type KicadConfigInput, type KicadError, type KicadErrorKind, type KicadScript, type ScriptEffect, type ScriptRun, SkillRegistration, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription, tryReadBundledSkill };

package/lib/index.mjs

@@ -902,6 +902,38 @@ function readBundledSkill(moduleUrl, override) {
 	};
 }
 /**
+* Read the bundled skill, or `null` when the installed package does not carry
+* one.
+*
+* ── Why this degrades instead of throwing ──────────────────────────────────
+* A missing `skills/` tree is a PACKAGING failure, and the honest signal for a
+* packaging failure is a loud error — but not a dead server. `apply()` runs
+* inside the DSH plugin tree: throwing here aborts the whole loader
+* (`plugin tree failed to load`), kills the DSH process, and takes every other
+* plugin and the entire EDA session down with it, for one missing asset.
+*
+* 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).
+*
+* @param moduleUrl - `import.meta.url` of the calling module.
+* @param override - explicit skill directory (plugin config or env var).
+*/
+function tryReadBundledSkill(moduleUrl, override) {
+	try {
+		return readBundledSkill(moduleUrl, 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", {
+			expectedDir: resolveSkillDir(moduleUrl, override),
+			error: String(err?.message ?? err)
+		});
+		return null;
+	}
+}
+/**
 * Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
 *
 * Both halves are registered here so that one installation delivers both. The
@@ -917,15 +949,17 @@ 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);
+	const skill = tryReadBundledSkill(import.meta.url, config.skillsDir);
+	const skillDir = skill?.dir ?? resolveSkillDir(import.meta.url, config.skillsDir);
 	log.info("applying dsh-kicad node half", {
 		hasConfigHost: hasHostConfig(config),
 		pythonPath: resolved.pythonPath,
-		skillDir: skill.dir,
+		skillDir,
+		skillPresent: skill !== null,
 		timeoutMs: resolved.timeoutMs
 	});
 	const disposers = [];
-	disposers.push(ctx.skills.register({
+	if (skill) disposers.push(ctx.skills.register({
 		name: skill.name,
 		description: skill.description,
 		content: skill.content,
@@ -935,13 +969,14 @@ function apply(ctx, config = {}) {
 		}
 	}));
 	const tools = createKicadTools({
-		scriptsDir: scriptsDir(skill.dir),
+		scriptsDir: scriptsDir(skillDir),
 		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,
+		skill: skill?.name ?? null,
+		degraded: skill === null,
 		tools: tools.length,
 		expectedTools: kicadToolNames().length
 	});
@@ -954,4 +989,4 @@ function apply(ctx, config = {}) {
 	};
 }
 //#endregion
-export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription };
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription, tryReadBundledSkill };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-kicad",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.0"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.4.2"
+    "@huaqiu/dsh-plugin-log": "0.4.3"
   },
   "files": [
     "lib",

package/src/index.ts

@@ -157,6 +157,46 @@ export function readBundledSkill(moduleUrl: string, override?: string): {
   }
 }
 
+/**
+ * Read the bundled skill, or `null` when the installed package does not carry
+ * one.
+ *
+ * ── Why this degrades instead of throwing ──────────────────────────────────
+ * A missing `skills/` tree is a PACKAGING failure, and the honest signal for a
+ * packaging failure is a loud error — but not a dead server. `apply()` runs
+ * inside the DSH plugin tree: throwing here aborts the whole loader
+ * (`plugin tree failed to load`), kills the DSH process, and takes every other
+ * plugin and the entire EDA session down with it, for one missing asset.
+ *
+ * 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).
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param override - explicit skill directory (plugin config or env var).
+ */
+export function tryReadBundledSkill(
+  moduleUrl: string,
+  override?: string,
+): { dir: string; name: string; description: string; content: string } | null {
+  try {
+    return readBundledSkill(moduleUrl, 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',
+      {
+        expectedDir: resolveSkillDir(moduleUrl, override),
+        error: String((err as Error)?.message ?? err),
+      },
+    )
+    return null
+  }
+}
+
 /**
  * Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
  *
@@ -179,32 +219,39 @@ export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
 
   const resolved = resolveKicadConfig(config)
 
-  // Throws when the installed package is missing its skill — a packaging
-  // failure must be loud, not silently degraded (§15).
-  const skill = readBundledSkill(import.meta.url, config.skillsDir)
+  // 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)
 
   log.info('applying dsh-kicad node half', {
     hasConfigHost: hasHostConfig(config),
     pythonPath: resolved.pythonPath,
-    skillDir: skill.dir,
+    skillDir,
+    skillPresent: skill !== null,
     timeoutMs: resolved.timeoutMs,
   })
 
   const disposers: Array<() => void> = []
 
   // ── Skill (bundled, no separate installation) ────────────────────────────
-  disposers.push(
-    ctx.skills.register({
-      name: skill.name,
-      description: skill.description,
-      content: skill.content,
-      resourceBase: { kind: 'directory', path: skill.dir },
-    }),
-  )
+  if (skill) {
+    disposers.push(
+      ctx.skills.register({
+        name: skill.name,
+        description: skill.description,
+        content: skill.content,
+        resourceBase: { kind: 'directory', path: skill.dir },
+      }),
+    )
+  }
 
   // ── Tools ────────────────────────────────────────────────────────────────
   const tools = createKicadTools({
-    scriptsDir: scriptsDir(skill.dir),
+    scriptsDir: scriptsDir(skillDir),
     pythonPath: resolved.pythonPath,
     config: resolved,
   })
@@ -213,7 +260,8 @@ export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
   }
 
   log.info('dsh-kicad node half ready', {
-    skill: skill.name,
+    skill: skill?.name ?? null,
+    degraded: skill === null,
     tools: tools.length,
     expectedTools: kicadToolNames().length,
   })