copperhead 0.8.1 → 0.10.0

package/src/commands/doctor.ts

@@ -1,10 +1,21 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { execa } from 'execa';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { DEFAULTS, loadConfig, resolveModel, type CopperheadConfig } from '../config.js';
+import {
+  DEFAULTS,
+  DEFAULT_API_KEY_ENV,
+  isLocalEndpoint,
+  loadConfig,
+  resolveCompatSettings,
+  resolveModel,
+  type CompatSettings,
+  type CopperheadConfig,
+} from '../config.js';
 import { kicadCliVersion } from '../kicad/cli.js';
 import { redactSecrets } from '../util/redact.js';
+import { isNotFoundError } from '../util/preflight.js';
 
 const execFileP = promisify(execFile);
 
@@ -15,7 +26,7 @@ const execFileP = promisify(execFile);
  * at the model provider). Each probe fails soft: a missing tool is a reported
  * `fail`, never a thrown error, so `doctor` still prints the rest of the report.
  */
-export type DoctorStatus = 'ok' | 'fail' | 'info';
+export type DoctorStatus = 'ok' | 'fail' | 'warn' | 'info';
 
 export interface DoctorCheck {
   name: string;
@@ -35,6 +46,7 @@ export interface DoctorDeps {
   nodeVersion: string;
   kicadVersion: () => Promise<string>;
   gitVersion: () => Promise<string>;
+  openspecVersion: () => Promise<string>;
   env: NodeJS.ProcessEnv;
 }
 
@@ -45,6 +57,15 @@ function defaultDeps(): DoctorDeps {
     // `git --version` prints "git version 2.34.1"; keep only the number, the
     // report already labels the row "git".
     gitVersion: async () => (await execFileP('git', ['--version'])).stdout.trim().replace(/^git version\s+/, ''),
+    /**
+     * Probes `openspec --version` via execa, the same probe shape as the real
+     * call site (src/openspec/cli.ts): execa resolves Windows .cmd/.bat shims
+     * via cross-spawn without a shell, so a missing binary still yields ENOENT
+     * (what isNotFoundError expects) on every platform, instead of a
+     * shell-reported exit 127/"not found".
+     * @returns the trimmed stdout of `openspec --version` (e.g. "1.8.0").
+     */
+    openspecVersion: async () => (await execa('openspec', ['--version'])).stdout.trim(),
     env: process.env,
   };
 }
@@ -90,6 +111,41 @@ async function gitCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
   }
 }
 
+/**
+ * Report whether the `openspec` CLI is reachable, needed for `validate_change`
+ * and the `create` pipeline. Fails soft like `kicadCheck`/`gitCheck`: a
+ * missing or erroring probe is returned as a `fail` check, never thrown.
+ * @param probe resolves the openspec version string, or rejects if the CLI
+ *   can't be run (e.g. not found on PATH).
+ * @returns an `ok` check with the version on success; a `fail` check with an
+ *   install hint when `probe` rejects with a not-found error (per
+ *   `isNotFoundError`), or a `fail` check with the flattened error message
+ *   otherwise.
+ */
+async function openspecCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
+  try {
+    return { name: 'openspec', status: 'ok', detail: await probe() };
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      return {
+        name: 'openspec',
+        status: 'fail',
+        detail: 'not found on PATH',
+        hint: 'npm i -g @fission-ai/openspec; validate_change and the create pipeline need it.',
+      };
+    }
+    // Collapse embedded newlines/whitespace from a raw shell/subprocess error:
+    // formatDoctor's column layout assumes a single-line detail, and wrapWords
+    // splits on plain spaces only.
+    const rawMessage = (err as Error).message || String(err);
+    return {
+      name: 'openspec',
+      status: 'fail',
+      detail: rawMessage.replace(/\s+/g, ' ').trim(),
+    };
+  }
+}
+
 /**
  * Map a resolved model to the credential its provider needs, mirroring
  * makeProvider's prefix routing (agent/loop.ts). Presence-only: it checks that a
@@ -97,7 +153,139 @@ async function gitCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
  * Saved-login providers (codex, claude-code) need no key and can't be verified
  * offline, so they report `info` (which does not block `ok`).
  */
-export function checkCredential(model: string, env: NodeJS.ProcessEnv): DoctorCheck {
+export function checkCredential(
+  model: string,
+  env: NodeJS.ProcessEnv,
+  compat?: CompatSettings | undefined,
+): DoctorCheck {
+  // OpenAI-compatible endpoint: the credential lives in a variable the user
+  // names, and the endpoint is worth showing because it is the whole point of
+  // the route. A loopback endpoint (Ollama) needs no key at all (design D4).
+  if (model === 'compat' || model.startsWith('compat:')) {
+    const shownModel = redactSecrets(model);
+    const compatModel = model.startsWith('compat:') ? model.slice('compat:'.length) : undefined;
+    // Mirrors makeProvider (agent/loop.ts): bare `compat` has no valid default
+    // model, so it must fail here too, or doctor reports "ready" for a run
+    // that would fail on its very first turn.
+    if (!compatModel) {
+      return {
+        name: 'provider',
+        status: 'fail',
+        detail: `${shownModel} -> compat: ${model === 'compat:' ? 'empty' : 'missing'} model id`,
+        hint: 'use "compat:<model-id>"; a compatible endpoint has no default model to assume.',
+      };
+    }
+    const settings = compat ?? { apiKeyEnv: DEFAULT_API_KEY_ENV };
+    // Display only: some endpoints embed a credential in the URL itself (a
+    // query param, userinfo) — Gemini's compat endpoint does this with
+    // ?key=.... redactSecrets covers known key shapes, but a key embedded in
+    // a URL query isn't reliably one of them, so drop the query and userinfo
+    // entirely rather than pattern-matching, regardless of shape.
+    // isLocalEndpoint() below still runs against the raw settings.baseURL,
+    // never this.
+    const where = (() => {
+      if (!settings.baseURL) return '(no baseURL configured)';
+      try {
+        const u = new URL(settings.baseURL);
+        return `${u.origin}${u.pathname}`;
+      } catch {
+        return redactSecrets(settings.baseURL);
+      }
+    })();
+    if (!settings.baseURL) {
+      return {
+        name: 'provider',
+        status: 'fail',
+        detail: `${shownModel} -> compat: no endpoint configured`,
+        hint: 'set COPPERHEAD_BASE_URL, or "baseURL" in .copperhead/config.json.',
+      };
+    }
+    if (isLocalEndpoint(settings.baseURL)) {
+      return {
+        name: 'provider',
+        status: 'ok',
+        detail: `${shownModel} -> compat: ${where} (local endpoint, no key required)`,
+      };
+    }
+    return env[settings.apiKeyEnv]
+      ? { name: 'provider', status: 'ok', detail: `${shownModel} -> compat: ${where} (${settings.apiKeyEnv} set)` }
+      : {
+          name: 'provider',
+          status: 'fail',
+          detail: `${shownModel} -> compat: ${where} (${settings.apiKeyEnv} not set)`,
+          hint: `export ${settings.apiKeyEnv}=... for that endpoint.`,
+        };
+  }
+  return checkKeyedCredential(model, env);
+}
+
+/**
+ * Hosts whose free tier may train on submitted prompts. Keyed on hostname
+ * rather than model name: hostnames are stable, model and tier names rot in
+ * months, so the tier detail belongs in docs (design D5). Never `fail` — a
+ * contributor deliberately using a free tier on a non-proprietary board is not
+ * misconfigured, so this must not make `doctor` exit non-zero.
+ */
+const TRAINING_RISK_HOSTS: Record<string, string> = {
+  'generativelanguage.googleapis.com': "Gemini's free tier may train on submitted prompts",
+  'openrouter.ai': 'OpenRouter `:free` models may route to providers that train on prompts',
+};
+
+/**
+ * True loopback only — unlike `isLocalEndpoint` (config.ts), this excludes
+ * `.local`/mDNS hostnames. `isLocalEndpoint`'s broader definition is correct
+ * for "does this need a credential" (many LAN-hosted servers skip auth), but
+ * wrong for the privacy bypass below: a request to `nas.local` genuinely
+ * leaves the machine onto the LAN to a different physical device, so "nothing
+ * leaves the machine" does not hold the way it does for real loopback.
+ */
+function isLoopbackHost(baseURL: string): boolean {
+  try {
+    const h = new URL(baseURL).hostname.toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '[::1]';
+  } catch {
+    return false;
+  }
+}
+
+/** A `warn` line when the configured endpoint's host is a documented training risk. */
+export function checkPromptPrivacy(model: string, compat?: CompatSettings | undefined): DoctorCheck | null {
+  if (model !== 'compat' && !model.startsWith('compat:')) return null;
+  if (!compat?.baseURL) return null;
+  // A true loopback endpoint has no third party to have a policy about:
+  // nothing leaves the machine, so "check the provider's terms" would be
+  // nonsensical. A LAN host (including .local) does not get this bypass.
+  if (isLoopbackHost(compat.baseURL)) return null;
+  let host: string;
+  try {
+    host = new URL(compat.baseURL).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  const noPolicyOnRecord = (): DoctorCheck => ({
+    name: 'privacy',
+    status: 'info',
+    detail: `${host}: no known training-on-prompts policy on record (copperhead cannot verify this; check the provider's terms)`,
+  });
+  const risk = Object.entries(TRAINING_RISK_HOSTS).find(([h]) => host === h || host.endsWith(`.${h}`));
+  if (!risk) return noPolicyOnRecord();
+  // OpenRouter's documented risk is specific to its `:free`-suffixed models
+  // (their own wording), not the host as a whole. Warning on a fully paid
+  // OpenRouter model would be a false positive that undermines trust in the
+  // other, host-wide warnings (Gemini's applies to its whole free tier).
+  if (risk[0] === 'openrouter.ai') {
+    const compatModel = model.startsWith('compat:') ? model.slice('compat:'.length) : '';
+    if (!compatModel.endsWith(':free')) return noPolicyOnRecord();
+  }
+  return {
+    name: 'privacy',
+    status: 'warn',
+    detail: `${host}: ${risk[1]}`,
+    hint: 'PCB designs are often proprietary. Use a paid tier or a local endpoint for confidential work.',
+  };
+}
+
+function checkKeyedCredential(model: string, env: NodeJS.ProcessEnv): DoctorCheck {
   // A pasted API key can end up as the model value (--model sk-..., a stray
   // COPPERHEAD_MODEL); redact it before it reaches the report, same policy as
   // transcripts (AC-4.1). Routing below still uses the raw value.
@@ -152,16 +340,20 @@ function providerCheck(
 ): DoctorCheck {
   try {
     const { model } = resolveModel(flag, config, env);
-    return checkCredential(model, env);
+    return checkCredential(model, env, resolveCompatSettings(config, env));
   } catch (err) {
-    // resolveModel throws only when nothing selects a model at all. Its message
-    // starts with "no model configured: " — already this check's detail line —
-    // so keep only the remedy part for the hint.
+    // resolveModel throws for two distinct reasons: nothing selects a model at
+    // all ("no model configured: ..."), or two-plus credentials are present
+    // with nothing to break the tie ("ambiguous: ..."). Strip whichever prefix
+    // matched for the hint, and reflect which case it was in the detail so an
+    // ambiguous setup does not misreport as "nothing configured".
+    const message = (err as Error).message;
+    const ambiguous = message.startsWith('ambiguous:');
     return {
       name: 'provider',
       status: 'fail',
-      detail: 'no model configured',
-      hint: (err as Error).message.replace(/^no model configured:\s*/, ''),
+      detail: ambiguous ? 'ambiguous: multiple credentials, no model selected' : 'no model configured',
+      hint: message.replace(/^(no model configured|ambiguous):\s*/, ''),
     };
   }
 }
@@ -222,17 +414,32 @@ export async function runDoctor(opts: RunDoctorOptions): Promise<DoctorReport> {
             hint: 'check that it is a regular file (not a directory) and that you have permission to read it.',
           };
   }
+  // Resolving the model can fail (nothing configured); providerCheck reports
+  // that, and the compat-only checks simply do not apply in that case.
+  const compat = resolveCompatSettings(config, deps.env);
+  let resolvedModel: string | null = null;
+  try {
+    resolvedModel = resolveModel(opts.model, config, deps.env).model;
+  } catch {
+    resolvedModel = null;
+  }
   const checks: DoctorCheck[] = [
     nodeCheck(deps.nodeVersion),
     await kicadCheck(deps.kicadVersion),
     await gitCheck(deps.gitVersion),
+    await openspecCheck(deps.openspecVersion),
     providerCheck(opts.model, config, deps.env),
-    configError ?? projectCheck(config, opts.repoRoot),
   ];
+  if (resolvedModel) {
+    const privacy = checkPromptPrivacy(resolvedModel, compat);
+    if (privacy) checks.push(privacy);
+  }
+  checks.push(configError ?? projectCheck(config, opts.repoRoot));
+  // `warn` and `info` never block: only a hard failure means "not ready".
   return { ok: checks.every((c) => c.status !== 'fail'), checks };
 }
 
-const TAG: Record<DoctorStatus, string> = { ok: '[ok]', fail: '[FAIL]', info: '[info]' };
+const TAG: Record<DoctorStatus, string> = { ok: '[ok]', fail: '[FAIL]', warn: '[warn]', info: '[info]' };
 const TAG_COL = 2; // leading indent
 const NAME_COL = TAG_COL + 7; // widest tag "[FAIL]" + one space
 const DETAIL_COL = NAME_COL + 10; // widest name "kicad-cli" + one space
@@ -242,7 +449,7 @@ const DETAIL_COL = NAME_COL + 10; // widest name "kicad-cli" + one space
 // tests see plain text. Colored text is padded before painting — escape codes
 // have zero display width but nonzero string length, so painting first would
 // break the column math.
-const ANSI: Record<DoctorStatus, string> = { ok: '32', fail: '31', info: '36' };
+const ANSI: Record<DoctorStatus, string> = { ok: '32', fail: '31', warn: '33', info: '36' };
 const DIM = '2';
 function paint(text: string, code: string, on: boolean): string {
   return on ? `\u001b[${code}m${text}\u001b[0m` : text;

package/src/config.ts

@@ -2,9 +2,32 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Optional `legibility` block: checker thresholds and per-family severity
+ * overrides (`off` disables a family). Unknown keys and invalid values are
+ * ignored by the checker's own sanitizer, so a config typo cannot crash a run.
+ */
+export interface LegibilityUserConfig {
+  thresholds?: {
+    gridPitch?: number;
+    minPitch?: number;
+    utilization?: number;
+    maxWireLength?: number;
+    familyCap?: number;
+  };
+  severity?: Record<string, 'error' | 'advisory' | 'off'>;
+  /** Scorer tuning: per-metric weights and the known-good composite floor. */
+  score?: {
+    weights?: Record<string, number>;
+    floor?: number;
+  };
+}
+
 export interface CopperheadConfig {
   schematic: string | null;
   board: string | null;
+  /** Schematic legibility checker thresholds and severity overrides. */
+  legibility?: LegibilityUserConfig;
   docs: string;
   model: string | null;
   maxTurns: number;
@@ -26,6 +49,18 @@ export interface CopperheadConfig {
   /** Cache each turn's LLM response to disk and replay it on identical inputs,
    * so retries/restarts reuse work already paid for. Default on. */
   llmCache: boolean;
+  /**
+   * Base URL of an OpenAI-compatible endpoint (Groq, OpenRouter, Gemini's
+   * compat endpoint, a local Ollama). Consulted only by the `compat`
+   * route (design D2), so a stray value never redirects a plain `gpt-5` run.
+   */
+  baseURL?: string;
+  /**
+   * Name of the environment variable holding the compat endpoint's key, e.g.
+   * `GROQ_API_KEY`. The *name*, never the key itself: credentials stay in the
+   * environment (AC-4.1).
+   */
+  apiKeyEnv?: string;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
   generatedHashes?: Record<string, string>;
   /**
@@ -90,8 +125,11 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
         ? (raw.maxStageRetries as number)
         : DEFAULTS.maxStageRetries,
     llmCache: raw.llmCache !== false,
+    ...(typeof raw.baseURL === 'string' && raw.baseURL.trim() ? { baseURL: raw.baseURL.trim() } : {}),
+    ...(typeof raw.apiKeyEnv === 'string' && raw.apiKeyEnv.trim() ? { apiKeyEnv: raw.apiKeyEnv.trim() } : {}),
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
     ...(raw.origin === 'create' || raw.origin === 'init' ? { origin: raw.origin } : {}),
+    ...(raw.legibility && typeof raw.legibility === 'object' ? { legibility: raw.legibility } : {}),
   };
 }
 
@@ -140,9 +178,76 @@ export function resolveModel(flag: string | undefined, config: CopperheadConfig,
   if (flag) return { model: flag, source: 'flag' };
   if (env.COPPERHEAD_MODEL) return { model: env.COPPERHEAD_MODEL, source: 'env' };
   if (config.model) return { model: config.model, source: 'config' };
-  if (env.OPENAI_API_KEY) return { model: 'gpt-5', source: 'openai-key' };
-  if (env.ANTHROPIC_API_KEY) return { model: 'claude', source: 'anthropic-key' };
+  // Auto-fallback is only safe when exactly one credential is present: guessing
+  // is a convenience when there is nothing to guess wrong. With two or more
+  // keys set (a common dev setup once a compat endpoint's key sits alongside
+  // OPENAI_API_KEY/ANTHROPIC_API_KEY), silently favoring whichever is checked
+  // first can send a request to the wrong provider with no signal — including
+  // a paid one when a free key was what was actually intended. Refuse instead
+  // of guessing; the compat route itself is never a fallback candidate here,
+  // since it is opt-in only via an explicit `compat:` prefix (design D2).
+  const available: { keyVar: string; model: string; source: ModelSource }[] = [
+    ...(env.OPENAI_API_KEY ? [{ keyVar: 'OPENAI_API_KEY', model: 'gpt-5', source: 'openai-key' as const }] : []),
+    ...(env.ANTHROPIC_API_KEY ? [{ keyVar: 'ANTHROPIC_API_KEY', model: 'claude', source: 'anthropic-key' as const }] : []),
+  ];
+  if (available.length === 1) return { model: available[0]!.model, source: available[0]!.source };
+  if (available.length > 1) {
+    throw new Error(
+      `ambiguous: ${available.length} credentials found (${available.map((a) => a.keyVar).join(', ')}) and no model was ` +
+        'selected; pass --model, set COPPERHEAD_MODEL, or set "model" in .copperhead/config.json.',
+    );
+  }
   throw new Error(
     'no model configured: pass --model, set COPPERHEAD_MODEL, or export an API key; see https://docs.copperhead.sh/reference/configuration/',
   );
 }
+
+/** Where an OpenAI-compatible run points, and which variable holds its key. */
+export interface CompatSettings {
+  /** Endpoint base URL; undefined means the client's own default (OpenAI). */
+  baseURL?: string;
+  /** Name of the env var holding the key. Never the key itself. */
+  apiKeyEnv: string;
+}
+
+/** The credential variable used when nothing else is configured. */
+export const DEFAULT_API_KEY_ENV = 'OPENAI_API_KEY';
+
+/**
+ * Resolve the compatible-endpoint settings: environment wins over config, the
+ * same direction as `resolveModel`'s chain. These are *settings*, not a
+ * provider selector — only the `compat` route reads them (design D1/D2), so an
+ * exported COPPERHEAD_BASE_URL never silently redirects a `gpt-5` run.
+ */
+export function resolveCompatSettings(config: CopperheadConfig, env = process.env): CompatSettings {
+  const baseURL = env.COPPERHEAD_BASE_URL?.trim() || config.baseURL?.trim();
+  const apiKeyEnv = env.COPPERHEAD_API_KEY_ENV?.trim() || config.apiKeyEnv?.trim() || DEFAULT_API_KEY_ENV;
+  return { ...(baseURL ? { baseURL } : {}), apiKeyEnv };
+}
+
+/**
+ * True when a resolved model id routes through the `compat` provider (D1/D2).
+ * The single source of truth for that gate: `makeProvider` uses it to decide
+ * whether to consult `CompatSettings` at all, and the response cache (loop.ts)
+ * uses it to decide whether a run's cache key may depend on `baseURL` — a
+ * non-compat run (gpt-5, claude, ...) never reads COPPERHEAD_BASE_URL, so its
+ * cache key must not vary with it either, or every entry gets orphaned each
+ * time the endpoint used for unrelated compat testing changes.
+ */
+export function isCompatModel(model: string): boolean {
+  return model === 'compat' || model.startsWith('compat:');
+}
+
+/**
+ * True when the endpoint is loopback, i.e. a local server such as Ollama.
+ * Those need no credential (design D4); a remote endpoint always does.
+ */
+export function isLocalEndpoint(baseURL: string | undefined): boolean {
+  if (!baseURL) return false;
+  try {
+    const h = new URL(baseURL).hostname.toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '[::1]' || h.endsWith('.local');
+  } catch {
+    return false; // an unparseable URL is not a local endpoint; the run fails later with a clearer error
+  }
+}

package/src/kicad/bootstrap.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { configPath, loadConfig, type CopperheadConfig } from '../config.js';
+import { CREATE_ORIGIN } from './fab.js';
 
 /**
  * The create pipeline starts from a brief with no KiCad files, but the agent
@@ -37,8 +38,8 @@ function uuidFrom(seed: string): string {
 function emptySchematic(rootUuid: string): string {
   return `(kicad_sch
 	(version 20231120)
-	(generator "eeschema")
-	(generator_version "8.0")
+	(generator "copperhead-draft")
+	(generator_version "0")
 	(uuid "${rootUuid}")
 	(paper "A4")
 	(lib_symbols)
@@ -147,9 +148,25 @@ function projectFile(slug: string, rootUuid: string): string {
 }
 
 async function persist(repoRoot: string, config: CopperheadConfig): Promise<void> {
+  await mkdir(path.dirname(configPath(repoRoot)), { recursive: true });
   await writeFile(configPath(repoRoot), JSON.stringify(config, null, 2) + '\n', 'utf8');
 }
 
+/**
+ * Stamp the config as create-produced (`origin: "create"`). The marker is what
+ * scopes the legibility finish gate (`isCreateProducedRepo` feeds the
+ * obligations ledger) and the fab release gate — a gate hung on a marker
+ * nothing writes is silently inert, so `runCreate` stamps it up front and
+ * `bootstrapKicadProject` re-stamps on every (re-)scaffold, covering the
+ * rollback path that deletes an uncommitted config.
+ */
+export async function markCreateOrigin(repoRoot: string): Promise<void> {
+  const config = await loadConfig(repoRoot);
+  if (config.origin === CREATE_ORIGIN) return;
+  config.origin = CREATE_ORIGIN;
+  await persist(repoRoot, config);
+}
+
 /**
  * Ensure a KiCad project exists and is wired into config. No-op (returns null)
  * when config already points at a schematic on disk. If project files exist but
@@ -160,6 +177,10 @@ async function persist(repoRoot: string, config: CopperheadConfig): Promise<void
 export async function bootstrapKicadProject(repoRoot: string, brief: string): Promise<string | null> {
   const config = await loadConfig(repoRoot);
   if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) return null;
+  // Only `create` scaffolds through here, so the repo is create-produced by
+  // definition; stamping on every scaffold keeps the marker alive across the
+  // rollback-then-rescaffold path (git clean deletes an uncommitted config).
+  config.origin = CREATE_ORIGIN;
 
   const slug = projectSlug(brief);
   const schRel = `${slug}.kicad_sch`;

package/src/kicad/cli.ts

@@ -4,7 +4,7 @@ import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { normalizeReport, type CheckReport } from './report.js';
-import { PreflightError } from '../util/preflight.js';
+import { PreflightError, isNotFoundError } from '../util/preflight.js';
 
 export class KicadCliMissingError extends PreflightError {
   constructor() {
@@ -109,7 +109,7 @@ function fallbackAfterMissing(): string {
 async function runKicad(args: string[], opts?: { reject?: boolean }): Promise<Awaited<ReturnType<typeof execa>>> {
   let bin = resolveKicadCli();
   let res = await execa(bin, args, { reject: false });
-  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+  if (res.failed && isNotFoundError(res)) {
     if (bin === 'kicad-cli') {
       bin = fallbackAfterMissing();
       res = await execa(bin, args, { reject: false });
@@ -117,10 +117,10 @@ async function runKicad(args: string[], opts?: { reject?: boolean }): Promise<Aw
       throw new KicadCliMissingError();
     }
   }
-  if (opts?.reject === false) return res;
-  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+  if (res.failed && isNotFoundError(res)) {
     throw new KicadCliMissingError();
   }
+  if (opts?.reject === false) return res;
   if (res.failed) {
     throw Object.assign(new Error(res.stderr || res.stdout || `kicad-cli exited ${res.exitCode}`), res);
   }
@@ -143,15 +143,8 @@ export function setKicadFallbackBinaries(paths?: readonly string[]): void {
 }
 
 export async function kicadCliVersion(): Promise<string> {
-  try {
-    const res = await runKicad(['version']);
-    return String(res.stdout ?? '').trim();
-  } catch (err) {
-    if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
-    // runKicad already maps PATH ENOENT → fallback → KicadCliMissingError
-    if (err instanceof KicadCliMissingError) throw err;
-    throw err;
-  }
+  const res = await runKicad(['version']);
+  return String(res.stdout ?? '').trim();
 }
 
 async function runCheck(
@@ -167,9 +160,6 @@ async function runCheck(
       [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
       { reject: false },
     );
-    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
-      throw new KicadCliMissingError();
-    }
     let raw: unknown;
     try {
       raw = JSON.parse(await readFile(out, 'utf8'));
@@ -218,7 +208,6 @@ export async function kicadLoadError(filePath: string): Promise<string | null> {
     : ['pcb', 'export', 'pos', '--output', path.join(dir, 'probe.pos'), filePath];
   try {
     const res = await runKicad(args, { reject: false });
-    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     if (res.exitCode === 0) return null;
     return [res.stderr, res.stdout].filter(Boolean).join('\n').trim() || `kicad-cli exited ${res.exitCode}`;
   } finally {
@@ -258,7 +247,6 @@ export async function exportFab(pcbPath: string, schPath: string | null, outDir:
       result.produced.push(job.artifact);
     } catch (err) {
       if (err instanceof KicadCliMissingError) throw err;
-      if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
       result.failed.push({ artifact: job.artifact, reason: String((err as ExecaError).stderr ?? (err as Error).message).slice(0, 200) });
     }
   }
@@ -275,7 +263,6 @@ export async function exportSvg(kind: 'sch' | 'pcb', filePath: string, outDir: s
     await runKicad(args);
   } catch (err) {
     if (err instanceof KicadCliMissingError) throw err;
-    if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     throw err;
   }
   return outDir;