copperhead 0.7.0 → 0.8.0

package/src/commands/create.ts

@@ -14,6 +14,7 @@ import { diagnoseStageFailure, transcriptExcerpt, withTimeout, type StageDiagnos
 import type { Provider } from '../agent/types.js';
 import type { RunMetaInput } from '../agent/runmeta.js';
 import { fmtDuration, fmtTokens, type ProgressRenderer } from '../agent/render.js';
+import { copper, dim, ok, stageLine, warn } from '../agent/theme.js';
 import { openspecInit } from '../openspec/cli.js';
 import { sweepStaleTempDirs, pruneHistoryDir } from '../util/tmp.js';
 import { assertDiskSpace, DEFAULT_MIN_FREE_BYTES } from '../util/preflight.js';
@@ -161,7 +162,7 @@ export interface CreateOptions {
 async function emitJlcpcbAfterOutputs(stageName: string, opts: CreateOptions): Promise<void> {
   if (stageName !== 'outputs') return;
   const out = await emitCreateJlcpcbBom(opts.repoRoot);
-  if (out) opts.log(`stage outputs: emitted ${out} (JLCPCB assembly BOM)`);
+  if (out) opts.log(stageLine('outputs', `emitted ${out} (JLCPCB assembly BOM)`, 'ok'));
 }
 
 /** Stages whose output is a KiCad file worth rendering to an image (5.4). */
@@ -203,16 +204,26 @@ async function commitResumedStage(opts: CreateOptions, config: CopperheadConfig,
   const foreign = dirty.filter((f) => !isManagedPath(f, config));
   if (foreign.length) {
     opts.log(
-      `stage ${stageName}: already-complete work is uncommitted, but the tree also has non-copperhead changes ` +
-        `(${foreign.slice(0, 3).join(', ')}${foreign.length > 3 ? ', …' : ''}); leaving it uncommitted so nothing of yours is swept up`,
+      stageLine(
+        stageName,
+        `already-complete work is uncommitted, but the tree also has non-copperhead changes ` +
+          `(${foreign.slice(0, 3).join(', ')}${foreign.length > 3 ? ', …' : ''}); leaving it uncommitted so nothing of yours is swept up`,
+        'warn',
+      ),
     );
     return;
   }
   try {
     const sha = await commitAll(opts.repoRoot, `copperhead: resume — commit completed stage ${stageName}`);
-    opts.log(`stage ${stageName}: committed already-complete work ${sha.slice(0, 10)} so a later rollback cannot wipe it (2.4)`);
-  } catch (err) {
-    opts.log(`stage ${stageName}: could not commit resumed work (${(err as Error).message})`);
+    opts.log(
+      stageLine(
+        stageName,
+        `committed already-complete work ${sha.slice(0, 10)} so a later rollback cannot wipe it (2.4)`,
+        'ok',
+      ),
+    );
+  } catch (e) {
+    opts.log(stageLine(stageName, `could not commit resumed work (${(e as Error).message})`, 'err'));
   }
 }
 
@@ -243,12 +254,18 @@ async function renderStageArtifacts(opts: CreateOptions, stageName: string, tran
     try {
       await exportSvg(kind, path.join(opts.repoRoot, file), artifactsDir);
       rendered++;
-    } catch (err) {
-      opts.log(`stage ${stageName}: could not render ${kind} SVG (${(err as Error).message})`);
+    } catch (e) {
+      opts.log(stageLine(stageName, `could not render ${kind} SVG (${(e as Error).message})`, 'warn'));
     }
   }
   if (rendered) {
-    opts.log(`stage ${stageName}: rendered ${rendered} SVG artifact(s) into ${path.relative(opts.repoRoot, artifactsDir)}/`);
+    opts.log(
+      stageLine(
+        stageName,
+        `rendered ${rendered} SVG artifact(s) into ${path.relative(opts.repoRoot, artifactsDir)}/`,
+        'ok',
+      ),
+    );
   }
 }
 
@@ -331,10 +348,14 @@ function resumeCommand(opts: CreateOptions): string {
  */
 function logResumePoint(opts: CreateOptions, stage: Stage, index: number): void {
   opts.log('');
-  opts.log(`⏸  stopped at stage ${index + 1}/${STAGES.length} (${stage.name}). To resume from here, run:`);
-  opts.log(`     ${resumeCommand(opts)}`);
   opts.log(
-    `   (${index} stage(s) already complete are detected from repo state and skipped; it resumes at ${stage.name}.)`,
+    warn(`⏸  stopped at stage ${index + 1}/${STAGES.length} (${stage.name}). To resume from here, run:`),
+  );
+  opts.log(copper(`     ${resumeCommand(opts)}`));
+  opts.log(
+    dim(
+      `   (${index} stage(s) already complete are detected from repo state and skipped; it resumes at ${stage.name}.)`,
+    ),
   );
 }
 
@@ -380,16 +401,21 @@ function printCostTable(opts: CreateOptions, costs: StageCost[]): void {
     `  ${r.stage.padEnd(w.stage)}  ${r.wall.padStart(w.wall)}  ${r.turns.padStart(w.turns)}  ${r.out.padStart(w.out)}  ${r.cache.padStart(w.cache)}`;
   const rule = `  ${'-'.repeat(w.stage)}  ${'-'.repeat(w.wall)}  ${'-'.repeat(w.turns)}  ${'-'.repeat(w.out)}  ${'-'.repeat(w.cache)}`;
   opts.log('');
-  opts.log('Per-stage cost summary (5.2):');
-  opts.log(line(header));
-  opts.log(rule);
+  opts.log(copper('Per-stage cost summary'));
+  opts.log(dim(line(header)));
+  opts.log(dim(rule));
   for (const r of rows) opts.log(line(r));
   if (total) {
-    opts.log(rule);
-    opts.log(line(total));
+    opts.log(dim(rule));
+    opts.log(boldTotal(line(total)));
   }
 }
 
+function boldTotal(s: string): string {
+  // TOTAL row: keep digits readable, accent only the label when color is on.
+  return s.replace(/^(\s*)TOTAL/, (_, sp: string) => `${sp}${copper('TOTAL')}`);
+}
+
 /** Sum the cost of the stages that actually ran this invocation (resumed stages
  *  cost nothing). Shared by the cumulative line and the end-of-run report (5.6). */
 function ranTotals(stageCosts: StageCost[]): {
@@ -422,8 +448,10 @@ function logCumulative(opts: CreateOptions, stageCosts: StageCost[]): void {
   const t = ranTotals(stageCosts);
   if (!t.turns && !t.wallMs) return; // nothing has actually run yet (all resumed)
   opts.log(
-    `pipeline so far: ${stageCosts.length}/${STAGES.length} stages · ${fmtDuration(t.wallMs)} · ` +
-      `${fmtTokens(t.tokensOut)} out tokens · ${cachePct(t.cacheHits, t.turns)}% cache hits`,
+    dim(
+      `pipeline so far: ${stageCosts.length}/${STAGES.length} stages · ${fmtDuration(t.wallMs)} · ` +
+        `${fmtTokens(t.tokensOut)} out tokens · ${cachePct(t.cacheHits, t.turns)}% cache hits`,
+    ),
   );
 }
 
@@ -533,11 +561,11 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
   // so a concurrent run's fresh dirs are never touched; best-effort, so it never
   // blocks a run (I8).
   const swept = await sweepStaleTempDirs(Date.now());
-  if (swept.length) opts.log(`startup: reclaimed ${swept.length} stale temp dir(s) from earlier runs`);
+  if (swept.length) opts.log(dim(`startup: reclaimed ${swept.length} stale temp dir(s) from earlier runs`));
   // Cap the gitignored .history/ so KiCad local history cannot grow unbounded
   // across a long run and fill the disk (4.1, I8). Best-effort; keeps the newest.
   const pruned = await pruneHistoryDir(opts.repoRoot);
-  if (pruned) opts.log(`startup: pruned ${pruned} old .history/ entrie(s) to cap local-history growth`);
+  if (pruned) opts.log(dim(`startup: pruned ${pruned} old .history/ entrie(s) to cap local-history growth`));
   await openspecInit(opts.repoRoot);
   const completed: string[] = [];
   const stageCosts: StageCost[] = [];
@@ -550,10 +578,12 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
     // contract can eventually be met. No-op once a project exists.
     if (stage.name === 'schematic') {
       const created = await bootstrapKicadProject(opts.repoRoot, brief);
-      if (created) opts.log(`stage schematic: scaffolded empty KiCad project (${created} + board + project), wired into config`);
+      if (created) {
+        opts.log(stageLine('schematic', `scaffolded empty KiCad project (${created} + board + project), wired into config`));
+      }
     }
     if (await stage.isComplete(opts.repoRoot, config.docs)) {
-      opts.log(`stage ${stage.name}: already complete (resuming past it)`);
+      opts.log(stageLine(stage.name, 'already complete (resuming past it)', 'ok'));
       await commitResumedStage(opts, config, stage.name);
       completed.push(stage.name);
       stageCosts.push({ name: stage.name, resumed: true, wallMs: 0, turns: 0, tokensIn: 0, tokensOut: 0, cacheHits: 0 });
@@ -585,9 +615,16 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       // whenever the project already exists.
       if (stage.name === 'schematic') {
         const rescaffolded = await bootstrapKicadProject(opts.repoRoot, brief);
-        if (rescaffolded && attempt > 1) opts.log(`stage schematic: re-scaffolded empty KiCad project after rollback, wired into config`);
+        if (rescaffolded && attempt > 1) {
+          opts.log(stageLine('schematic', 're-scaffolded empty KiCad project after rollback, wired into config'));
+        }
       }
-      opts.log(`stage ${stage.name}: running${attempt > 1 ? ` (attempt ${attempt}/${config.maxStageRetries + 1})` : ''}`);
+      opts.log(
+        stageLine(
+          stage.name,
+          `running${attempt > 1 ? ` (attempt ${attempt}/${config.maxStageRetries + 1})` : ''}`,
+        ),
+      );
       const res = await runAgentLoop({
         repoRoot: opts.repoRoot,
         model: opts.model,
@@ -635,12 +672,16 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
 
       if (attempt > config.maxStageRetries) {
         opts.log(
-          `stage ${stage.name}: ${failure}; exhausted ${config.maxStageRetries} auto-retry(ies). Stopping for a human.`,
+          stageLine(
+            stage.name,
+            `${failure}; exhausted ${config.maxStageRetries} auto-retry(ies). Stopping for a human.`,
+            'err',
+          ),
         );
         break;
       }
 
-      opts.log(`stage ${stage.name}: ${failure}; asking the model whether to retry…`);
+      opts.log(stageLine(stage.name, `${failure}; asking the model whether to retry…`, 'warn'));
       const diagnosis = await diagnose({
         model: opts.model,
         timeoutMs: config.turnTimeoutMs,
@@ -656,9 +697,15 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       // not under-report by omitting it.
       cost.tokensIn += diagnosis.usage?.inputTokens ?? 0;
       cost.tokensOut += diagnosis.usage?.outputTokens ?? 0;
-      opts.log(`stage ${stage.name}: diagnosis → ${diagnosis.verdict} — ${diagnosis.reason}`);
+      opts.log(
+        stageLine(
+          stage.name,
+          `diagnosis → ${diagnosis.verdict} — ${diagnosis.reason}`,
+          diagnosis.verdict === 'abort' ? 'err' : 'warn',
+        ),
+      );
       if (diagnosis.verdict === 'abort') {
-        opts.log(`stage ${stage.name}: recovery supervisor recommends stopping for a human.`);
+        opts.log(stageLine(stage.name, 'recovery supervisor recommends stopping for a human.', 'err'));
         break;
       }
       guidance = diagnosis.guidance ?? `The previous attempt failed: ${failure}. ${diagnosis.reason}`;
@@ -680,7 +727,11 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
   }
 
   const check = await runCheck(opts.repoRoot, opts.log);
-  opts.log(check.ok ? 'create pipeline complete; all checks green' : 'create pipeline complete with check failures');
+  opts.log(
+    check.ok
+      ? ok('create pipeline complete; all checks green')
+      : warn('create pipeline complete with check failures'),
+  );
   printCostTable(opts, stageCosts);
   await writeRunReport(opts, stageCosts);
   return { ok: check.ok, completed };

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 };
+}