copperhead 0.6.0 → 0.8.0

package/src/config.ts

@@ -12,6 +12,20 @@ export interface CopperheadConfig {
   stageMaxTurns?: Record<string, number>;
   maxRepairCycles: number;
   budgets: Record<string, number>;
+  /** Per-turn watchdog (ms). A provider turn exceeding this is aborted and
+   * retried, so a hung call can't stall the run forever. <=0 disables it. */
+  turnTimeoutMs: number;
+  /** How often (ms) to emit a liveness heartbeat while a provider turn is in
+   * flight, so a slow large-output turn is distinguishable from a hung one
+   * (5.1). Fires only after the first interval, so quick turns stay silent.
+   * <=0 disables it. */
+  heartbeatMs: number;
+  /** How many times the create pipeline may auto-retry a stage that failed or
+   * ended without meeting its contract, gated by an LLM diagnosis each time. */
+  maxStageRetries: number;
+  /** 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;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
   generatedHashes?: Record<string, string>;
   /**
@@ -30,6 +44,19 @@ export const DEFAULTS: Omit<CopperheadConfig, 'schematic' | 'board'> = {
   maxTurns: 40,
   maxRepairCycles: 5,
   budgets: {},
+  // 10 min. A single large capture turn (a full lib_symbols + instances edit,
+  // ~40k output tokens) on the claude-code provider legitimately runs several
+  // minutes; the old 5-min deadline killed those mid-flight and, because the
+  // watchdog budget is spent per stage, could fail a stage that was only slow,
+  // not hung. 10 min clears the largest observed turns while still catching a
+  // genuinely stuck subprocess.
+  turnTimeoutMs: 600000,
+  // 30s: within one interval an operator knows a turn is alive, and a full
+  // 10-min turn emits ~20 lines — enough to distinguish slow from hung without
+  // flooding the log. Quick turns (< 30s) emit nothing.
+  heartbeatMs: 30000,
+  maxStageRetries: 2,
+  llmCache: true,
 };
 
 export function configPath(repoRoot: string): string {
@@ -56,13 +83,20 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     ...(Object.keys(stageMaxTurns).length ? { stageMaxTurns } : {}),
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
+    turnTimeoutMs: typeof raw.turnTimeoutMs === 'number' ? raw.turnTimeoutMs : DEFAULTS.turnTimeoutMs,
+    heartbeatMs: typeof raw.heartbeatMs === 'number' ? raw.heartbeatMs : DEFAULTS.heartbeatMs,
+    maxStageRetries:
+      Number.isInteger(raw.maxStageRetries) && (raw.maxStageRetries as number) >= 0
+        ? (raw.maxStageRetries as number)
+        : DEFAULTS.maxStageRetries,
+    llmCache: raw.llmCache !== false,
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
     ...(raw.origin === 'create' || raw.origin === 'init' ? { origin: raw.origin } : {}),
   };
 }
 
 /** Which level of the model-selection precedence chain won. */
-export type ModelSource = 'flag' | 'env' | 'config' | 'openai-key' | 'anthropic-key';
+export type ModelSource = 'flag' | 'env' | 'config' | 'openai-key' | 'anthropic-key' | 'picker';
 
 export interface ResolvedModel {
   model: string;
@@ -77,6 +111,8 @@ export interface ResolvedModel {
  * Accepted values (same set for `--model`, COPPERHEAD_MODEL, and `model` in
  * .copperhead/config.json):
  *
+ * - `cursor`          : the Cursor Agent CLI using saved login (`agent login`).
+ * - `cursor:<id>`     : the same provider on a specific model id.
  * - `claude-code`     : the Claude Code saved-login provider on its default
  *                       model. Needs NO API key — it reuses the logged-in Claude
  *                       Code CLI / CLAUDE_CODE_OAUTH_TOKEN via the Agent SDK.
@@ -97,7 +133,8 @@ export interface ResolvedModel {
  * a typo like `claud-sonnet-5` silently routes to OpenAI and fails there.
  * Anthropic and direct OpenAI providers require their API keys; `codex` requires
  * a locally installed and authenticated Codex CLI, and `claude-code` requires a
- * Claude Code login (CLAUDE_CODE_OAUTH_TOKEN); neither needs a model API key.
+ * Claude Code login (CLAUDE_CODE_OAUTH_TOKEN); `cursor` requires `agent login`.
+ * None of the saved-login providers need a model API key.
  */
 export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): ResolvedModel {
   if (flag) return { model: flag, source: 'flag' };
@@ -106,6 +143,6 @@ export function resolveModel(flag: string | undefined, config: CopperheadConfig,
   if (env.OPENAI_API_KEY) return { model: 'gpt-5', source: 'openai-key' };
   if (env.ANTHROPIC_API_KEY) return { model: 'claude', source: 'anthropic-key' };
   throw new Error(
-    'no model configured: pass --model codex (uses your local Codex login), set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
+    'no model configured: pass --model, set COPPERHEAD_MODEL, or export an API key; see https://docs.copperhead.sh/reference/configuration/',
   );
 }

package/src/kicad/bootstrap.ts

@@ -0,0 +1,181 @@
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { configPath, loadConfig, type CopperheadConfig } from '../config.js';
+
+/**
+ * The create pipeline starts from a brief with no KiCad files, but the agent
+ * cannot create them: `write_file` refuses KiCad files and `edit_file` only
+ * edits existing ones. Without a project on disk the schematic stage can never
+ * satisfy its contract (config.schematic stays null), so the pipeline stalls
+ * indefinitely. This module scaffolds a minimal, kicad-cli-loadable empty
+ * project (schematic ERC-clean, board DRC-clean with a default outline) and
+ * wires it into .copperhead/config.json, giving the agent a file to populate.
+ */
+
+/** Slug for the project filename, taken from the brief's first H1 (a leading
+ * "Brief:" label is dropped). Falls back to "board". */
+export function projectSlug(brief: string): string {
+  const m = brief.match(/^#\s+(.+?)\s*$/m);
+  const title = (m?.[1] ?? 'board').replace(/^brief\s*:\s*/i, '');
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'board';
+}
+
+/** A stable, valid-shaped v4 UUID derived from a seed, so a given project
+ * bootstraps to the same UUIDs on every run (no Date/random — runs stay
+ * reproducible). */
+function uuidFrom(seed: string): string {
+  const h = createHash('sha256').update(seed).digest('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+function emptySchematic(rootUuid: string): string {
+  return `(kicad_sch
+	(version 20231120)
+	(generator "eeschema")
+	(generator_version "8.0")
+	(uuid "${rootUuid}")
+	(paper "A4")
+	(lib_symbols)
+	(sheet_instances
+		(path "/" (page "1"))
+	)
+)
+`;
+}
+
+function emptyBoard(outlineUuid: string): string {
+  // A default 30x20mm outline on Edge.Cuts so the blank board is DRC-clean out
+  // of the gate; the layout stage resizes/replaces it with the real outline.
+  return `(kicad_pcb
+	(version 20240108)
+	(generator "pcbnew")
+	(generator_version "8.0")
+	(general
+		(thickness 1.6)
+		(legacy_teardrops no)
+	)
+	(paper "A4")
+	(layers
+		(0 "F.Cu" signal)
+		(31 "B.Cu" signal)
+		(32 "B.Adhes" user "B.Adhesive")
+		(33 "F.Adhes" user "F.Adhesive")
+		(34 "B.Paste" user)
+		(35 "F.Paste" user)
+		(36 "B.SilkS" user "B.Silkscreen")
+		(37 "F.SilkS" user "F.Silkscreen")
+		(38 "B.Mask" user)
+		(39 "F.Mask" user)
+		(40 "Dwgs.User" user "User.Drawings")
+		(41 "Cmts.User" user "User.Comments")
+		(42 "Eco1.User" user "User.Eco1")
+		(43 "Eco2.User" user "User.Eco2")
+		(44 "Edge.Cuts" user)
+		(45 "Margin" user)
+		(46 "B.CrtYd" user "B.Courtyard")
+		(47 "F.CrtYd" user "F.Courtyard")
+		(48 "B.Fab" user)
+		(49 "F.Fab" user)
+	)
+	(setup
+		(pad_to_mask_clearance 0)
+		(allow_soldermask_bridges_in_footprints no)
+	)
+	(net 0 "")
+	(gr_rect (start 100 100) (end 130 120)
+		(stroke (width 0.1) (type default))
+		(layer "Edge.Cuts")
+		(uuid "${outlineUuid}")
+	)
+)
+`;
+}
+
+function projectFile(slug: string, rootUuid: string): string {
+  return (
+    JSON.stringify(
+      {
+        board: { design_settings: { defaults: {}, rules: {} } },
+        erc: {
+          erc_exclusions: [],
+          meta: { version: 0 },
+          rule_severities: { footprint_link_issues: 'ignore', lib_symbol_issues: 'ignore' },
+        },
+        meta: { filename: `${slug}.kicad_pro`, version: 1 },
+        net_settings: {
+          classes: [
+            {
+              bus_width: 12,
+              clearance: 0.2,
+              diff_pair_gap: 0.25,
+              diff_pair_via_gap: 0.25,
+              diff_pair_width: 0.2,
+              line_style: 0,
+              microvia_diameter: 0.3,
+              microvia_drill: 0.1,
+              name: 'Default',
+              pcb_color: 'rgba(0, 0, 0, 0.000)',
+              schematic_color: 'rgba(0, 0, 0, 0.000)',
+              track_width: 0.25,
+              via_diameter: 0.6,
+              via_drill: 0.3,
+              wire_width: 6,
+            },
+          ],
+          meta: { version: 3 },
+        },
+        schematic: {
+          annotate_start_num: 0,
+          drawing: { default_line_thickness: 6.0, default_text_size: 50.0 },
+          legacy_lib_dir: '',
+          legacy_lib_list: [],
+          meta: { version: 1 },
+        },
+        sheets: [[rootUuid, 'Root']],
+        text_variables: {},
+      },
+      null,
+      2,
+    ) + '\n'
+  );
+}
+
+async function persist(repoRoot: string, config: CopperheadConfig): Promise<void> {
+  await writeFile(configPath(repoRoot), JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * 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
+ * config doesn't reference them, just wires config. Otherwise scaffolds an empty
+ * project. Returns the schematic's repo-relative path when it created or wired
+ * one, else null.
+ */
+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;
+
+  const slug = projectSlug(brief);
+  const schRel = `${slug}.kicad_sch`;
+  const pcbRel = `${slug}.kicad_pcb`;
+  const proRel = `${slug}.kicad_pro`;
+  const schAbs = path.join(repoRoot, schRel);
+
+  if (!existsSync(schAbs)) {
+    const rootUuid = uuidFrom(slug);
+    await writeFile(schAbs, emptySchematic(rootUuid), 'utf8');
+    await writeFile(path.join(repoRoot, pcbRel), emptyBoard(uuidFrom(`${slug}:edge`)), 'utf8');
+    await writeFile(path.join(repoRoot, proRel), projectFile(slug, rootUuid), 'utf8');
+  }
+
+  config.schematic = schRel;
+  config.board = existsSync(path.join(repoRoot, pcbRel)) ? pcbRel : null;
+  await persist(repoRoot, config);
+  return schRel;
+}

package/src/kicad/cli.ts

@@ -1,4 +1,5 @@
 import { execa, ExecaError } from 'execa';
+import { existsSync } from 'node:fs';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
@@ -13,6 +14,7 @@ export class KicadCliMissingError extends PreflightError {
       [
         'install KiCad ≥ 8: https://www.kicad.org/download/',
         'ensure the kicad-cli binary is on PATH (on macOS it ships inside KiCad.app/Contents/MacOS)',
+        'or set COPPERHEAD_KICAD_CLI=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
         'confirm with "kicad-cli version", then rerun',
       ],
     );
@@ -20,12 +22,134 @@ export class KicadCliMissingError extends PreflightError {
   }
 }
 
+/**
+ * `COPPERHEAD_KICAD_CLI` points somewhere that does not exist. Distinct from
+ * KicadCliMissingError because the advice is the opposite: the override was
+ * seen and rejected, so telling the user to set it would be nonsense.
+ */
+export class KicadCliBadOverrideError extends PreflightError {
+  constructor(configured: string) {
+    super(
+      `COPPERHEAD_KICAD_CLI points to a path that does not exist: ${configured}`,
+      'the override wins over PATH, so falling back silently would run a different binary than the one you named and make the failure impossible to diagnose',
+      [
+        `check the path: ls -l "${configured}"`,
+        'on macOS the binary lives at /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
+        'or unset COPPERHEAD_KICAD_CLI to fall back to PATH',
+        'confirm with "$COPPERHEAD_KICAD_CLI version", then rerun',
+      ],
+    );
+    this.name = 'KicadCliBadOverrideError';
+  }
+}
+
+/** Well-known install locations when `kicad-cli` is not on PATH (macOS app bundle). */
+const FALLBACK_BINARIES = [
+  '/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
+  '/Applications/KiCad-10.0/KiCad.app/Contents/MacOS/kicad-cli',
+  '/Applications/KiCad-9.0/KiCad.app/Contents/MacOS/kicad-cli',
+  '/Applications/KiCad-8.0/KiCad.app/Contents/MacOS/kicad-cli',
+];
+
+let fallbackBinaries: readonly string[] = FALLBACK_BINARIES;
+
+let cachedBinary: string | null | undefined;
+
+/**
+ * Resolve the kicad-cli executable: `COPPERHEAD_KICAD_CLI` > PATH name
+ * (`kicad-cli`). On PATH miss, `runKicad` falls back to macOS KiCad.app paths.
+ */
+export function resolveKicadCli(): string {
+  if (cachedBinary !== undefined) {
+    if (cachedBinary === null) throw new KicadCliMissingError();
+    return cachedBinary;
+  }
+  const fromEnv = envOverride();
+  if (fromEnv) {
+    cachedBinary = fromEnv;
+    return fromEnv;
+  }
+  cachedBinary = 'kicad-cli';
+  return cachedBinary;
+}
+
+/**
+ * The `COPPERHEAD_KICAD_CLI` override, or null when unset. Set-but-missing is
+ * a hard error rather than a silent fallthrough to PATH: the user told us
+ * which binary to run, and quietly running a different one (or reporting
+ * "not found on PATH" with advice to set the variable they already set) is
+ * the worst possible answer.
+ */
+function envOverride(): string | null {
+  const fromEnv = process.env.COPPERHEAD_KICAD_CLI?.trim();
+  if (!fromEnv) return null;
+  if (!existsSync(fromEnv)) throw new KicadCliBadOverrideError(fromEnv);
+  return fromEnv;
+}
+
+/**
+ * After ENOENT on PATH, retry with a known macOS install path.
+ *
+ * Deliberately does not re-read `COPPERHEAD_KICAD_CLI`: this is reached only
+ * when resolveKicadCli() cached the bare PATH name, which in turn happens only
+ * when the override was unset (set-but-missing throws there instead), so an
+ * override re-check here could never fire.
+ */
+function fallbackAfterMissing(): string {
+  for (const candidate of fallbackBinaries) {
+    if (existsSync(candidate)) {
+      cachedBinary = candidate;
+      return candidate;
+    }
+  }
+  cachedBinary = null;
+  throw new KicadCliMissingError();
+}
+
+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 (bin === 'kicad-cli') {
+      bin = fallbackAfterMissing();
+      res = await execa(bin, args, { reject: false });
+    } else {
+      throw new KicadCliMissingError();
+    }
+  }
+  if (opts?.reject === false) return res;
+  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+    throw new KicadCliMissingError();
+  }
+  if (res.failed) {
+    throw Object.assign(new Error(res.stderr || res.stdout || `kicad-cli exited ${res.exitCode}`), res);
+  }
+  return res;
+}
+
+/** Test helper: clear the resolved-binary cache. */
+export function resetKicadCliCache(): void {
+  cachedBinary = undefined;
+}
+
+/**
+ * Test helper: point the app-bundle probe at fixture paths, or call with no
+ * argument to restore the real list. Without this the fallback branch is only
+ * exercisable on a macOS host that happens to have KiCad installed, which
+ * makes the outcome depend on the developer's machine.
+ */
+export function setKicadFallbackBinaries(paths?: readonly string[]): void {
+  fallbackBinaries = paths ?? FALLBACK_BINARIES;
+}
+
 export async function kicadCliVersion(): Promise<string> {
   try {
-    const { stdout } = await execa('kicad-cli', ['version']);
-    return stdout.trim();
+    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;
   }
 }
@@ -39,8 +163,7 @@ async function runCheck(
   const out = path.join(dir, `${kind}.json`);
   const sub = kind === 'erc' ? ['sch', 'erc'] : ['pcb', 'drc'];
   try {
-    const res = await execa(
-      'kicad-cli',
+    const res = await runKicad(
       [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
       { reject: false },
     );
@@ -94,7 +217,7 @@ export async function kicadLoadError(filePath: string): Promise<string | null> {
     ? ['sch', 'export', 'netlist', '--output', path.join(dir, 'probe.net'), filePath]
     : ['pcb', 'export', 'pos', '--output', path.join(dir, 'probe.pos'), filePath];
   try {
-    const res = await execa('kicad-cli', args, { reject: false });
+    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}`;
@@ -131,9 +254,10 @@ export async function exportFab(pcbPath: string, schPath: string | null, outDir:
   }
   for (const job of jobs) {
     try {
-      await execa('kicad-cli', job.args);
+      await runKicad(job.args);
       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) });
     }
@@ -148,8 +272,9 @@ export async function exportSvg(kind: 'sch' | 'pcb', filePath: string, outDir: s
       ? ['sch', 'export', 'svg', '--output', outDir, filePath]
       : ['pcb', 'export', 'svg', '--output', path.join(outDir, 'board.svg'), '--layers', 'F.Cu,B.Cu,Edge.Cuts', filePath];
   try {
-    await execa('kicad-cli', args);
+    await runKicad(args);
   } catch (err) {
+    if (err instanceof KicadCliMissingError) throw err;
     if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     throw err;
   }