copperhead 0.6.0 → 0.8.0

package/src/commands/demo.ts

@@ -0,0 +1,184 @@
+/**
+ * End-to-end demo: scaffold a tiny git repo and run `create` against the
+ * USB-C power breakout brief (same path as `npm run demo:simple`).
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, readFile, readdir, appendFile } from 'node:fs/promises';
+import { execa } from 'execa';
+import type { ProgressRenderer } from '../agent/render.js';
+import type { RunMetaInput } from '../agent/runmeta.js';
+import type { BudgetExhaustedStats } from '../agent/loop.js';
+import { copper, dim, ok } from '../agent/theme.js';
+import { traceRule } from '../agent/animate.js';
+import { shortPath } from '../util/paths.js';
+import { runCreate } from './create.js';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const DEFAULT_BRIEF = path.join(PKG_ROOT, 'examples/simple/usb-c-breakout.md');
+const DEFAULT_DEMO_DIR = path.join(PKG_ROOT, 'demo-runs/usb-c-breakout');
+
+export interface DemoOptions {
+  model: string;
+  modelSource: RunMetaInput['modelSource'];
+  version: string;
+  kicadCliVersion: string;
+  interactive?: boolean;
+  /** Override demo repo (defaults to demo-runs/usb-c-breakout or COPPERHEAD_DEMO_DIR). */
+  demoDir?: string;
+  briefPath?: string;
+  log?: (line: string) => void;
+  renderer: ProgressRenderer;
+  onBudgetExhausted?: (stats: BudgetExhaustedStats) => Promise<number>;
+}
+
+/** Resolve the packaged USB-C brief; throws a clear error if the install is incomplete. */
+export function defaultBriefPath(): string {
+  if (!existsSync(DEFAULT_BRIEF)) {
+    throw new Error(
+      `demo brief missing at ${DEFAULT_BRIEF}; reinstall copperhead or run from a full checkout`,
+    );
+  }
+  return DEFAULT_BRIEF;
+}
+
+export function defaultDemoDir(): string {
+  return process.env.COPPERHEAD_DEMO_DIR ?? DEFAULT_DEMO_DIR;
+}
+
+/** Marker identifying a directory scaffolded by `copperhead demo`. */
+const DEMO_MARKER = path.join('.copperhead', 'demo-repo');
+
+/**
+ * Prepare a clean-enough git repo for the create pipeline (git init, ignore
+ * runs/, baseline config + commit). Mirrors scripts/demo-simple.sh.
+ */
+export async function scaffoldDemoRepo(demoDir: string): Promise<void> {
+  await mkdir(demoDir, { recursive: true });
+
+  // Fail closed before touching git: only scaffold into an empty directory
+  // or one this function created earlier (identified by the marker file).
+  // Anything else risks git-initializing and committing into a directory
+  // the user cares about.
+  const entries = await readdir(demoDir);
+  if (entries.length > 0 && !existsSync(path.join(demoDir, DEMO_MARKER))) {
+    throw new Error(
+      `refusing to scaffold the demo repo in ${demoDir}: the directory is not empty and was not created by copperhead demo; use an empty directory (or point COPPERHEAD_DEMO_DIR elsewhere)`,
+    );
+  }
+
+  const git = async (...args: string[]) => execa('git', args, { cwd: demoDir });
+
+  if (!existsSync(path.join(demoDir, '.git'))) {
+    await git('init', '-q');
+  }
+
+  const hasName = await execa('git', ['config', 'user.name'], { cwd: demoDir, reject: false });
+  if (hasName.exitCode !== 0) await git('config', 'user.name', 'copperhead demo');
+  const hasEmail = await execa('git', ['config', 'user.email'], { cwd: demoDir, reject: false });
+  if (hasEmail.exitCode !== 0) await git('config', 'user.email', 'demo@copperhead.local');
+
+  const gi = path.join(demoDir, '.gitignore');
+  if (!existsSync(gi)) await writeFile(gi, '', 'utf8');
+  const giText = await readFile(gi, 'utf8');
+  if (!giText.split('\n').includes('.copperhead/runs/')) {
+    await appendFile(gi, (giText.endsWith('\n') || giText === '' ? '' : '\n') + '.copperhead/runs/\n');
+  }
+
+  const cfgDir = path.join(demoDir, '.copperhead');
+  await mkdir(cfgDir, { recursive: true });
+  const marker = path.join(demoDir, DEMO_MARKER);
+  if (!existsSync(marker)) await writeFile(marker, 'created by copperhead demo\n', 'utf8');
+  const cfg = path.join(cfgDir, 'config.json');
+  if (!existsSync(cfg)) {
+    // Create stages need a larger turn budget than a single `do` edit.
+    await writeFile(
+      cfg,
+      `${JSON.stringify({ docs: 'docs/', maxTurns: 100, maxRepairCycles: 5 }, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  await git('add', '.gitignore', '.copperhead/config.json');
+  const head = await execa('git', ['rev-parse', '--verify', 'HEAD'], { cwd: demoDir, reject: false });
+  if (head.exitCode !== 0) {
+    await git('commit', '-q', '-m', 'demo: initialize repository');
+  } else {
+    const staged = await execa('git', ['diff', '--cached', '--quiet'], { cwd: demoDir, reject: false });
+    if (staged.exitCode !== 0) {
+      await git('commit', '-q', '-m', 'demo: update demo scaffolding');
+    }
+  }
+}
+
+/** What copperhead is — printed by `/demo` and `copperhead demo --tour`. */
+export function demoTourText(): string {
+  return [
+    '',
+    copper('  What copperhead does'),
+    traceRule(28),
+    '',
+    dim('  Cursor for circuit boards. You describe a change; the agent edits'),
+    dim('  real KiCad files, keeps design docs in sync, and verifies with'),
+    dim('  kicad-cli ERC/DRC before anything is committed.'),
+    '',
+    copper('  The loop'),
+    traceRule(16),
+    '',
+    `  ${copper('1.')} ${dim('Propose')}   write an OpenSpec change (edit tools stay locked until it validates)`,
+    `  ${copper('2.')} ${dim('Edit')}      anchored edits to .kicad_sch / .kicad_pcb + docs`,
+    `  ${copper('3.')} ${dim('Verify')}    run ERC (and DRC if the board changed); repair or roll back`,
+    `  ${copper('4.')} ${dim('Remember')}  DECISIONS.md + CHANGELOG + a run summary next to the transcript`,
+    '',
+    copper('  Try it'),
+    traceRule(14),
+    '',
+    `  ${copper('copperhead demo')}              ${dim('full create pipeline (USB-C breakout)')}`,
+    `  ${copper('copperhead')}                   ${dim('interactive shell — type a change request')}`,
+    `  ${copper('copperhead do "add an LED"')}    ${dim('one-shot edit on the current repo')}`,
+    '',
+    copper('  Example prompts'),
+    traceRule(22),
+    '',
+    dim('  • add reverse-polarity protection on VIN'),
+    dim('  • rename net KEY_DAH to KEY_DASH'),
+    dim('  • move the key input to a different RTC-capable pin'),
+    '',
+  ].join('\n');
+}
+
+export async function runDemo(opts: DemoOptions): Promise<{ ok: boolean; demoDir: string }> {
+  const log = opts.log ?? ((l: string) => console.log(l));
+  const demoDir = path.resolve(opts.demoDir ?? defaultDemoDir());
+  const briefPath = path.resolve(opts.briefPath ?? defaultBriefPath());
+
+  log('');
+  log(`  ${copper('copperhead demo')}  ${dim('USB-C power breakout')}`);
+  log(`  ${dim('repo')}   ${shortPath(demoDir)}`);
+  log(`  ${dim('brief')}  ${shortPath(briefPath)}`);
+  log('');
+
+  await scaffoldDemoRepo(demoDir);
+  log(ok('  scaffold ready'));
+  log('');
+
+  const res = await runCreate({
+    repoRoot: demoDir,
+    briefPath,
+    model: opts.model,
+    interactive: opts.interactive ?? false,
+    ...(opts.onBudgetExhausted ? { onBudgetExhausted: opts.onBudgetExhausted } : {}),
+    log,
+    renderer: opts.renderer,
+    meta: {
+      command: 'create',
+      modelSource: opts.modelSource,
+      version: opts.version,
+      kicadCliVersion: opts.kicadCliVersion,
+    },
+  });
+
+  return { ok: res.ok, demoDir };
+}

package/src/commands/doctor.ts

@@ -0,0 +1,289 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS, loadConfig, resolveModel, type CopperheadConfig } from '../config.js';
+import { kicadCliVersion } from '../kicad/cli.js';
+import { redactSecrets } from '../util/redact.js';
+
+const execFileP = promisify(execFile);
+
+/**
+ * `copperhead doctor` (env preflight): a fast, LLM-free, network-free check of
+ * whether this machine can actually run a copperhead command — the gap `check`
+ * leaves (it verifies kicad-cli but is contractually LLM-free, so it never looks
+ * 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 interface DoctorCheck {
+  name: string;
+  status: DoctorStatus;
+  detail: string;
+  hint?: string;
+}
+
+export interface DoctorReport {
+  /** true when no *critical* check failed (info-only checks never block). */
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+/** Probes are injectable so tests never depend on the host's tools. */
+export interface DoctorDeps {
+  nodeVersion: string;
+  kicadVersion: () => Promise<string>;
+  gitVersion: () => Promise<string>;
+  env: NodeJS.ProcessEnv;
+}
+
+function defaultDeps(): DoctorDeps {
+  return {
+    nodeVersion: process.version,
+    kicadVersion: kicadCliVersion,
+    // `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+/, ''),
+    env: process.env,
+  };
+}
+
+const MIN_NODE_MAJOR = 20; // package.json engines: ">=20"
+
+function nodeCheck(version: string): DoctorCheck {
+  const major = Number(version.replace(/^v/, '').split('.')[0]);
+  if (Number.isFinite(major) && major >= MIN_NODE_MAJOR) {
+    return { name: 'node', status: 'ok', detail: `${version} (>= ${MIN_NODE_MAJOR})` };
+  }
+  return {
+    name: 'node',
+    status: 'fail',
+    detail: `${version} (< ${MIN_NODE_MAJOR})`,
+    hint: `copperhead needs Node >= ${MIN_NODE_MAJOR}; upgrade Node.`,
+  };
+}
+
+async function kicadCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
+  try {
+    return { name: 'kicad-cli', status: 'ok', detail: await probe() };
+  } catch {
+    return {
+      name: 'kicad-cli',
+      status: 'fail',
+      detail: 'not found on PATH',
+      hint: 'install KiCad >= 9 (bundles kicad-cli); ERC/DRC gates need it.',
+    };
+  }
+}
+
+async function gitCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
+  try {
+    return { name: 'git', status: 'ok', detail: await probe() };
+  } catch {
+    return {
+      name: 'git',
+      status: 'fail',
+      detail: 'not found on PATH',
+      hint: 'install git; copperhead snapshots and commits its work.',
+    };
+  }
+}
+
+/**
+ * Map a resolved model to the credential its provider needs, mirroring
+ * makeProvider's prefix routing (agent/loop.ts). Presence-only: it checks that a
+ * required API key is set, never that it authenticates (that would need network).
+ * 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 {
+  // 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.
+  const shown = redactSecrets(model);
+  const savedLogin: Record<string, string> = {
+    codex: 'uses local Codex login',
+    'claude-code': 'uses Claude Code login',
+    cursor: 'uses Cursor Agent CLI login',
+  };
+  for (const [prefix, how] of Object.entries(savedLogin)) {
+    if (model === prefix || model.startsWith(`${prefix}:`)) {
+      // makeProvider rejects an empty override; a real run would fail here.
+      if (model === `${prefix}:`) {
+        return {
+          name: 'provider',
+          status: 'fail',
+          detail: `${shown} -> ${prefix}: empty model override`,
+          hint: `use "${prefix}" or "${prefix}:<model-id>".`,
+        };
+      }
+      return {
+        name: 'provider',
+        status: 'info',
+        detail: `${shown} -> ${prefix}: ${how} (not verified offline)`,
+      };
+    }
+  }
+  if (model === 'claude' || model.startsWith('claude')) {
+    return env.ANTHROPIC_API_KEY
+      ? { name: 'provider', status: 'ok', detail: `${shown} -> anthropic: ANTHROPIC_API_KEY set` }
+      : {
+          name: 'provider',
+          status: 'fail',
+          detail: `${shown} -> anthropic: ANTHROPIC_API_KEY not set`,
+          hint: 'export ANTHROPIC_API_KEY=... (or use --model claude-code for saved login).',
+        };
+  }
+  return env.OPENAI_API_KEY
+    ? { name: 'provider', status: 'ok', detail: `${shown} -> openai: OPENAI_API_KEY set` }
+    : {
+        name: 'provider',
+        status: 'fail',
+        detail: `${shown} -> openai: OPENAI_API_KEY not set`,
+        hint: 'export OPENAI_API_KEY=... (or use --model codex for saved login).',
+      };
+}
+
+function providerCheck(
+  flag: string | undefined,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  env: NodeJS.ProcessEnv,
+): DoctorCheck {
+  try {
+    const { model } = resolveModel(flag, config, env);
+    return checkCredential(model, 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.
+    return {
+      name: 'provider',
+      status: 'fail',
+      detail: 'no model configured',
+      hint: (err as Error).message.replace(/^no model configured:\s*/, ''),
+    };
+  }
+}
+
+function projectCheck(config: Awaited<ReturnType<typeof loadConfig>>, repoRoot: string): DoctorCheck {
+  const hasConfig = existsSync(path.join(repoRoot, '.copperhead', 'config.json'));
+  if (!hasConfig) {
+    return {
+      name: 'project',
+      status: 'info',
+      detail: 'no .copperhead/config.json (run `copperhead init` to scaffold)',
+    };
+  }
+  return {
+    name: 'project',
+    status: 'info',
+    detail: `schematic ${config.schematic ?? 'not wired'} · board ${config.board ?? 'not wired'}`,
+  };
+}
+
+export interface RunDoctorOptions {
+  repoRoot: string;
+  model?: string | undefined;
+  deps?: Partial<DoctorDeps>;
+}
+
+// Same shape loadConfig returns when no config file exists at all: a safe
+// fallback so a corrupted config.json degrades the project check, not the
+// whole command (resolveModel's config.model precedence level is simply
+// unavailable; --model/COPPERHEAD_MODEL/an available key still resolve).
+const FALLBACK_CONFIG: CopperheadConfig = { schematic: null, board: null, ...DEFAULTS };
+
+export async function runDoctor(opts: RunDoctorOptions): Promise<DoctorReport> {
+  const deps = { ...defaultDeps(), ...opts.deps };
+  let config: CopperheadConfig;
+  let configError: DoctorCheck | undefined;
+  try {
+    config = await loadConfig(opts.repoRoot);
+  } catch (err) {
+    config = FALLBACK_CONFIG;
+    // JSON.parse throws a bare SyntaxError for bad content; readFile throws a
+    // coded Error (EACCES, EISDIR, ...) for a file that couldn't be read at
+    // all. The two need different advice: content is fixed by regenerating
+    // the file, unreadable is a permissions/filesystem problem regenerating
+    // it will not solve.
+    configError =
+      err instanceof SyntaxError
+        ? {
+            name: 'project',
+            status: 'fail',
+            detail: `.copperhead/config.json is malformed: ${err.message}`,
+            hint: 'fix or delete .copperhead/config.json (rerun `copperhead init`/`copperhead create` to regenerate it).',
+          }
+        : {
+            name: 'project',
+            status: 'fail',
+            detail: `.copperhead/config.json could not be read: ${(err as Error).message}`,
+            hint: 'check that it is a regular file (not a directory) and that you have permission to read it.',
+          };
+  }
+  const checks: DoctorCheck[] = [
+    nodeCheck(deps.nodeVersion),
+    await kicadCheck(deps.kicadVersion),
+    await gitCheck(deps.gitVersion),
+    providerCheck(opts.model, config, deps.env),
+    configError ?? projectCheck(config, opts.repoRoot),
+  ];
+  return { ok: checks.every((c) => c.status !== 'fail'), checks };
+}
+
+const TAG: Record<DoctorStatus, string> = { ok: '[ok]', fail: '[FAIL]', 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
+
+// Plain ANSI, no color dependency: green/red/cyan tags, dim hints. Color is
+// off by default; the CLI opts in only for a real TTY, so piped output and
+// 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 DIM = '2';
+function paint(text: string, code: string, on: boolean): string {
+  return on ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+
+function wrapWords(text: string, width: number): string[] {
+  const lines: string[] = [];
+  let line = '';
+  for (const word of text.split(' ')) {
+    if (line && line.length + 1 + word.length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+/** Continuation lines land in the same column as the first, so wrapped text reads as one block. */
+function pushWrapped(lines: string[], first: string, text: string, col: number, width: number): void {
+  const wrapped = wrapWords(text, Math.max(20, width - col));
+  lines.push(first + (wrapped[0] ?? ''));
+  for (const rest of wrapped.slice(1)) lines.push(' '.repeat(col) + rest);
+}
+
+export function formatDoctor(report: DoctorReport, width = 80, color = false): string[] {
+  const lines: string[] = [];
+  for (const c of report.checks) {
+    const tag = paint(TAG[c.status], ANSI[c.status], color) + ' '.repeat(NAME_COL - TAG_COL - TAG[c.status].length);
+    const head = ' '.repeat(TAG_COL) + tag + c.name.padEnd(DETAIL_COL - NAME_COL);
+    pushWrapped(lines, head, c.detail, DETAIL_COL, width);
+    if (c.hint) {
+      const start = lines.length;
+      pushWrapped(lines, `${' '.repeat(NAME_COL)}hint: `, c.hint, NAME_COL + 6, width);
+      for (let i = start; i < lines.length; i++) lines[i] = paint(lines[i]!, DIM, color);
+    }
+  }
+  lines.push(
+    report.ok ? paint('ready', ANSI.ok, color) : paint('not ready: fix the [FAIL] items above', ANSI.fail, color),
+  );
+  return lines;
+}