copperhead 0.5.0 → 0.6.0

package/src/cli.ts

@@ -8,6 +8,14 @@ import { runInit, InitError } from './memory/scaffold.js';
 import { runCheck } from './commands/check.js';
 import { syncVerify, syncResolve, formatSyncReport } from './commands/sync.js';
 import { runCreate } from './commands/create.js';
+import {
+  runExportBom,
+  parseSupplier,
+  parseBoards,
+  parseSpares,
+  ExportError,
+} from './commands/export.js';
+import { DEFAULT_BOARDS, DEFAULT_SPARES } from './kicad/bom-export.js';
 import { runAgentLoop, type BudgetExhaustedStats } from './agent/loop.js';
 import { makeRenderer } from './agent/render.js';
 import { kicadCliVersion } from './kicad/cli.js';
@@ -117,7 +125,7 @@ program
   .command('do')
   .description('the core loop: propose, edit, verify, propagate, commit')
   .argument('<request>', 'the change request in natural language')
-  .option('--model <model>', 'codex | gpt-5 | claude (or a provider-specific model id)')
+  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--max-turns <n>', 'turn budget for this run')
   .option('--allow-dirty', 'allow a dirty tree (snapshot via git stash create)')
   .option('--dry-run', 'propose the diff, write nothing')
@@ -195,7 +203,7 @@ program
   .command('create')
   .description('Mode A: full pipeline from a product brief to the output package')
   .requiredOption('--brief <file>', 'product brief (markdown)')
-  .option('--model <model>', 'codex | gpt-5 | claude')
+  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
   .action(async (opts: { brief: string; model?: string; interactive?: boolean }) => {
     const repo = repoOf(program.opts());
@@ -221,6 +229,48 @@ program
     }
   });
 
+const exportCmd = program
+  .command('export')
+  .description('emit supplier-ready files from repo state (deterministic; no LLM, no network)');
+
+exportCmd
+  .command('bom')
+  .description('write a supplier-format BOM (jlcpcb | digikey | mouser) from docs/BOM.md')
+  .requiredOption('--supplier <name>', 'jlcpcb | digikey | mouser')
+  .option('--boards <n>', 'number of boards to order', String(DEFAULT_BOARDS))
+  .option('--spares <percent>', 'spare parts percentage', String(DEFAULT_SPARES))
+  .option('--include-unverified', 'include UNVERIFIED rows that carry an MPN (never MPN-less rows)')
+  .action(async (opts: { supplier: string; boards: string; spares: string; includeUnverified?: boolean }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    try {
+      const supplier = parseSupplier(opts.supplier);
+      const boards = parseBoards(opts.boards);
+      const spares = parseSpares(opts.spares);
+      const res = await runExportBom({
+        repoRoot: repo,
+        supplier,
+        boards,
+        spares,
+        includeUnverified: opts.includeUnverified ?? false,
+      });
+      // Warnings go to stderr so a `> file` redirect of stdout stays clean and
+      // the excluded-rows report is still seen.
+      for (const w of res.warnings) console.error(w);
+      if (json) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`wrote ${res.outPath} (${res.included.length} part(s), ${res.excluded.length} excluded)`);
+      }
+      process.exit(0);
+    } catch (err) {
+      // ExportError carries an actionable message (bad flag, missing BOM, drift);
+      // anything else is unexpected. Both exit non-zero with no stack trace.
+      console.error(err instanceof ExportError ? err.message : (err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program.parseAsync().catch((err: Error) => {
   console.error(err.message);
   process.exit(1);

package/src/commands/create.ts

@@ -10,6 +10,7 @@ import type { RunMetaInput } from '../agent/runmeta.js';
 import type { ProgressRenderer } from '../agent/render.js';
 import { openspecInit } from '../openspec/cli.js';
 import { runCheck } from './check.js';
+import { emitCreateJlcpcbBom } from './export.js';
 
 /**
  * Mode A (`copperhead create`, SPEC §2.5): staged pipeline, each stage a
@@ -122,6 +123,18 @@ export interface CreateOptions {
   meta?: Omit<RunMetaInput, 'stage' | 'brief'>;
 }
 
+/**
+ * Stage 6 emits the JLCPCB assembly BOM deterministically alongside the agent's
+ * outputs package (create-pipeline delta). Called whenever the outputs stage is
+ * confirmed complete — on the pass that finishes it and on any later resume — so
+ * the file tracks the current BOM.md.
+ */
+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)`);
+}
+
 export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; completed: string[] }> {
   const brief = await readFile(path.resolve(opts.briefPath), 'utf8');
   // Hashed from the content already in hand: a brief edited mid-pipeline shows
@@ -135,6 +148,7 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
     if (await stage.isComplete(opts.repoRoot, config.docs)) {
       opts.log(`stage ${stage.name}: already complete (resuming past it)`);
       completed.push(stage.name);
+      await emitJlcpcbAfterOutputs(stage.name, opts);
       continue;
     }
     opts.log(`stage ${stage.name}: running`);
@@ -174,6 +188,7 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       return { ok: false, completed };
     }
     completed.push(stage.name);
+    await emitJlcpcbAfterOutputs(stage.name, opts);
   }
 
   const check = await runCheck(opts.repoRoot, opts.log);

package/src/commands/export.ts

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { loadConfig } from '../config.js';
+import { checkDrift } from '../memory/drift.js';
+import { buildExport, parseBom, SUPPLIERS, isSupplier, type Supplier, type ExportResult } from '../kicad/bom-export.js';
+
+/**
+ * `copperhead export bom` (capability supplier-bom-export): deterministic,
+ * LLM-free, network-free — safe anywhere `check` is safe. This module must never
+ * import a provider.
+ */
+export class ExportError extends Error {}
+
+export interface ExportBomOptions {
+  repoRoot: string;
+  supplier: Supplier;
+  boards: number;
+  spares: number;
+  includeUnverified: boolean;
+}
+
+export interface ExportBomResult extends ExportResult {
+  supplier: Supplier;
+  /** Repo-relative path the CSV was written to. */
+  outPath: string;
+}
+
+const OUT_DIR = 'outputs';
+
+export function outFileFor(supplier: Supplier): string {
+  return path.join(OUT_DIR, `${supplier}-bom.csv`);
+}
+
+/**
+ * Read BOM.md, refuse on drift, and write the supplier CSV to
+ * outputs/<supplier>-bom.csv. Throws ExportError with an actionable message for
+ * the caller to print and exit non-zero.
+ */
+export async function runExportBom(opts: ExportBomOptions): Promise<ExportBomResult> {
+  const config = await loadConfig(opts.repoRoot);
+  const bomPath = path.join(opts.repoRoot, config.docs, 'BOM.md');
+  if (!existsSync(bomPath)) {
+    throw new ExportError(
+      `no ${path.join(config.docs, 'BOM.md')} to export — run copperhead init on an existing project, or copperhead create`,
+    );
+  }
+
+  // BOM.md is the sole input, but it must agree with the schematic before it can
+  // be trusted as an ordering source (requirement "BOM.md is the sole input").
+  // Refuse loudly here rather than let a drifted BOM become a wrong order.
+  if (config.schematic && existsSync(path.join(opts.repoRoot, config.schematic))) {
+    const drift = await checkDrift(opts.repoRoot, config.docs, config.schematic);
+    if (drift.length) {
+      const lines = drift.map((m) => `  - ${m.doc} claims "${m.claim}" but actual is "${m.actual}"`).join('\n');
+      throw new ExportError(
+        `BOM.md drifts from the schematic; run \`copperhead check\` and resolve drift before ordering:\n${lines}`,
+      );
+    }
+  }
+
+  const rows = parseBom(await readFile(bomPath, 'utf8'));
+  const result = buildExport(rows, opts.supplier, {
+    boards: opts.boards,
+    spares: opts.spares,
+    includeUnverified: opts.includeUnverified,
+  });
+
+  const outPath = outFileFor(opts.supplier);
+  await mkdir(path.join(opts.repoRoot, OUT_DIR), { recursive: true });
+  await writeFile(path.join(opts.repoRoot, outPath), result.csv, 'utf8');
+
+  return { ...result, supplier: opts.supplier, outPath };
+}
+
+/**
+ * Deterministically emit the JLCPCB assembly BOM alongside the create stage-6
+ * outputs (create-pipeline delta). No-op when there is no BOM.md yet; never
+ * throws on drift here — the pipeline's own gates own that.
+ */
+export async function emitCreateJlcpcbBom(repoRoot: string): Promise<string | null> {
+  const config = await loadConfig(repoRoot);
+  const bomPath = path.join(repoRoot, config.docs, 'BOM.md');
+  if (!existsSync(bomPath)) return null;
+  const rows = parseBom(await readFile(bomPath, 'utf8'));
+  const { csv } = buildExport(rows, 'jlcpcb', { boards: 1, spares: 10, includeUnverified: false });
+  const outPath = outFileFor('jlcpcb');
+  await mkdir(path.join(repoRoot, OUT_DIR), { recursive: true });
+  await writeFile(path.join(repoRoot, outPath), csv, 'utf8');
+  return outPath;
+}
+
+/** Validate `--supplier`; throws ExportError listing the supported values. */
+export function parseSupplier(value: string): Supplier {
+  if (!isSupplier(value)) {
+    throw new ExportError(`unknown supplier "${value}"; supported: ${SUPPLIERS.join(', ')}`);
+  }
+  return value;
+}
+
+/** Validate `--boards`: a positive integer. */
+export function parseBoards(value: string): number {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new ExportError(`--boards must be a positive integer, got "${value}"`);
+  }
+  return n;
+}
+
+/** Validate `--spares`: a non-negative percentage. */
+export function parseSpares(value: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new ExportError(`--spares must be a non-negative number, got "${value}"`);
+  }
+  return n;
+}

package/src/config.ts

@@ -14,6 +14,12 @@ export interface CopperheadConfig {
   budgets: Record<string, number>;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
   generatedHashes?: Record<string, string>;
+  /**
+   * How the repo was bootstrapped. `"create"` marks a Mode A pipeline repo
+   * (fab gate requires DEVPLAN.md). Written by `copperhead create`; absent on
+   * init-only / hand-maintained repos.
+   */
+  origin?: 'create' | 'init';
 }
 
 export const CONFIG_DIR = '.copperhead';
@@ -51,6 +57,7 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
+    ...(raw.origin === 'create' || raw.origin === 'init' ? { origin: raw.origin } : {}),
   };
 }
 
@@ -70,8 +77,12 @@ export interface ResolvedModel {
  * Accepted values (same set for `--model`, COPPERHEAD_MODEL, and `model` in
  * .copperhead/config.json):
  *
- * - `claude`  : the Anthropic provider on its default model.
- * - `claude-*`: any Anthropic model id, passed through verbatim, e.g.
+ * - `claude-code`     : the Claude Code saved-login provider on its default
+ *                       model. Needs NO API key — it reuses the logged-in Claude
+ *                       Code CLI / CLAUDE_CODE_OAUTH_TOKEN via the Agent SDK.
+ * - `claude-code:<id>`: the same provider on a specific model id.
+ * - `claude`  : the Anthropic API provider on its default model.
+ * - `claude-*`: any Anthropic API model id, passed through verbatim, e.g.
  *               `claude-opus-4-5`. Anything starting with `claude` routes here.
  * - `codex`   : the locally installed Codex CLI using its saved ChatGPT login.
  * - `codex:*` : Codex CLI with an explicit model id, e.g. `codex:gpt-5.6`.
@@ -80,10 +91,13 @@ export interface ResolvedModel {
  *               `gpt-5-mini` or `o3`.
  *
  * Routing is prefix-based, not a fixed list (see makeProvider in agent/loop.ts),
- * so a model released after this build still works without a code change. The
- * cost is that a typo like `claud-sonnet-5` silently routes to OpenAI and fails
- * there. Anthropic and direct OpenAI providers require their API keys; `codex`
- * instead requires a locally installed and authenticated Codex CLI.
+ * matched top to bottom: `claude-code`/`claude-code:<id>` is checked BEFORE the
+ * `claude*` prefix, so it is never captured by the Anthropic API route. A model
+ * released after this build still works without a code change. The cost is that
+ * a typo like `claud-sonnet-5` silently routes to OpenAI and fails there.
+ * Anthropic and direct OpenAI providers require their API keys; `codex` requires
+ * a locally installed and authenticated Codex CLI, and `claude-code` requires a
+ * Claude Code login (CLAUDE_CODE_OAUTH_TOKEN); neither needs a model API key.
  */
 export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): ResolvedModel {
   if (flag) return { model: flag, source: 'flag' };

package/src/kicad/bom-export.ts

@@ -0,0 +1,321 @@
+import { parseMarkdownTables, type TableRow } from '../memory/bom-table.js';
+
+/**
+ * Supplier-format BOM export (capability supplier-bom-export). Deterministic,
+ * LLM-free, network-free: a pure transformation of BOM.md into files a supplier
+ * accepts without hand-editing. BOM.md is the sole input (design D1) — it is
+ * already drift-checked against the schematic, so exports inherit that
+ * consistency guarantee.
+ */
+
+export type Supplier = 'jlcpcb' | 'digikey' | 'mouser';
+
+export const SUPPLIERS: readonly Supplier[] = ['jlcpcb', 'digikey', 'mouser'];
+
+/** CLI defaults for the quantity flags, shared so the "ignored for jlcpcb"
+ *  note fires only when the user actually set a non-default value. */
+export const DEFAULT_BOARDS = 1;
+export const DEFAULT_SPARES = 10;
+
+export function isSupplier(s: string): s is Supplier {
+  return (SUPPLIERS as readonly string[]).includes(s);
+}
+
+export interface BomRow {
+  refdes: string;
+  value: string;
+  footprint: string;
+  /** MPN column value as written (may be a placeholder like "UNVERIFIED"). */
+  mpn: string;
+  manufacturer: string;
+  /** LCSC part number when a column carries it, else ''. */
+  lcsc: string;
+  /** True when any cell carries the standalone token UNVERIFIED. */
+  unverified: boolean;
+  /** True when the MPN column carries an orderable part number (not a placeholder). */
+  hasMpn: boolean;
+}
+
+// Header aliases → canonical field. Matched after normalizing a header cell to
+// lowercase alphanumerics, so "LCSC Part #" and "lcsc_part" both hit `lcsc`.
+const HEADER_ALIASES: Record<string, keyof Pick<BomRow, 'refdes' | 'value' | 'footprint' | 'mpn' | 'manufacturer' | 'lcsc'>> = {
+  refdes: 'refdes',
+  ref: 'refdes',
+  designator: 'refdes',
+  reference: 'refdes',
+  value: 'value',
+  comment: 'value',
+  val: 'value',
+  footprint: 'footprint',
+  package: 'footprint',
+  mpn: 'mpn',
+  manufacturerpartnumber: 'mpn',
+  mfrpartnumber: 'mpn',
+  mfrpart: 'mpn',
+  partnumber: 'mpn',
+  manufacturer: 'manufacturer',
+  mfr: 'manufacturer',
+  lcsc: 'lcsc',
+  lcscpart: 'lcsc',
+  lcscpartnumber: 'lcsc',
+};
+
+const norm = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+// MPN cells that mean "no orderable part number yet". `UNVERIFIED` is the
+// init/scaffold placeholder (src/memory/scaffold.ts writes it into the MPN
+// column for every extracted symbol); the rest are common human shorthand.
+const MPN_PLACEHOLDERS = new Set(['', 'unverified', 'tbd', 'todo', 'tbc', 'na', 'none', '-', '—', '?']);
+
+const isMpnPlaceholder = (mpn: string): boolean => MPN_PLACEHOLDERS.has(mpn.trim().toLowerCase());
+
+const UNVERIFIED_RE = /\bUNVERIFIED\b/i;
+
+/**
+ * Parse BOM.md into rows by column header, tolerating extra/reordered columns.
+ * Only the header row and data rows of the first parts table are used; a table
+ * without a recognizable Refdes header yields no rows.
+ *
+ * NOTE: the drift gate this exporter runs behind (checkDrift in
+ * ../memory/drift.ts) reads Refdes|Value|Footprint *by position*, not by header.
+ * So while this parser tolerates reordering those base columns, reordering them
+ * makes checkDrift compare the wrong cells and the export refuses with a bogus
+ * drift message. Keep the base three columns first and in order; only append.
+ */
+export function parseBom(md: string): BomRow[] {
+  const tableRows = parseMarkdownTables(md);
+  const headerIdx = tableRows.findIndex((r) => r.cells.some((c) => HEADER_ALIASES[norm(c)] === 'refdes'));
+  const header = headerIdx === -1 ? undefined : tableRows[headerIdx];
+  if (!header) return [];
+  const col: Partial<Record<keyof BomRow, number>> = {};
+  header.cells.forEach((c, i) => {
+    const field = HEADER_ALIASES[norm(c)];
+    // First occurrence wins, so a stray later column never shadows the real one.
+    if (field && col[field] === undefined) col[field] = i;
+  });
+
+  const at = (row: TableRow, field: keyof BomRow): string => {
+    const i = col[field];
+    return i === undefined ? '' : (row.cells[i] ?? '').trim();
+  };
+
+  const rows: BomRow[] = [];
+  for (const row of tableRows.slice(headerIdx + 1)) {
+    const refdes = at(row, 'refdes');
+    if (!refdes) continue; // blank line / stray row
+    const mpn = at(row, 'mpn');
+    rows.push({
+      refdes,
+      value: at(row, 'value'),
+      footprint: at(row, 'footprint'),
+      mpn,
+      manufacturer: at(row, 'manufacturer'),
+      lcsc: at(row, 'lcsc'),
+      unverified: row.cells.some((c) => UNVERIFIED_RE.test(c)),
+      hasMpn: !isMpnPlaceholder(mpn),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Passive footprint classifier (design D4): the library item after the `:` in a
+ * KiCad footprint id starts with `R_`, `C_`, or `L_` for the passive classes
+ * that lose parts to handling. Bare footprint names (no library) are matched
+ * too, so `R_0603` and `Resistor_SMD:R_0603_1608Metric` both classify.
+ */
+export function isPassiveFootprint(footprint: string): boolean {
+  const item = footprint.includes(':') ? footprint.slice(footprint.lastIndexOf(':') + 1) : footprint;
+  return /^[RCL]_/.test(item.trim());
+}
+
+/**
+ * Order quantity for one BOM line (requirement "Quantity arithmetic"):
+ * `ceil(perBoardCount × boards × (1 + spares/100))`, raised to
+ * `perBoardCount × boards + 2` for passive lines when the percentage yields
+ * less — losing two 0402s to tweezers is the norm and percentage-only spares
+ * under-order low-count passive lines (design D4).
+ */
+export function orderQuantity(
+  perBoardCount: number,
+  boards: number,
+  sparesPercent: number,
+  isPassive: boolean,
+): number {
+  const base = perBoardCount * boards;
+  // `base * (100 + spares) / 100` keeps the multiply in whole units before the
+  // divide, and the epsilon absorbs IEEE-754 dust so an exact result like 110
+  // does not ceil to 111 (100 × 1.1 is 110.00000000000001 in float). The dust is
+  // ~1e-13; 1e-9 is far below any real fractional quantity, so genuine fractions
+  // (44.5 → 45) are unaffected.
+  const withSpares = Math.ceil((base * (100 + sparesPercent)) / 100 - 1e-9);
+  return isPassive ? Math.max(withSpares, base + 2) : withSpares;
+}
+
+/** Natural refdes ordering: R2 before R10, and R* before U*. */
+function naturalCompare(a: string, b: string): number {
+  const pa = a.match(/^([A-Za-z]*)(\d*)/);
+  const pb = b.match(/^([A-Za-z]*)(\d*)/);
+  const alpha = (pa?.[1] ?? '').localeCompare(pb?.[1] ?? '');
+  if (alpha !== 0) return alpha;
+  const na = pa?.[2] ? parseInt(pa[2], 10) : 0;
+  const nb = pb?.[2] ? parseInt(pb[2], 10) : 0;
+  if (na !== nb) return na - nb;
+  return a.localeCompare(b);
+}
+
+/** RFC-4180 field quoting: quote when the field holds a comma, quote, or newline. */
+function csvField(value: string): string {
+  return /[",\n\r]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+const csvRow = (fields: string[]): string => fields.map(csvField).join(',');
+
+export interface ExportOptions {
+  boards: number;
+  spares: number;
+  includeUnverified: boolean;
+}
+
+export interface ExportResult {
+  /** The supplier CSV, ending in a newline. */
+  csv: string;
+  /** Rows that made it into the file, in emit order. */
+  included: BomRow[];
+  /** Rows excluded, with the reason, for the warnings footer. */
+  excluded: { row: BomRow; reason: string }[];
+  /** Human-readable warning/notice lines (stderr + --json). */
+  warnings: string[];
+}
+
+interface Line {
+  rows: BomRow[];
+  /** Representative row (first, in refdes order) for value/footprint/mpn/etc. */
+  head: BomRow;
+  designators: string[];
+}
+
+/**
+ * Split rows into included/excluded by the ordering rules (requirement
+ * "Unorderable rows are excluded and reported"): MPN-less rows are always
+ * excluded; UNVERIFIED rows are excluded unless `includeUnverified`, and even
+ * then only when they carry a real MPN.
+ */
+function partition(
+  rows: BomRow[],
+  includeUnverified: boolean,
+): { included: BomRow[]; excluded: ExportResult['excluded'] } {
+  const included: BomRow[] = [];
+  const excluded: ExportResult['excluded'] = [];
+  for (const row of rows) {
+    if (!row.hasMpn) {
+      excluded.push({ row, reason: 'no MPN' });
+    } else if (row.unverified && !includeUnverified) {
+      excluded.push({ row, reason: 'UNVERIFIED' });
+    } else {
+      included.push(row);
+    }
+  }
+  return { included, excluded };
+}
+
+function groupBy(rows: BomRow[], key: (r: BomRow) => string): Line[] {
+  const map = new Map<string, BomRow[]>();
+  for (const r of rows) {
+    const k = key(r);
+    const arr = map.get(k);
+    if (arr) arr.push(r);
+    else map.set(k, [r]);
+  }
+  const lines: Line[] = [];
+  for (const groupRows of map.values()) {
+    const sorted = [...groupRows].sort((a, b) => naturalCompare(a.refdes, b.refdes));
+    // Groups are never empty (a key exists because a row produced it).
+    lines.push({ rows: sorted, head: sorted[0]!, designators: sorted.map((r) => r.refdes) });
+  }
+  // Deterministic line order: by the first designator of each line.
+  return lines.sort((a, b) => naturalCompare(a.designators[0]!, b.designators[0]!));
+}
+
+function buildWarnings(
+  supplier: Supplier,
+  included: BomRow[],
+  excluded: ExportResult['excluded'],
+  opts: ExportOptions,
+): string[] {
+  const { includeUnverified } = opts;
+  const warnings: string[] = [];
+  for (const { row, reason } of excluded) {
+    const hint =
+      reason === 'no MPN'
+        ? 'add an MPN in BOM.md — unorderable without one'
+        : 'verify against the datasheet or re-run with --include-unverified';
+    warnings.push(`EXCLUDED (${reason}): ${row.refdes} (${row.value || 'no value'}) — ${hint}`);
+  }
+  if (includeUnverified) {
+    for (const row of included) {
+      if (row.unverified) {
+        warnings.push(`INCLUDED but UNVERIFIED (--include-unverified): ${row.refdes} (${row.mpn}) — confirm before ordering`);
+      }
+    }
+  }
+  if (supplier === 'jlcpcb') {
+    // The JLCPCB assembly format has no quantity column — quantity is set from
+    // the board count entered at upload — so --boards/--spares never reach this
+    // file. Say so when the user supplied a non-default value, or they may order
+    // the wrong count expecting the flags to have taken effect.
+    if (opts.boards !== DEFAULT_BOARDS || opts.spares !== DEFAULT_SPARES) {
+      warnings.push(
+        'NOTE: --boards/--spares are ignored for jlcpcb — quantity is set from the board count you enter at JLCPCB upload',
+      );
+    }
+    const blank = included.filter((r) => !r.lcsc).map((r) => r.refdes);
+    if (blank.length) {
+      warnings.push(
+        `NOTE: no LCSC part # for ${blank.join(', ')} — JLCPCB accepts the upload but needs manual matching for these`,
+      );
+    }
+  }
+  return warnings;
+}
+
+function emitJlcpcb(lines: Line[]): string {
+  // JLCPCB assembly-service BOM: one line per Comment+Footprint+LCSC, designators
+  // grouped. Quantity is derived by JLCPCB from the designator count × the board
+  // count entered at upload, so there is no quantity column here (design/proposal).
+  const header = 'Comment,Designator,Footprint,LCSC Part #';
+  const body = lines.map((l) =>
+    csvRow([l.head.value, l.designators.join(','), l.head.footprint, l.head.lcsc]),
+  );
+  return [header, ...body].join('\n') + '\n';
+}
+
+function emitCart(lines: Line[], opts: ExportOptions, mpnHeader: string): string {
+  // DigiKey / Mouser cart upload: one line per MPN with a computed order
+  // quantity and the designators as the customer reference.
+  const header = `${mpnHeader},Manufacturer,Quantity,Customer Reference`;
+  const body = lines.map((l) => {
+    const qty = orderQuantity(l.designators.length, opts.boards, opts.spares, isPassiveFootprint(l.head.footprint));
+    return csvRow([l.head.mpn, l.head.manufacturer, String(qty), l.designators.join(',')]);
+  });
+  return [header, ...body].join('\n') + '\n';
+}
+
+/**
+ * Build the supplier CSV plus its warnings from parsed BOM rows. Pure: no I/O,
+ * so the emitters are golden-file testable in isolation (design D5).
+ */
+export function buildExport(rows: BomRow[], supplier: Supplier, opts: ExportOptions): ExportResult {
+  const { included, excluded } = partition(rows, opts.includeUnverified);
+  const lines =
+    supplier === 'jlcpcb'
+      ? groupBy(included, (r) => `${r.value}${r.footprint}${r.lcsc}`)
+      : groupBy(included, (r) => r.mpn);
+
+  let csv: string;
+  if (supplier === 'jlcpcb') csv = emitJlcpcb(lines);
+  else if (supplier === 'digikey') csv = emitCart(lines, opts, 'Manufacturer Part Number');
+  else csv = emitCart(lines, opts, 'Mfr. Part Number');
+
+  return { csv, included, excluded, warnings: buildWarnings(supplier, included, excluded, opts) };
+}