copperhead 0.3.0

package/src/memory/scaffold.ts

@@ -0,0 +1,241 @@
+import { readFile, writeFile, mkdir, readdir, chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { listSymbols, pinNets, type SchematicSymbol, type PinNet } from '../kicad/sexp.js';
+import { configPath, loadConfig, type CopperheadConfig } from '../config.js';
+
+export class InitError extends Error {}
+
+export interface InitResult {
+  created: string[];
+  skipped: string[];
+  refused: string[];
+}
+
+const sha = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+async function findKicadFiles(searchRoot: string): Promise<{ sch: string | null; pcb: string | null }> {
+  let sch: string | null = null;
+  let pcb: string | null = null;
+  async function walk(dir: string): Promise<void> {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) await walk(abs);
+      else if (entry.name.endsWith('.kicad_sch') && !sch) sch = abs;
+      else if (entry.name.endsWith('.kicad_pcb') && !pcb) pcb = abs;
+    }
+  }
+  await walk(searchRoot);
+  return { sch, pcb };
+}
+
+function bomTable(symbols: SchematicSymbol[]): string {
+  const rows = symbols.map(
+    (s) => `| ${s.ref} | ${s.value} | ${s.footprint} | UNVERIFIED | extracted from schematic by copperhead init |`,
+  );
+  return ['| Refdes | Value | Footprint | MPN | Rationale |', '|---|---|---|---|---|', ...rows].join('\n');
+}
+
+function pinoutTable(pins: PinNet[]): string {
+  const rows = pins.map((p) => `| ${p.ref} | ${p.pinNumber} | ${p.pinName} | ${p.net ?? ''} | |`);
+  return ['| Refdes | Pin | Name | Net | Notes |', '|---|---|---|---|---|', ...rows].join('\n');
+}
+
+function generateDocs(
+  projectName: string,
+  symbols: SchematicSymbol[],
+  pins: PinNet[],
+): Record<string, string> {
+  const mcuRefs = new Set(symbols.filter((s) => s.ref.startsWith('U')).map((s) => s.ref));
+  const mcuPins = pins.filter((p) => mcuRefs.has(p.ref));
+  return {
+    'SPEC.md': `# ${projectName} — Specification
+
+What the device is, top-level constraints and budgets.
+
+## Budgets
+
+<!-- Add hard budgets here; copperhead treats them as constraints, e.g. -->
+<!-- - sleep_current_uA: 25 -->
+
+## Assumptions
+
+<!-- Decisions the agent made without explicit direction are flagged ASSUMED here -->
+`,
+    'BOM.md': `# Bill of Materials
+
+Every part: refdes, MPN, value, package, and WHY it was chosen. MPNs the agent
+introduces without a datasheet check are flagged UNVERIFIED.
+
+${bomTable(symbols)}
+`,
+    'PINOUT.md': `# Pinout
+
+Pin assignment extracted from the schematic. Check strapping/RTC notes before
+reassigning pins.
+
+${pinoutTable(mcuPins.length ? mcuPins : pins)}
+`,
+    'SUBSYSTEMS.md': `# Subsystems
+
+Per-sheet values and reasoning (regulator, charger, RF, ...).
+
+${[...new Set(symbols.map((s) => s.sheet))].map((sheet) => `## Sheet ${sheet}\n\n${symbols.filter((s) => s.sheet === sheet).map((s) => `- ${s.ref}: ${s.value}`).join('\n')}`).join('\n\n')}
+`,
+    'LAYOUT.md': `# Layout intent
+
+Placement and routing intent: keepouts, pours, ESD placement.
+
+## Draft quality
+
+<!-- copperhead writes an honest assessment here after any layout pass -->
+`,
+    'DECISIONS.md': `# Decision log
+
+Append-only. Every non-trivial agent decision lands here: date, run id,
+decision, rationale, and what it affects. Entries are never rewritten.
+`,
+    'CHANGELOG.md': `# Design changelog
+
+Append-only, newest first. One entry per committed copperhead run.
+`,
+  };
+}
+
+function copperheadReadme(config: CopperheadConfig): string {
+  return `# .copperhead — copperhead working memory
+
+Generated by \`copperhead init\`; regenerated on re-runs (do not hand-edit).
+
+## config.json
+
+- \`schematic\` / \`board\`: repo-relative paths to the KiCad files copperhead operates on (currently: ${config.schematic ?? 'none'} / ${config.board ?? 'none'})
+- \`docs\`: design docs directory (docs-as-memory), default \`docs/\`
+- \`model\`: default model (\`gpt-5\` or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- \`maxTurns\`: agent loop turn budget per run (default 40)
+- \`maxRepairCycles\`: ERC/DRC repair attempts before rollback (default 5)
+- \`budgets\`: free-form hard constraints (e.g. \`"sleep_current_uA": 25\`); surfaced verbatim into every run's system prompt
+- \`generatedHashes\`: content hashes of generated docs, used to detect hand edits on re-init
+
+## constraints.json
+
+Machine-readable constraint registry. Each key maps to \`{ min/max/forbidden/value, source, affects[] }\`.
+\`source\` points at the doc or spec that states the constraint; \`affects\` lists the
+refdes/nets/zones to revisit when the constraint changes. Kept in sync with the
+docs in the same tool turn (dual write).
+
+## runs/
+
+One directory per \`do\`/\`create\`/\`sync\` run: \`transcript.jsonl\` (full audit
+trail) and \`summary.md\` (human-readable: request, plan, files touched,
+verification results, decisions, open obligations). Both redact secrets at
+write time. This directory is gitignored.
+`;
+}
+
+const HOOK_MARKER = '# installed by copperhead init';
+
+async function installPreCommitHook(repoRoot: string): Promise<string | null> {
+  const hooksDir = path.join(repoRoot, '.git', 'hooks');
+  if (!existsSync(hooksDir)) return null;
+  const hookPath = path.join(hooksDir, 'pre-commit');
+  if (existsSync(hookPath)) {
+    const existing = await readFile(hookPath, 'utf8');
+    if (existing.includes(HOOK_MARKER)) return null; // idempotent
+    return null; // never clobber a user's own hook
+  }
+  const script = `#!/bin/sh
+${HOOK_MARKER}
+# Hand edits that desync docs, constraints, or the schematic fail at commit time.
+exec copperhead check
+`;
+  await writeFile(hookPath, script, 'utf8');
+  await chmod(hookPath, 0o755);
+  return hookPath;
+}
+
+export interface InitOptions {
+  repoRoot: string;
+  searchPath?: string;
+  force?: boolean;
+  installHooks?: boolean;
+}
+
+export async function runInit(opts: InitOptions): Promise<InitResult> {
+  const { repoRoot } = opts;
+  const searchRoot = path.resolve(repoRoot, opts.searchPath ?? '.');
+  const { sch, pcb } = await findKicadFiles(searchRoot);
+  if (!sch) {
+    throw new InitError(
+      `no .kicad_sch found under ${path.relative(repoRoot, searchRoot) || '.'} — point copperhead at a KiCad project (copperhead init --path <dir>)`,
+    );
+  }
+
+  const config = await loadConfig(repoRoot);
+  config.schematic = path.relative(repoRoot, sch);
+  config.board = pcb ? path.relative(repoRoot, pcb) : null;
+
+  const symbols = await listSymbols(sch);
+  const pins = await pinNets(sch);
+  const projectName = path.basename(sch, '.kicad_sch');
+  const docs = generateDocs(projectName, symbols, pins);
+
+  const docsDir = path.join(repoRoot, config.docs);
+  await mkdir(docsDir, { recursive: true });
+
+  const result: InitResult = { created: [], skipped: [], refused: [] };
+  const hashes: Record<string, string> = { ...(config.generatedHashes ?? {}) };
+  const appendOnly = new Set(['DECISIONS.md', 'CHANGELOG.md']);
+
+  for (const [name, content] of Object.entries(docs)) {
+    const p = path.join(docsDir, name);
+    const rel = path.join(config.docs, name);
+    if (!existsSync(p)) {
+      await writeFile(p, content, 'utf8');
+      hashes[name] = sha(content);
+      result.created.push(rel);
+      continue;
+    }
+    if (appendOnly.has(name)) {
+      result.skipped.push(rel); // append-only docs are never regenerated
+      continue;
+    }
+    const current = await readFile(p, 'utf8');
+    if (hashes[name] === sha(current)) {
+      if (current === content) {
+        result.skipped.push(rel);
+      } else if (opts.force) {
+        await writeFile(p, content, 'utf8');
+        hashes[name] = sha(content);
+        result.created.push(rel);
+      } else {
+        // schematic changed since generation but doc untouched: safe to refresh
+        await writeFile(p, content, 'utf8');
+        hashes[name] = sha(content);
+        result.created.push(rel);
+      }
+    } else if (opts.force) {
+      await writeFile(p, content, 'utf8');
+      hashes[name] = sha(content);
+      result.created.push(rel);
+    } else {
+      result.refused.push(rel);
+    }
+  }
+
+  config.generatedHashes = hashes;
+  const cfgPath = configPath(repoRoot);
+  await mkdir(path.dirname(cfgPath), { recursive: true });
+  await writeFile(cfgPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  // generated documentation, always refreshed (design D12)
+  await writeFile(path.join(repoRoot, '.copperhead', 'README.md'), copperheadReadme(config), 'utf8');
+
+  if (opts.installHooks !== false) {
+    const hook = await installPreCommitHook(repoRoot);
+    if (hook) result.created.push(path.relative(repoRoot, hook));
+  }
+
+  return result;
+}

package/src/openspec/cli.ts

@@ -0,0 +1,43 @@
+import { execa } from 'execa';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * OpenSpec is driven as a subprocess, same pattern as kicad-cli (SPEC §2.6).
+ * Never user-triggered; copperhead owns the propose → validate → archive flow.
+ */
+
+export interface OpenSpecResult {
+  ok: boolean;
+  output: string;
+}
+
+async function openspec(repo: string, args: string[]): Promise<OpenSpecResult> {
+  try {
+    const { stdout, stderr } = await execa('openspec', args, { cwd: repo });
+    return { ok: true, output: [stdout, stderr].filter(Boolean).join('\n') };
+  } catch (err) {
+    const e = err as { stdout?: string; stderr?: string; code?: string; message: string };
+    if (e.code === 'ENOENT') {
+      return { ok: false, output: 'openspec CLI not found on PATH (npm i -g @fission-ai/openspec)' };
+    }
+    return { ok: false, output: [e.stdout, e.stderr].filter(Boolean).join('\n') || e.message };
+  }
+}
+
+export function hasOpenSpec(repo: string): boolean {
+  return existsSync(path.join(repo, 'openspec'));
+}
+
+export async function openspecInit(repo: string): Promise<OpenSpecResult> {
+  if (hasOpenSpec(repo)) return { ok: true, output: 'openspec/ already present' };
+  return openspec(repo, ['init', '--no-interactive']);
+}
+
+export function openspecValidate(repo: string, changeId?: string): Promise<OpenSpecResult> {
+  return openspec(repo, changeId ? ['validate', changeId] : ['validate']);
+}
+
+export function openspecArchive(repo: string, changeId: string): Promise<OpenSpecResult> {
+  return openspec(repo, ['archive', changeId, '--yes']);
+}

package/src/util/env.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal .env loader.
+ *
+ * Keys are env-var-only by contract (AC-4.1), and they still are: this reads a
+ * gitignored .env into process.env at startup and nothing else ever persists
+ * them. No dependency, because dotenv's extra features (interpolation, multi-
+ * file precedence) are all things we would have to reason about at key-handling
+ * time.
+ *
+ * The real environment always wins. A .env file is a convenience for local runs,
+ * so it must never quietly override what CI or a shell export already set.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+/** KEY=value, optional `export ` prefix, optional matched quotes. */
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+
+export function parseEnv(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = LINE.exec(line);
+    if (!m) continue;
+    const key = m[1]!;
+    let value = m[2]!.trim();
+    const quoted =
+      (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length > 1);
+    if (quoted) {
+      value = value.slice(1, -1);
+    } else {
+      // Only strip trailing comments from unquoted values; a `#` inside quotes
+      // is part of the secret.
+      const hash = value.indexOf(' #');
+      if (hash !== -1) value = value.slice(0, hash).trim();
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Load `<dir>/.env` into process.env without overriding existing values.
+ * Returns the names (never the values) of the variables it set, for logging.
+ */
+export function loadEnvFile(dir: string): string[] {
+  const p = path.join(dir, '.env');
+  if (!existsSync(p)) return [];
+  let parsed: Record<string, string>;
+  try {
+    parsed = parseEnv(readFileSync(p, 'utf8'));
+  } catch {
+    return [];
+  }
+  const applied: string[] = [];
+  for (const [key, value] of Object.entries(parsed)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+      applied.push(key);
+    }
+  }
+  return applied;
+}

package/src/util/git.ts

@@ -0,0 +1,63 @@
+import { execa } from 'execa';
+
+export interface GitSnapshot {
+  head: string;
+  stash: string | null;
+}
+
+async function git(repo: string, args: string[]): Promise<string> {
+  const { stdout } = await execa('git', args, { cwd: repo });
+  return stdout.trim();
+}
+
+export async function isGitRepo(repo: string): Promise<boolean> {
+  try {
+    await git(repo, ['rev-parse', '--git-dir']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirty(repo: string): Promise<boolean> {
+  const status = await git(repo, ['status', '--porcelain']);
+  return status.length > 0;
+}
+
+/**
+ * Snapshot the working tree before a run. On a clean tree HEAD is enough;
+ * with --allow-dirty we keep a `git stash create` object so uncommitted work
+ * survives a rollback (SPEC §7).
+ */
+export async function snapshot(repo: string): Promise<GitSnapshot> {
+  const head = await git(repo, ['rev-parse', 'HEAD']);
+  let stash: string | null = null;
+  if (await isDirty(repo)) {
+    stash = (await git(repo, ['stash', 'create'])) || null;
+  }
+  return { head, stash };
+}
+
+/**
+ * Hard-restore the working tree to a snapshot (AC-3.6). The run audit trail
+ * (.copperhead/runs/) survives rollback: it is the evidence of what failed.
+ */
+export async function restore(repo: string, snap: GitSnapshot): Promise<void> {
+  await git(repo, ['reset', '--hard', snap.head]);
+  await git(repo, ['clean', '-fd', '-e', '.copperhead/runs']);
+  if (snap.stash) {
+    await git(repo, ['stash', 'apply', snap.stash]);
+  }
+}
+
+export async function commitAll(repo: string, message: string): Promise<string> {
+  await git(repo, ['add', '-A']);
+  await git(repo, ['commit', '-m', message]);
+  return git(repo, ['rev-parse', 'HEAD']);
+}
+
+export async function changedFiles(repo: string, sinceHead: string): Promise<string[]> {
+  const tracked = await git(repo, ['diff', '--name-only', sinceHead]);
+  const untracked = await git(repo, ['ls-files', '--others', '--exclude-standard']);
+  return [...new Set([...tracked.split('\n'), ...untracked.split('\n')])].filter(Boolean);
+}

package/src/util/paths.ts

@@ -0,0 +1,25 @@
+import path from 'node:path';
+
+export class SandboxError extends Error {
+  constructor(public readonly attempted: string) {
+    super(`path escapes repo root: ${attempted}`);
+    this.name = 'SandboxError';
+  }
+}
+
+/**
+ * Resolve a repo-relative path and reject anything that escapes the repo root
+ * (AC-4.2). All file tools must go through this.
+ */
+export function resolveInRepo(repoRoot: string, p: string): string {
+  const abs = path.resolve(repoRoot, p);
+  const root = path.resolve(repoRoot);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new SandboxError(p);
+  }
+  return abs;
+}
+
+export function isKicadFile(p: string): boolean {
+  return /\.(kicad_sch|kicad_pcb|kicad_pro|kicad_sym|kicad_mod)$/.test(p);
+}

package/src/util/redact.ts

@@ -0,0 +1,20 @@
+/**
+ * Write-time secret redaction for transcripts and summaries (AC-4.1).
+ * Patterns are deliberately broad: losing a few characters of log fidelity
+ * beats leaking a key.
+ */
+const PATTERNS: RegExp[] = [
+  /sk-[A-Za-z0-9_-]+/g,
+  /Bearer\s+[A-Za-z0-9._-]{16,}/g,
+  // Registry and forge tokens: a transcript that quotes a publish command or a
+  // failing CI log can carry these just as easily as a model API key.
+  /npm_[A-Za-z0-9]{36,}/g,
+  /gh[pousr]_[A-Za-z0-9]{36,}/g,
+  /github_pat_[A-Za-z0-9_]{22,}/g,
+];
+
+export function redactSecrets(text: string): string {
+  let out = text;
+  for (const re of PATTERNS) out = out.replace(re, '[REDACTED]');
+  return out;
+}

package/src/util/retry.ts

@@ -0,0 +1,33 @@
+export interface RetryOpts {
+  retries?: number;
+  baseMs?: number;
+  isRetryable?: (err: unknown) => boolean;
+  onRetry?: (attempt: number, err: unknown) => void;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export function isRateLimit(err: unknown): boolean {
+  const status = (err as { status?: number; statusCode?: number })?.status
+    ?? (err as { statusCode?: number })?.statusCode;
+  return status === 429;
+}
+
+/** Exponential backoff ×N for rate limits (SPEC §4.5). */
+export async function withRetry<T>(fn: () => Promise<T>, opts: RetryOpts = {}): Promise<T> {
+  const retries = opts.retries ?? 3;
+  const baseMs = opts.baseMs ?? 1000;
+  const isRetryable = opts.isRetryable ?? isRateLimit;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let lastErr: unknown;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isRetryable(err) || attempt === retries) throw err;
+      opts.onRetry?.(attempt + 1, err);
+      await sleep(baseMs * 2 ** attempt);
+    }
+  }
+  throw lastErr;
+}