copperhead 0.9.0 → 0.11.0

package/src/capabilities/helpers.ts

@@ -0,0 +1,37 @@
+import { isKicadFile } from '../util/paths.js';
+import type { RunContext } from '../agent/context.js';
+
+export const str = (args: Record<string, unknown>, key: string): string => {
+  const v = args[key];
+  if (typeof v !== 'string' || v === '') throw new Error(`missing required string arg "${key}"`);
+  return v;
+};
+
+// U+FFFD (the Unicode replacement character) is what a byte sequence becomes
+// when UTF-8 decoding fails — most often a multibyte glyph (Ω, µ, ±, °) split
+// across a streaming chunk boundary and decoded per-chunk upstream in the
+// provider SDK (I2). It never appears in a legitimately authored PCB doc, so
+// its presence in a content-bearing tool arg means the value arrived corrupted.
+// Reject the call before it lands on disk so the model re-emits; the corruption
+// is nondeterministic (it depends on where a chunk boundary fell), so the retry
+// almost always comes through clean — far cheaper than shipping a mangled value
+// like "5.1kΩ" → "5.1k�" into DECISIONS.md and only noticing on review.
+const REPLACEMENT_CHAR = '�';
+export function corruptionError(fields: Record<string, unknown>): string | null {
+  const bad = Object.entries(fields)
+    .filter(([, v]) => typeof v === 'string' && v.includes(REPLACEMENT_CHAR))
+    .map(([k]) => k);
+  if (!bad.length) return null;
+  return `rejected: the ${bad.join(', ')} value contains U+FFFD (�), the replacement character that signals a UTF-8 decoding error — a special character (e.g. Ω, µ, ±, °) was likely mangled in transit. Re-send this exact call with the intended character written correctly, or spell it in ASCII (e.g. "ohm", "uF", "+/-", "deg").`;
+}
+
+export function markTouched(ctx: RunContext, rel: string): void {
+  ctx.filesTouched.add(rel);
+  if (isKicadFile(rel)) {
+    ctx.ledger.onKicadEdit(rel);
+    if (rel.endsWith('.kicad_sch')) ctx.lastErc = null;
+    if (rel.endsWith('.kicad_pcb')) ctx.lastDrc = null;
+  } else if (rel.endsWith('.md')) {
+    ctx.ledger.onDocEdit(rel);
+  }
+}

package/src/capabilities/index.ts

@@ -0,0 +1,53 @@
+import { outcomeResult, textResult, type ViewHint } from '../agent/envelope.js';
+import { defineTool, type CatalogEntry, type CatalogTool } from './define.js';
+import { HANDLERS } from './handlers.js';
+import generateReport from './skills/generate-report.js';
+
+export type { CatalogEntry, CatalogSkill, CatalogTool } from './define.js';
+export { defineTool, defineSkill } from './define.js';
+
+const HINT: Record<string, ViewHint> = {
+  read_file: 'query',
+  search: 'query',
+  list_symbols: 'query',
+  list_nets: 'query',
+  propose_change: 'mutation',
+  validate_change: 'diagnostic',
+  edit_file: 'mutation',
+  write_file: 'mutation',
+  run_erc: 'diagnostic',
+  search_symbols: 'query',
+  symbol_pins: 'query',
+  verify_symbols: 'diagnostic',
+  draft_schematic: 'mutation',
+  score_schematic: 'diagnostic',
+  check_legibility: 'diagnostic',
+  run_drc: 'diagnostic',
+  export_svg: 'export',
+  export_outputs: 'export',
+  check_drift: 'diagnostic',
+  record_constraint: 'mutation',
+  resolve_affected: 'mutation',
+  record_decision: 'mutation',
+  finish: 'diagnostic',
+};
+
+function wrap(def: (typeof HANDLERS)[number]): CatalogTool {
+  const viewHint = HINT[def.schema.name];
+  if (!viewHint) throw new Error(`missing viewHint for ${def.schema.name}`);
+  return defineTool({
+    schema: def.schema,
+    version: 1,
+    viewHint,
+    gate: def.requiresUnlock ? (ctx) => ctx.editsUnlocked : () => true,
+    handler: async (ctx, args) => {
+      const result = await def.handler(ctx, args);
+      return typeof result === 'string'
+        ? textResult(result, viewHint)
+        : outcomeResult(result.text, result.ok, viewHint);
+    },
+  });
+}
+
+/** Tools from HANDLERS + every skill module imported below (conformance checks skills/). */
+export const catalog: CatalogEntry[] = [...HANDLERS.map(wrap), generateReport];

package/src/capabilities/skills/generate-report.ts

@@ -0,0 +1,25 @@
+import { defineSkill } from '../define.js';
+
+export default defineSkill({
+  schema: {
+    name: 'generate_report',
+    description:
+      'Read-only report of the current design: ERC, DRC (if a board exists), drift, nets, and an optional SVG path. Does not edit files.',
+    parameters: {
+      type: 'object',
+      properties: { scope: { type: 'string', enum: ['power', 'all'], description: 'Report scope (default all)' } },
+      required: [],
+    },
+  },
+  version: 1,
+  viewHint: 'diagnostic',
+  tools: ['read_file', 'search', 'list_nets', 'run_erc', 'run_drc', 'export_svg', 'check_drift'],
+  maxTurns: 8,
+  prompt: (_ctx, args) => `You are generating a read-only design report (scope: ${args.scope === 'power' ? 'power' : 'all'}).
+Call the available tools to gather ERC, DRC (only if a board is configured; otherwise skip), drift, and the net list. Optionally export an SVG of the schematic.
+Do not edit any file. Do not call finish. When you have those results, stop calling tools.`,
+  isComplete: (ctx) =>
+    (!ctx.config.schematic || ctx.lastErc !== null) &&
+    (!ctx.config.board || ctx.lastDrc !== null) &&
+    (!ctx.config.schematic || ctx.lastDrift != null),
+});

package/src/cli.ts

@@ -179,6 +179,83 @@ program
   .description('ERC + DRC + doc-drift + spec validation; no LLM calls; CI-safe')
   .action(checkAction);
 
+// `draft` and `score` are command groups taking the artifact as a noun
+// (`draft schematic` today, `draft pcb` when layout drafting exists), so the
+// verb alone never has to guess what it applies to.
+const draftGroup = program
+  .command('draft')
+  .description('deterministically draft an artifact from its declared intent; no LLM, no network');
+draftGroup
+  .command('schematic')
+  .description('draft the schematic from schematic.intent.json')
+  .option('--intent <path>', 'repo-relative intent file (default: schematic.intent.json beside the schematic)')
+  .action(async (opts: { intent?: string }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    try {
+      const { loadConfig } = await import('./config.js');
+      const { draftSchematic, defaultIntentPath, formatSchematicDraftReport } = await import('./kicad/draft/draft.js');
+      const config = await loadConfig(repo);
+      if (!config.schematic) {
+        console.error('no schematic configured in .copperhead/config.json');
+        process.exit(1);
+      }
+      const res = await draftSchematic({
+        repoRoot: repo,
+        schematic: config.schematic,
+        intentPath: opts.intent ?? defaultIntentPath(config.schematic),
+        docsDir: config.docs,
+      });
+      if (!res.ok) {
+        if (json) console.log(JSON.stringify({ ok: false, findings: res.findings }, null, 2));
+        else console.error(res.message);
+        process.exit(1);
+      }
+      if (json) console.log(JSON.stringify({ ok: true, report: res.report }, null, 2));
+      else console.log(formatSchematicDraftReport(res.report));
+      process.exit(0);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
+const scoreGroup = program
+  .command('score')
+  .description('quantitative quality score for an artifact; advisory exit code; no LLM, no network');
+scoreGroup
+  .command('schematic')
+  .description('legibility and layout score for the schematic')
+  .option('--file <path>', 'score this .kicad_sch instead of the configured schematic (any sheet, no repo needed)')
+  .action(async (opts: { file?: string }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    try {
+      const { loadConfig } = await import('./config.js');
+      const { scoreSchematic, formatScore } = await import('./kicad/score.js');
+      const path = await import('node:path');
+      if (opts.file) {
+        const report = await scoreSchematic(path.resolve(opts.file), { docsDir: null });
+        console.log(json ? JSON.stringify(report, null, 2) : formatScore(report));
+        process.exit(0);
+      }
+      const config = await loadConfig(repo);
+      if (!config.schematic) {
+        console.error('no schematic configured in .copperhead/config.json');
+        process.exit(1);
+      }
+      const report = await scoreSchematic(path.join(repo, config.schematic), {
+        docsDir: path.join(repo, config.docs),
+        ...(config.legibility ? { config: config.legibility } : {}),
+      });
+      console.log(json ? JSON.stringify(report, null, 2) : formatScore(report));
+      process.exit(0); // the exit code never depends on the composite (AC-16.26 family)
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .description('env preflight: kicad-cli, git, node, and the model provider credential; no LLM, no network')
@@ -240,6 +317,60 @@ program
     },
   );
 
+const skillCmd = program.command('skill').description('run a registered skill (nested tool loop; no git commit)');
+
+skillCmd
+  .command('list')
+  .description('list registered skills (LLM-free, network-free)')
+  .action(async () => {
+    const repo = repoOf(program.opts());
+    try {
+      const { listSkills } = await import('./commands/skill.js');
+      const skills = await listSkills(repo);
+      if (program.opts().json) console.log(JSON.stringify(skills, null, 2));
+      else {
+        for (const s of skills) {
+          console.log(`${s.available ? '·' : '×'} ${s.name.replaceAll('_', '-')}  ${s.description.split('\n')[0]}`);
+        }
+      }
+      process.exit(0);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
+skillCmd
+  .command('run')
+  .description('run a skill by name (generate-report)')
+  .argument('<name>', 'skill name (kebab or underscore)')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code | compat:<id>')
+  .option('--scope <scope>', 'generate-report scope: power | all', 'all')
+  .action(async (name: string, opts: { model?: string; scope?: string }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    // `process.exit` skips pending finally blocks, so the provider close has to
+    // finish before the exit call — hence the code is carried out, not exited on.
+    let code = 1;
+    try {
+      const { runSkillCli, providerForSkillRun } = await import('./commands/skill.js');
+      const { provider } = await providerForSkillRun(repo, opts.model);
+      const res = await runSkillCli({
+        repoRoot: repo,
+        name,
+        args: { scope: opts.scope === 'power' ? 'power' : 'all' },
+        provider,
+        json,
+      });
+      console.log(res.text);
+      code = res.code;
+    } catch (err) {
+      console.error((err as Error).message);
+      code = 1;
+    }
+    process.exit(code);
+  });
+
 program
   .command('sync')
   .description('verify the whole design state for inconsistencies and resolve drift')
@@ -276,6 +407,29 @@ program
     }
   });
 
+program
+  .command('mcp')
+  .description('EXPERIMENTAL: serve the gated pipeline to MCP hosts over stdio (unstable surface)')
+  // `--repo` is also a global flag, but a host config reads as
+  // `args: ["mcp", "--repo", "/path"]`, so the command accepts it locally too.
+  .option('--repo <path>', 'target repository (default: cwd)')
+  .action(async (opts: { repo?: string }) => {
+    const repo = repoOf(opts.repo ? { repo: opts.repo } : program.opts());
+    try {
+      // Imported lazily, like `skill`: the MCP SDK and zod are a ~150ms load
+      // that every other command — including the pre-commit `check` — would
+      // otherwise pay, and a resolution failure here would take down the whole
+      // CLI rather than just this command.
+      const { startMcpServer } = await import('./mcp/server.js');
+      // Never returns until the host closes stdio. Nothing is printed to
+      // stdout here or anywhere downstream: it carries JSON-RPC alone.
+      await startMcpServer({ repoRoot: repo });
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('demo')
   .description('tour of what copperhead does, or run the USB-C breakout create pipeline')

package/src/commands/check.ts

@@ -5,7 +5,9 @@ import { runErc, runDrc } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { checkDrift, emptySchematicWarning, type DriftMismatch } from '../memory/drift.js';
 import { loadConstraints, checkForbiddenPins, type ConstraintViolation } from '../memory/constraints.js';
-import { pinNets } from '../kicad/sexp.js';
+import { pinNets, readSheetGeometry } from '../kicad/sexp.js';
+import { scoreFromGeometry, type ScoreReport } from '../kicad/score.js';
+import { checkLegibility, formatLegibility, LEGIBILITY_FAMILIES, type LegibilityFinding } from '../kicad/legibility.js';
 import { openspecValidate } from '../openspec/cli.js';
 
 /**
@@ -19,6 +21,20 @@ export interface CheckResult {
   drift: { ok: boolean; mismatches: DriftMismatch[]; warning?: string };
   openspec: { ok: boolean; detail: string } | null;
   constraints: { ok: boolean; violations: ConstraintViolation[] };
+  /**
+   * Advisory at every severity (design C6): findings inform, the exit code
+   * never depends on them, so existing repos gain information, not failures.
+   * Always present — all families skipped when no schematic is configured.
+   */
+  legibility: {
+    findings: LegibilityFinding[];
+    counts: { error: number; advisory: number };
+    skipped: { family: string; reason: string }[];
+    disabled: string[];
+    suppressed: { family: string; sheet: string; count: number }[];
+    /** Advisory quantitative score; null when no schematic is configured. */
+    score: ScoreReport | null;
+  };
 }
 
 export async function runCheck(repoRoot: string, log: (s: string) => void): Promise<CheckResult> {
@@ -59,6 +75,39 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
     log(res.ok ? 'openspec ✓' : `openspec: ${res.output}`);
   }
 
+  let legibility: CheckResult['legibility'];
+  if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) {
+    const report = await checkLegibility(path.join(repoRoot, config.schematic), {
+      docsDir: path.join(repoRoot, config.docs),
+      ...(config.legibility ? { config: config.legibility } : {}),
+    });
+    const score = scoreFromGeometry(
+      await readSheetGeometry(path.join(repoRoot, config.schematic)),
+      report,
+      config.legibility,
+    );
+    legibility = {
+      findings: report.findings,
+      counts: report.counts,
+      skipped: report.skipped,
+      disabled: report.disabled,
+      suppressed: report.suppressed,
+      score,
+    };
+    log(formatLegibility(report));
+    log(`legibility score: ${score.composite}/100${score.cap ? ` (capped: ${score.cap.reason})` : ''}`);
+  } else {
+    legibility = {
+      findings: [],
+      counts: { error: 0, advisory: 0 },
+      skipped: LEGIBILITY_FAMILIES.map((family) => ({ family, reason: 'no schematic configured' })),
+      disabled: [],
+      suppressed: [],
+      score: null,
+    };
+    log('legibility skipped (no schematic configured)');
+  }
+
   let constraintViolations: ConstraintViolation[] = [];
   if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) {
     const registry = await loadConstraints(repoRoot);
@@ -87,5 +136,6 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
     drift: { ok: drift.length === 0, mismatches: drift, ...(driftWarning ? { warning: driftWarning } : {}) },
     openspec,
     constraints: { ok: constraintViolations.length === 0, violations: constraintViolations },
+    legibility,
   };
 }