copperhead 0.7.0 → 0.8.0

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

package/src/commands/repl-inspect.ts

@@ -0,0 +1,353 @@
+/**
+ * Read-only inspect helpers for REPL slash commands (/sync, /config, /runs…).
+ * All deterministic, no LLM.
+ */
+
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { execa } from 'execa';
+import { loadConfig } from '../config.js';
+import { checkDrift } from '../memory/drift.js';
+import { loadConstraints } from '../memory/constraints.js';
+import { parseBomTable } from '../memory/bom-table.js';
+import { syncVerify, formatSyncReport } from './sync.js';
+import { listSymbols, listNets, pinNets } from '../kicad/sexp.js';
+import { openspecValidate } from '../openspec/cli.js';
+import { copper, dim, ok, warn, err } from '../agent/theme.js';
+import { traceRule } from '../agent/animate.js';
+import { shortPath } from '../util/paths.js';
+import { branchName, headCommit, isDirty, isGitRepo, uncommittedCount } from '../util/git.js';
+
+function meta(label: string, value: string): string {
+  return `  ${dim(label.padEnd(12))} ${value}`;
+}
+
+async function sortedRunIds(repoRoot: string): Promise<string[]> {
+  const runsDir = path.join(repoRoot, '.copperhead', 'runs');
+  if (!existsSync(runsDir)) return [];
+  return (await readdir(runsDir, { withFileTypes: true }))
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort()
+    .reverse();
+}
+
+async function resolveSchematic(
+  repoRoot: string,
+): Promise<{ schPath: string } | { message: string }> {
+  const config = await loadConfig(repoRoot);
+  if (!config.schematic) {
+    return { message: 'no schematic configured (run copperhead init)' };
+  }
+  const schPath = path.join(repoRoot, config.schematic);
+  if (!existsSync(schPath)) {
+    return { message: `schematic missing: ${config.schematic}` };
+  }
+  return { schPath };
+}
+
+/** `/sync` — verify-only inconsistency report (never auto-resolves). */
+export async function formatSyncInspect(repoRoot: string): Promise<string> {
+  const report = await syncVerify(repoRoot);
+  const body = formatSyncReport(report);
+  const headline =
+    !report.resolvable.length && !report.violations.length
+      ? ok('  sync: clean')
+      : report.violations.length
+        ? err(`  sync: ${report.violations.length} requirement violation(s), ${report.resolvable.length} resolvable`)
+        : warn(`  sync: ${report.resolvable.length} resolvable inconsistency(ies)`);
+  return ['', copper('  Sync'), traceRule(12), '', headline, '', ...body.split('\n').map((l) => `  ${l}`), ''].join(
+    '\n',
+  );
+}
+
+/** `/config` — full resolved config view. */
+export async function formatConfigInspect(repoRoot: string): Promise<string> {
+  const c = await loadConfig(repoRoot);
+  const lines = [
+    '',
+    copper('  Config'),
+    traceRule(14),
+    '',
+    meta('schematic', c.schematic ?? dim('null')),
+    meta('board', c.board ?? dim('null')),
+    meta('docs', c.docs),
+    meta('model', c.model ?? dim('null (use --model / env)')),
+    meta('maxTurns', String(c.maxTurns)),
+    meta('repair', String(c.maxRepairCycles)),
+    meta('origin', c.origin ?? dim('unset')),
+    meta('llmCache', c.llmCache ? 'on' : 'off'),
+    meta('budgets', Object.keys(c.budgets).length ? JSON.stringify(c.budgets) : dim('{}')),
+  ];
+  if (c.stageMaxTurns && Object.keys(c.stageMaxTurns).length) {
+    lines.push(meta('stageTurns', JSON.stringify(c.stageMaxTurns)));
+  }
+  lines.push('');
+  lines.push(dim(`  file  ${shortPath(path.join(repoRoot, '.copperhead/config.json'))}`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/git` — porcelain status + branch tip. */
+export async function formatGitInspect(repoRoot: string): Promise<string> {
+  if (!(await isGitRepo(repoRoot))) {
+    return ['', warn('  git: not a repository'), ''].join('\n');
+  }
+  const [branch, commit, dirty, n, porcelain] = await Promise.all([
+    branchName(repoRoot).catch(() => 'unknown'),
+    headCommit(repoRoot).catch(() => 'unknown'),
+    isDirty(repoRoot).catch(() => null),
+    uncommittedCount(repoRoot).catch(() => null),
+    execa('git', ['status', '--porcelain'], { cwd: repoRoot }).then((r) =>
+      r.stdout ? r.stdout.split('\n').filter(Boolean) : [],
+    ),
+  ]);
+  const state =
+    dirty === null ? 'unknown' : dirty ? warn(`dirty (${n ?? '?'} file(s))`) : ok('clean');
+  const lines = [
+    '',
+    copper('  Git'),
+    traceRule(10),
+    '',
+    meta('branch', `${branch}@${commit.slice(0, 7)}`),
+    meta('state', state),
+    '',
+  ];
+  if (porcelain.length) {
+    lines.push(dim('  changes:'));
+    for (const row of porcelain.slice(0, 40)) lines.push(`  ${row}`);
+    if (porcelain.length > 40) lines.push(dim(`  … and ${porcelain.length - 40} more`));
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/** `/drift` — doc↔schematic only (no ERC/DRC). */
+export async function formatDriftInspect(repoRoot: string): Promise<string> {
+  const config = await loadConfig(repoRoot);
+  if (!config.schematic) {
+    return ['', warn('  drift: no schematic configured (run copperhead init)'), ''].join('\n');
+  }
+  const mismatches = await checkDrift(repoRoot, config.docs, config.schematic);
+  if (!mismatches.length) {
+    return ['', ok('  drift: docs match schematic'), ''].join('\n');
+  }
+  const lines = [
+    '',
+    copper('  Drift'),
+    traceRule(12),
+    '',
+    warn(`  ${mismatches.length} mismatch(es):`),
+    '',
+  ];
+  for (const m of mismatches.slice(0, 30)) {
+    lines.push(`  ${copper('▸')} ${m.doc}`);
+    lines.push(dim(`      claim   ${m.claim}`));
+    lines.push(dim(`      actual  ${m.actual}`));
+  }
+  if (mismatches.length > 30) lines.push(dim(`  … and ${mismatches.length - 30} more`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/constraints` — registry summary. */
+export async function formatConstraintsInspect(repoRoot: string): Promise<string> {
+  const registry = await loadConstraints(repoRoot);
+  const keys = Object.keys(registry).sort();
+  if (!keys.length) {
+    return ['', dim('  constraints: none recorded yet'), ''].join('\n');
+  }
+  const lines = [
+    '',
+    copper('  Constraints'),
+    traceRule(20),
+    '',
+    dim(`  ${keys.length} open constraint(s)`),
+    '',
+  ];
+  for (const key of keys.slice(0, 40)) {
+    const c = registry[key]!;
+    const bound =
+      c.value !== undefined
+        ? String(c.value)
+        : [c.min !== undefined ? `min ${c.min}` : '', c.max !== undefined ? `max ${c.max}` : '']
+            .filter(Boolean)
+            .join(', ') || (c.forbidden?.length ? `forbidden ${c.forbidden.join(',')}` : '—');
+    lines.push(`  ${copper(key)}  ${bound}`);
+    lines.push(dim(`    source ${c.source} · affects ${c.affects.join(', ') || '—'}`));
+  }
+  if (keys.length > 40) lines.push(dim(`  … and ${keys.length - 40} more`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/runs` — recent `.copperhead/runs/` summaries. */
+export async function formatRunsInspect(repoRoot: string): Promise<string> {
+  const runsDir = path.join(repoRoot, '.copperhead', 'runs');
+  const entries = await sortedRunIds(repoRoot);
+  if (!entries.length) {
+    return ['', dim('  runs: none yet'), ''].join('\n');
+  }
+
+  const lines = ['', copper('  Recent runs'), traceRule(18), ''];
+  for (const id of entries.slice(0, 12)) {
+    const summaryPath = path.join(runsDir, id, 'summary.md');
+    const reportPath = path.join(runsDir, id, 'REPORT.md');
+    let outcome = dim('unknown');
+    if (existsSync(summaryPath)) {
+      const text = await readFile(summaryPath, 'utf8');
+      const m =
+        text.match(/exitPath[:\s*`]+([a-z-]+)/i) ||
+        text.match(/\*\*Exit(?:\s*path)?:\*\*\s*`?([a-z-]+)/i) ||
+        text.match(/## Run stats[\s\S]*?`([a-z-]+)`/);
+      if (m?.[1]) {
+        const pathName = m[1];
+        outcome =
+          pathName === 'done' ? ok(pathName) : /fail|error|refus|exhaust|stall/i.test(pathName) ? err(pathName) : warn(pathName);
+      } else if (/## Run stats/i.test(text)) {
+        outcome = dim('recorded');
+      }
+    }
+    const extras = existsSync(reportPath) ? dim(' · report') : '';
+    lines.push(`  ${copper(id)}  ${outcome}${extras}`);
+  }
+  if (entries.length > 12) lines.push(dim(`  … and ${entries.length - 12} older`));
+  lines.push('');
+  lines.push(dim(`  dir  ${shortPath(runsDir)}`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/parts` — schematic symbol table (refdes / value / footprint). */
+export async function formatPartsInspect(repoRoot: string): Promise<string> {
+  const resolved = await resolveSchematic(repoRoot);
+  if ('message' in resolved) {
+    return ['', warn(`  parts: ${resolved.message}`), ''].join('\n');
+  }
+  const syms = await listSymbols(resolved.schPath);
+  if (!syms.length) {
+    return ['', dim('  parts: schematic has no components'), ''].join('\n');
+  }
+  const refW = Math.max(4, ...syms.map((s) => s.ref.length));
+  const valW = Math.min(24, Math.max(5, ...syms.map((s) => s.value.length)));
+  const lines = [
+    '',
+    copper('  Parts'),
+    traceRule(12),
+    '',
+    dim(`  ${'ref'.padEnd(refW)}  ${'value'.padEnd(valW)}  footprint`),
+    '',
+  ];
+  for (const s of syms.slice(0, 60)) {
+    const val = s.value.length > valW ? s.value.slice(0, valW - 1) + '…' : s.value;
+    lines.push(`  ${copper(s.ref.padEnd(refW))}  ${val.padEnd(valW)}  ${dim(s.footprint || '—')}`);
+  }
+  if (syms.length > 60) lines.push(dim(`  … and ${syms.length - 60} more`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/nets` — net names and pin attachments from the schematic. */
+export async function formatNetsInspect(repoRoot: string): Promise<string> {
+  const resolved = await resolveSchematic(repoRoot);
+  if ('message' in resolved) {
+    return ['', warn(`  nets: ${resolved.message}`), ''].join('\n');
+  }
+  const [names, pins] = await Promise.all([listNets(resolved.schPath), pinNets(resolved.schPath)]);
+  const byNet = new Map<string, string[]>();
+  for (const p of pins) {
+    const net = p.net ?? '(unconnected)';
+    const tag = p.pinName ? `${p.ref}.${p.pinName}` : `${p.ref}:${p.pinNumber}`;
+    const list = byNet.get(net) ?? [];
+    list.push(tag);
+    byNet.set(net, list);
+  }
+  const ordered = [...new Set([...names, ...byNet.keys()])].sort((a, b) => {
+    if (a === '(unconnected)') return 1;
+    if (b === '(unconnected)') return -1;
+    return a.localeCompare(b);
+  });
+  const lines = ['', copper('  Nets'), traceRule(10), '', dim(`  ${ordered.length} net(s)`), ''];
+  for (const net of ordered.slice(0, 40)) {
+    const attached = (byNet.get(net) ?? []).sort();
+    const preview = attached.slice(0, 8).join(', ');
+    const extra = attached.length > 8 ? dim(` +${attached.length - 8}`) : '';
+    lines.push(`  ${copper(net)}  ${dim(preview)}${extra}`);
+  }
+  if (ordered.length > 40) lines.push(dim(`  … and ${ordered.length - 40} more`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/bom` — parsed docs/BOM.md (inspect only; no export). */
+export async function formatBomInspect(repoRoot: string): Promise<string> {
+  const config = await loadConfig(repoRoot);
+  const bomPath = path.join(repoRoot, config.docs, 'BOM.md');
+  if (!existsSync(bomPath)) {
+    return ['', warn('  bom: docs/BOM.md not found'), ''].join('\n');
+  }
+  const rows = parseBomTable(await readFile(bomPath, 'utf8'));
+  if (!rows.length) {
+    return ['', dim('  bom: no parseable rows in BOM.md'), ''].join('\n');
+  }
+  const refW = Math.max(5, ...rows.map((r) => r.refdes.length));
+  const lines = ['', copper('  BOM'), traceRule(8), '', dim(`  ${rows.length} row(s) from ${shortPath(bomPath)}`), ''];
+  for (const r of rows.slice(0, 50)) {
+    const flags = r.flags.length ? dim(` [${r.flags.join(',')}]`) : '';
+    lines.push(
+      `  ${copper(r.refdes.padEnd(refW))}  ${r.value ?? '—'}  ${dim(r.footprint ?? '')}${flags}`,
+    );
+    if (r.mpn) lines.push(dim(`    mpn ${r.mpn}`));
+  }
+  if (rows.length > 50) lines.push(dim(`  … and ${rows.length - 50} more`));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** `/openspec` — `openspec validate` summary (same gate as check). */
+export async function formatOpenSpecInspect(repoRoot: string): Promise<string> {
+  const cfgPath = path.join(repoRoot, 'openspec', 'config.yaml');
+  if (!existsSync(cfgPath)) {
+    return ['', dim('  openspec: no openspec/config.yaml in this repo'), ''].join('\n');
+  }
+  const res = await openspecValidate(repoRoot);
+  const headline = res.ok ? ok('  openspec: valid') : err('  openspec: validation failed');
+  const body = res.output
+    .trim()
+    .split('\n')
+    .slice(0, 30)
+    .map((l) => `  ${l}`)
+    .join('\n');
+  const lines = ['', copper('  OpenSpec'), traceRule(16), '', headline, ''];
+  if (body) lines.push(body, '');
+  return lines.join('\n');
+}
+
+/** `/last` — preview the newest run summary.md. */
+export async function formatLastInspect(repoRoot: string): Promise<string> {
+  const entries = await sortedRunIds(repoRoot);
+  if (!entries.length) {
+    return ['', dim('  last: no runs yet'), ''].join('\n');
+  }
+  const id = entries[0]!;
+  const runsDir = path.join(repoRoot, '.copperhead', 'runs');
+  const summaryPath = path.join(runsDir, id, 'summary.md');
+  const transcriptPath = path.join(runsDir, id, 'transcript.jsonl');
+  const lines = ['', copper('  Last run'), traceRule(14), '', meta('id', id), ''];
+  if (!existsSync(summaryPath)) {
+    lines.push(dim('  summary.md missing'), '');
+    return lines.join('\n');
+  }
+  const text = await readFile(summaryPath, 'utf8');
+  const preview = text.split('\n').slice(0, 40);
+  lines.push(dim(`  ${shortPath(summaryPath)}`));
+  if (existsSync(transcriptPath)) {
+    lines.push(dim(`  ${shortPath(transcriptPath)}`));
+  }
+  lines.push('');
+  for (const line of preview) lines.push(`  ${line}`);
+  if (text.split('\n').length > 40) lines.push(dim('  … truncated'));
+  lines.push('');
+  return lines.join('\n');
+}