@henols/vice-mcp 0.2.1 → 0.2.2

package/r2000-cli.ts

@@ -1,1103 +0,0 @@
-#!/usr/bin/env node
-// r2000-cli.ts -- the thin CLI ergonomics layer over the guarded regenerator2000
-// seam (D-06). Reached as `vice-mcp r2000 <verb>` because that bin is the only
-// surface that resolves identically across the Claude Code plugin route and
-// both npm-installer routes: `installer/bin/cli.mjs`'s `viceServerEntry()`
-// always launches this server via `npx` in BOTH npm-installer modes, and
-// neither route places `.claude/mcp/vice/*.ts` as plain files inside a
-// consuming project for some other filesystem-path-resolving design to find.
-//
-// WHAT NOT TO DO, named concretely:
-//   - Never accept a caller-supplied passthrough of extra flags to
-//     regenerator2000 (D-07). Every child-process argv is built only by
-//     `r2000-launch.ts`'s fixed builders (`buildExportAsmArgs()`,
-//     `buildVerifyArgs()`) -- this file adds exactly two options of its own
-//     (`--entry`, `--out`), neither of which reaches the child process argv.
-//   - Never auto-pick a `.d64` entry when the caller does not name one (D-02).
-//     A silent auto-pick would happily analyse a cracktro or loader stub's
-//     bytes instead of the actual game -- precisely the failure
-//     `c64-provenance-diff` exists to prevent elsewhere in this project. Zero
-//     `--entry` means: print the directory listing, tell the user to re-run
-//     with `--entry NAME`, and exit 2. Never guess.
-//   - Never dispatch a flat `.raw`/`.bin` capture by its BYTE LENGTH alone
-//     (WR-07). The incident: a 4096-byte `capture.raw` fell through to the
-//     `bytes.length === 65536` branch's `else`, which is `parsePrg()` --
-//     whose first two bytes become the load address -- so a truncated
-//     capture silently "bootstrapped" with origin `$62c5` (its own first two
-//     payload bytes read backwards) and exit 0, with every downstream
-//     address wrong and no diagnostic. That is exactly the "silently guess"
-//     behaviour D-02 exists to forbid, just for a different input shape.
-//     `.raw`/`.bin` inputs are now dispatched by EXTENSION, before the
-//     length check, so `flatImageOrigin()`'s own named refusal (any length
-//     other than exactly 65536) is always reachable for those two
-//     extensions.
-
-//
-// `runR2000Cli()` returns an exit code and never terminates the process
-// itself, so it is testable in-process as well as from the bin (the bin,
-// `vice-proxy.ts`, is the only place that ends the process with this
-// function's return value). All output goes to stdout/stderr via
-// `console.log`/`console.error` -- never a thrown stack trace for an
-// expected, user-facing failure (missing file, unknown `.d64` entry, `.vsf`
-// input): each of those produces a single actionable line instead.
-//
-// Import nothing from `hostpath.ts` or `containerpath.ts`. Every path this
-// CLI handles is already container-side: regenerator2000 runs on the MCP
-// proxy's side of the boundary (D-R4), and translating any of these
-// arguments would be the mirror image of the DERIV-07 screenshot-path trap,
-// where a client-side-derived path was wrongly translated a second time.
-// This absence is asserted structurally by `hostpath-consumers.test.ts`
-// (D-08), not merely stated here.
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, extname, join } from "node:path";
-
-import { buildExportAsmArgs, runR2000, R2000ViceFlagError } from "./r2000-launch.ts";
-import { synthesizeProject, parsePrg, flatImageOrigin } from "./r2000-project.ts";
-import { listEntries, extractEntry, assertPlainImage } from "./r2000-d64.ts";
-import { verifyProject } from "./r2000-verify.ts";
-import { generateEnums } from "./r2000-enum-gen.ts";
-import { exportLabels, importLabels } from "./r2000-symbols.ts";
-import { renderMemoryMap, checkRenderedMemoryMap } from "./r2000-memmap-render.ts";
-
-const NPX_INVOCATION = "npx -y @henols/vice-mcp r2000 <verb>";
-const PLUGIN_INVOCATION = "node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 <verb>";
-
-// `verify` is the criterion-4 (R2000-06) proof route: it runs
-// regenerator2000's own `--verify` and reports the verdict `r2000-verify.ts`'s
-// `acmeVerdict()` derives from the PARSED ACME result line -- never from the
-// child process's exit code (D-10). A skipped ACME reads as a failure here,
-// not as an absence, even on a transcript whose own exit code and summary
-// line both say "passed" -- see r2000-verify.ts's header comment and
-// r2000-verify.test.ts's pinned trap transcript for the live incident this
-// guards against. A future maintainer reading only this file must not
-// reintroduce a `result.status === 0` shortcut anywhere in `cmdVerify()`.
-//
-// FLOW-02 (D-11.1-01): the `.vsf` paragraph below used to end by naming a
-// specific numbered phase as the eventual owner of closing that gap. That
-// phase shipped and never touched `.vsf` bootstrap, so the sentence told a
-// user to wait on a remediation that would never arrive. A phase number is
-// a planning artifact -- it has no place in a shipped diagnostic. Corrected
-// to name the backlog file instead; see the matching fix in
-// `bootstrapProject()` below and `docs-dangling-refs.test.ts`'s guard
-// against this defect class recurring anywhere in this file's string
-// literals.
-const USAGE = `usage (npm install):    ${NPX_INVOCATION}
-usage (plugin/in-repo): ${PLUGIN_INVOCATION}
-
-verbs:
-  bootstrap <input> [--entry NAME] [--out PROJECT] [--force]
-      Accepts a .prg, a .d64 (pick an entry with --entry), or a flat 64K
-      .raw/.bin capture. Writes a .regen2000proj to --out (default: the
-      input path with its extension replaced by .regen2000proj). Refuses to
-      overwrite an existing file at that path unless --force is given. A
-      .regen2000proj input is refused outright -- bootstrap never re-reads
-      one; use export-asm or verify on it directly.
-
-  export-asm <input-or-project> [--entry NAME] [--out FILE] [--force]
-      If given a .regen2000proj it is used directly; otherwise this bootstraps
-      the input to a temporary project first, so a bare .prg becomes ACME
-      source in one command with no human interaction (--entry is forwarded
-      to that bootstrap step, and is required the same way it is for
-      bootstrap itself when the input is a .d64 -- IN-06/D-11.1-04: this line
-      used to omit --entry even though the verb already accepted and used
-      it, which is corrected here alongside closing the sibling defect of
-      accepting-but-silently-dropping an option). Writes ACME source to
-      --out (default: the input stem plus .a). Refuses to overwrite an
-      existing file at that path unless --force is given.
-
-  verify <input-or-project> [--entry NAME]
-      The criterion-4 (R2000-06) reassembly proof: exports and reassembles
-      through regenerator2000's own --verify, and prints each assembler's
-      parsed result line. Exits 0 only when ACME's own line reports success --
-      a skipped ACME is a failure here, never a pass, regardless of the child
-      process's own exit code or its "All roundtrip verifications passed."
-      summary line (D-10). Accepts a .regen2000proj directly, or bootstraps a
-      bare .prg/.d64/flat-64K input to a temporary project first, exactly
-      like export-asm.
-
-  gen-enums <project> [--max-results N]
-      Generates program-specific enums from the register writes an existing
-      .regen2000proj's disassembly already contains (D-20/D-22/D-23,
-      R2000-13) -- one variant per DISTINCT value actually written, named
-      from the curated bit-name table (r2000-regbits.json), applied at every
-      matching immediate-load address, and saved. Prints total/paired/
-      unpaired register-store counts and, per created/updated enum, its name
-      and variant count. Requires an EXISTING .regen2000proj (this verb does
-      not bootstrap from a raw input -- run bootstrap first). --max-results
-      overrides the 10000-row ceiling on each of the two search passes this
-      verb runs internally; exits non-zero, printing the reason, when either
-      pass returns exactly its own ceiling (coverage may be incomplete) or
-      when generateEnums() itself refuses (an illegal generated identifier,
-      or an enum install that failed outright).
-
-  export-lbl <project> [--out FILE]
-      Exports the project's user-defined labels to a VICE label file
-      (R2000-14): "al C:xxxx .Name" lines that stock-symbols.ts's existing
-      parser accepts. The written file is read back and validated through
-      that same parser before this verb reports success -- a regenerator2000
-      exit code has lied before (r2000-verify.ts's D-10 founding incident),
-      so the exit code alone is never trusted. Defaults --out to the project
-      path's stem plus .lbl. Prints the written path and the symbol count
-      parsed back from the file. Requires an EXISTING .regen2000proj (this
-      verb does not bootstrap from a raw input).
-
-  import-lbl <project> <lbl>
-      Imports a VICE label file into the project (R2000-15, the D-28 path):
-      --import_lbl paired with --mcp-server-stdio plus an explicit
-      r2000_save_project -- the only combination that actually persists the
-      import (--import_lbl alone under --headless silently discards it,
-      main.rs:800-806). Prints the names imported, then an explicit line
-      naming the fact that the import was persisted by an explicit save
-      (proven by re-reading the project from disk in a fresh process, never
-      trusted from the child's own success text alone). Exits non-zero,
-      printing the reason, when the result is not disk-verified, or when the
-      given .lbl fails stock-symbols.ts's own size/line/symbol ceilings.
-      Requires an EXISTING .regen2000proj (this verb does not bootstrap from
-      a raw input).
-
-  render-memmap <project> --provenance FILE [--out FILE] [--check]
-      Generates the Markdown memory map from the project's store plus a
-      validated provenance sidecar (D-24: the store is canonical, this
-      output is a GENERATED VIEW -- never hand-edit it). Without --check,
-      writes --out (default: memory-map.md beside the project) and prints
-      the row count, the number of [unknown]-graded rows, and the render
-      digest. With --check, re-renders in memory and compares against the
-      file at --out: prints "in sync" and exits 0 when they match, prints
-      the first differing line and exits non-zero on drift (from either a
-      hand edit OR a store-side change since the file was last rendered),
-      or prints "missing" and exits non-zero when --out does not exist yet.
-      --check is how a hand edit to the generated file is caught. Requires
-      an EXISTING .regen2000proj and an EXISTING --provenance sidecar (this
-      verb does not bootstrap from a raw input).
-
-.d64 input with no --entry named prints the directory listing and exits 2 --
-this CLI never guesses which entry to use (D-02).
-
-.vsf input is not supported by any verb -- regenerator2000's auto-detected
-machine-type field is correct only by coincidence for C64 snapshots, and no
-R2000-* requirement covers .vsf as a bootstrap input (D-34). The idea is
-recorded as backlog at
-.planning/todos/pending/2026-08-20-vsf-as-a-bootstrap-input.md. Convert to
-.prg, .d64 or a flat 64K capture.
-`;
-
-function errMsg(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
-
-interface ParsedArgs {
-  positional: string[];
-  entry?: string;
-  out?: string;
-  force?: boolean;
-  entryMissingValue?: boolean;
-  outMissingValue?: boolean;
-}
-
-/** Fixed, closed option set -- exactly `--entry`, `--out` and `--force`. No
- * rest field, no passthrough: an unrecognised flag is treated as a
- * positional token (and will surface as "input file not found" rather than
- * silently reaching regenerator2000, since nothing here ever forwards raw
- * argv to the child process).
- *
- * WR-08: a value that is absent or itself `--`-shaped is a refusal
- * (`entryMissingValue`/`outMissingValue`), never silently taken as the
- * option's value -- the same posture `parseExportLblArgs()` below already
- * has for `--out`. Before this fix, `entry = rest[++i]` and `out =
- * rest[++i]` took the NEXT token unconditionally, so `bootstrap x.prg --out
- * --entry FOO` parsed as `{ out: "--entry", entry: undefined }` and
- * `bootstrapProject()` went on to `writeFileSync()` a project literally
- * named `--entry` -- a dash-prefixed filename that is a shell-glob hazard
- * for whatever later reads that directory. Callers check the two
- * `*MissingValue` flags and refuse with a one-line message naming the
- * option that was actually short a value (WR-09's lesson: `--out --entry
- * FOO` must say `--out` is missing a value, never that `--entry` is a bad
- * path) -- never throw, so `bootstrapProject()`'s never-throw contract
- * holds for every caller of this parser too. */
-function parseArgs(rest: string[]): ParsedArgs {
-  const positional: string[] = [];
-  let entry: string | undefined;
-  let out: string | undefined;
-  let force = false;
-  let entryMissingValue = false;
-  let outMissingValue = false;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i]!;
-    if (a === "--entry") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("--")) {
-        entryMissingValue = true;
-      } else {
-        entry = value;
-        i++;
-      }
-    } else if (a === "--out") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("--")) {
-        outMissingValue = true;
-      } else {
-        out = value;
-        i++;
-      }
-    } else if (a === "--force") {
-      force = true;
-    } else {
-      positional.push(a);
-    }
-  }
-  return { positional, entry, out, force, entryMissingValue, outMissingValue };
-}
-
-/**
- * IN-06 (D-11.1-04): the ONE declared verb-to-accepted-options fact in this
- * file. Every option every verb's own code actually reads is listed here --
- * ground truth, not merely what USAGE happens to say (see the export-asm
- * comment above: USAGE previously under-documented a real, working
- * `--entry` forward, which this map's own test caught and which USAGE was
- * corrected to match). `verify`'s entry is the fix for IN-06 itself:
- * `parseArgs()` parses `--out` for every verb because it is a single shared
- * parser, but `cmdVerify()` never reads the resulting `out` field -- so a
- * caller who passed `--out` to `verify` got no error and no effect. Listing
- * only `--entry` here means `checkAcceptedOptions()` below refuses `--out`
- * (and `--force`) before `cmdVerify()` ever runs.
- */
-export const VERB_OPTIONS: Readonly<Record<string, readonly string[]>> = Object.freeze({
-  bootstrap: ["--entry", "--out", "--force"],
-  "export-asm": ["--entry", "--out", "--force"],
-  verify: ["--entry"],
-  "gen-enums": ["--max-results"],
-  "export-lbl": ["--out"],
-  "import-lbl": [],
-  "render-memmap": ["--provenance", "--out", "--check"],
-});
-
-/**
- * The one shared refusal check IN-06 generalises to every verb (WR-08's
- * closed-option-set posture, applied uniformly rather than verb by verb).
- * Scans `rest` for any `--flag`-shaped token not in `verb`'s accepted set
- * from `VERB_OPTIONS` and returns a one-line refusal naming the flag and the
- * accepted set; returns `undefined` when every flag-shaped token is
- * accepted (or when `verb` is not a key in the map at all, so an unknown
- * verb still falls through to `runR2000Cli()`'s own "unknown verb"
- * message). Never throws -- this file's never-throw posture applies here
- * too.
- */
-export function checkAcceptedOptions(verb: string, rest: string[]): string | undefined {
-  const accepted = VERB_OPTIONS[verb];
-  if (!accepted) return undefined;
-  for (const token of rest) {
-    if (token.startsWith("--") && !accepted.includes(token)) {
-      const acceptedList = accepted.length > 0 ? accepted.join(", ") : "none";
-      return `${verb}: unknown option "${token}" -- not accepted by this verb (accepted: ${acceptedList})`;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Refuses to overwrite an existing file at `outPath` unless the caller
- * passed `--force`. Shared by every verb that writes an output file
- * (`bootstrap`, `export-asm`) so overwrite safety stays uniform rather than
- * one verb accreting a check the others lack (CR-01/CR-02).
- */
-function refuseOverwrite(outPath: string, force: boolean | undefined, verbLabel: string, extraHint = ""): boolean {
-  if (force || !existsSync(outPath)) return true;
-  console.error(
-    `${verbLabel}: refusing to overwrite the existing file ${outPath}${extraHint} -- ` +
-      `pass --force to overwrite it deliberately.`,
-  );
-  return false;
-}
-
-interface BootstrapOutcome {
-  code: number;
-  path?: string;
-}
-
-/**
- * Shared bootstrap logic used both by the `bootstrap` verb directly and by
- * `export-asm` when handed a bare input rather than an existing
- * `.regen2000proj`. Never throws for an expected, user-facing failure --
- * every branch below returns a `{ code }` result with a one-line message
- * already printed to stderr/stdout, so callers never see a stack trace for a
- * missing file, an unknown `.d64` entry, or a `.vsf` input.
- */
-function bootstrapProject(
-  input: string,
-  opts: { entry?: string; outPath?: string; force?: boolean },
-): BootstrapOutcome {
-  if (!existsSync(input)) {
-    console.error(`bootstrap: input file not found: ${input}`);
-    return { code: 1 };
-  }
-
-  const ext = extname(input).toLowerCase();
-  if (ext === ".regen2000proj") {
-    // CR-02: without this branch, a .regen2000proj input fell through to
-    // parsePrg(), which happily "parsed" the JSON text as a .prg (its first
-    // two bytes read as a bogus little-endian load address), and the
-    // derived out-path was then byte-identical to the input path --
-    // clobbering the project with garbage synthesised from its own text.
-    // Decision (see commit message): refuse rather than silently pass it
-    // through unchanged -- bootstrap's whole job is synthesising a project
-    // from RAW input, and a caller who names an existing .regen2000proj as
-    // bootstrap's input almost certainly meant export-asm or verify, which
-    // already accept a .regen2000proj directly and do the right thing.
-    console.error(
-      `bootstrap: ${input} is already a .regen2000proj -- bootstrap synthesises project files from raw ` +
-        "input (a .prg, a .d64 entry, or a flat 64K capture), it never re-reads one. Use export-asm or " +
-        "verify on it directly.",
-    );
-    return { code: 1 };
-  }
-  if (ext === ".vsf") {
-    // FLOW-02 (D-11.1-01): this refusal used to end by naming a specific
-    // numbered phase as the eventual owner of closing that gap. That phase
-    // shipped and never touched `.vsf` bootstrap -- the sentence pointed a
-    // user at a remediation path that would never exist. Name the backlog
-    // file instead; the WHY (the machine-type coincidence) stays, since
-    // that is the reason a user actually needs.
-    console.error(
-      "bootstrap: .vsf input is not supported -- regenerator2000's auto-detected machine-type field only " +
-        'reads correctly by coincidence ("C64SC" falls through to its own default, matching none of its ' +
-        "literal System arms). Filed as backlog, not covered by any R2000-* requirement (D-34): see " +
-        ".planning/todos/pending/2026-08-20-vsf-as-a-bootstrap-input.md. Convert to .prg, .d64 or a flat " +
-        "64K capture instead.",
-    );
-    return { code: 1 };
-  }
-
-  let bytes: Uint8Array;
-  try {
-    bytes = readFileSync(input);
-  } catch (err) {
-    console.error(`bootstrap: could not read ${input}: ${errMsg(err)}`);
-    return { code: 1 };
-  }
-
-  let origin: number;
-  let body: Uint8Array;
-
-  if (ext === ".d64") {
-    try {
-      assertPlainImage(bytes);
-    } catch (err) {
-      console.error(`bootstrap: ${errMsg(err)}`);
-      return { code: 1 };
-    }
-
-    if (!opts.entry) {
-      // D-02's fail-loud contract, implemented here and nowhere else: never
-      // pick an entry. A silent auto-pick would happily analyse a cracktro
-      // or loader stub instead of the game.
-      let entries;
-      try {
-        entries = listEntries(bytes);
-      } catch (err) {
-        console.error(`bootstrap: ${errMsg(err)}`);
-        return { code: 1 };
-      }
-      console.log(`bootstrap: ${input} is a .d64 image with no --entry given -- directory listing:`);
-      if (entries.length === 0) {
-        console.log("  (no entries)");
-      } else {
-        for (const e of entries) {
-          console.log(`  ${e.name}\t${e.type}\t${e.sizeBlocks} block(s)`);
-        }
-      }
-      console.log("Re-run with --entry NAME to choose one. This CLI never guesses (D-02).");
-      return { code: 2 };
-    }
-
-    let extracted: Uint8Array;
-    try {
-      extracted = extractEntry(bytes, opts.entry);
-    } catch (err) {
-      console.error(`bootstrap: ${errMsg(err)}`);
-      return { code: 1 };
-    }
-    try {
-      ({ origin, body } = parsePrg(extracted));
-    } catch {
-      // WR-09 (D-11.1-04): parsePrg() throws only when its input is under 3
-      // bytes (a .prg needs a 2-byte load address plus at least 1 payload
-      // byte). Every sibling branch below already wraps its own parsePrg()
-      // call -- this was the one gap, and its unwrapped throw escaped to
-      // runR2000Cli()'s last-resort net, surfacing as `r2000: parsePrg:
-      // input is N byte(s)` -- a message naming an internal function to a
-      // user who only ever supplied a disk image. Reworded entirely in the
-      // caller's own vocabulary (the entry name, never `parsePrg`) so the
-      // never-throw contract holds on this branch too.
-      console.error(
-        `bootstrap: entry "${opts.entry}" holds ${extracted.length} byte(s) -- not a loadable program ` +
-          "(a .prg needs at least 3 bytes: a 2-byte load address plus at least 1 payload byte). Choose a " +
-          "different --entry, or use a different input.",
-      );
-      return { code: 1 };
-    }
-  } else if (ext === ".raw" || ext === ".bin") {
-    // WR-07: dispatch by extension, not by byte length, so a truncated or
-    // oversized flat capture hits flatImageOrigin()'s own named refusal
-    // instead of falling through to parsePrg() and being silently
-    // reinterpreted as a .prg (see the header comment above).
-    try {
-      origin = flatImageOrigin(bytes);
-    } catch (err) {
-      console.error(`bootstrap: ${errMsg(err)}`);
-      return { code: 1 };
-    }
-    body = bytes;
-  } else if (bytes.length === 65536) {
-    // Extension-less flat capture (no `.raw`/`.bin` suffix): the only
-    // remaining route by which a 65536-byte flat image reaches
-    // flatImageOrigin() is this length check, kept for that case alone.
-    origin = flatImageOrigin(bytes);
-    body = bytes;
-  } else {
-    try {
-      ({ origin, body } = parsePrg(bytes));
-    } catch (err) {
-      console.error(`bootstrap: ${errMsg(err)}`);
-      return { code: 1 };
-    }
-  }
-
-  const outPath = opts.outPath ?? input.replace(/\.[^./\\]+$/, "") + ".regen2000proj";
-  if (!refuseOverwrite(outPath, opts.force, "bootstrap")) {
-    return { code: 1 };
-  }
-  let projectJson: string;
-  try {
-    projectJson = synthesizeProject(body, { origin });
-  } catch (err) {
-    console.error(`bootstrap: ${errMsg(err)}`);
-    return { code: 1 };
-  }
-  try {
-    writeFileSync(outPath, projectJson);
-  } catch (err) {
-    // WR-09 (D-11.1-04): an ENOENT (missing parent directory), EACCES or
-    // ENOSPC here is an ordinary, expected failure -- refuseOverwrite()
-    // above only handles the exists-case; this is the everything-else case,
-    // and it must not throw past this function's own never-throw contract.
-    console.error(`bootstrap: could not write ${outPath}: ${errMsg(err)}`);
-    return { code: 1 };
-  }
-  console.log(`bootstrap: wrote ${outPath} (origin $${origin.toString(16).padStart(4, "0")})`);
-  return { code: 0, path: outPath };
-}
-
-function cmdBootstrap(rest: string[]): number {
-  const { positional, entry, out, force, entryMissingValue, outMissingValue } = parseArgs(rest);
-  // WR-08: refused before any file is touched -- a flag-shaped or missing
-  // value for either option must never reach bootstrapProject() as if it
-  // were a real value.
-  if (entryMissingValue) {
-    console.error("bootstrap: --entry requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-  if (outMissingValue) {
-    console.error("bootstrap: --out requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-  const input = positional[0];
-  if (!input) {
-    console.error("bootstrap: usage: bootstrap <input> [--entry NAME] [--out PROJECT] [--force]");
-    return 1;
-  }
-  return bootstrapProject(input, { entry, outPath: out, force }).code;
-}
-
-function cmdExportAsm(rest: string[]): number {
-  const { positional, entry, out, force, entryMissingValue, outMissingValue } = parseArgs(rest);
-  // WR-08, same posture as cmdBootstrap() above: refuse before any temp
-  // directory or file is created.
-  if (entryMissingValue) {
-    console.error("export-asm: --entry requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-  if (outMissingValue) {
-    console.error("export-asm: --out requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-  const input = positional[0];
-  if (!input) {
-    console.error("export-asm: usage: export-asm <input-or-project> [--out FILE] [--force]");
-    return 1;
-  }
-  if (!existsSync(input)) {
-    console.error(`export-asm: input file not found: ${input}`);
-    return 1;
-  }
-
-  const ext = extname(input).toLowerCase();
-  let projectPath: string;
-  let tmpDir: string | undefined;
-
-  try {
-    if (ext === ".regen2000proj") {
-      projectPath = input;
-    } else {
-      // Bootstrap to a temp project first, so a bare .prg (or .d64/.raw)
-      // becomes ACME source in one command with no human interaction.
-      tmpDir = mkdtempSync(join(tmpdir(), "r2000-cli-"));
-      const tmpProjectPath = join(tmpDir, "bootstrap.regen2000proj");
-      const outcome = bootstrapProject(input, { entry, outPath: tmpProjectPath });
-      if (outcome.code !== 0) return outcome.code;
-      projectPath = outcome.path!;
-    }
-
-    const outPath = out ?? input.replace(/\.[^./\\]+$/, "") + ".a";
-    if (
-      !refuseOverwrite(
-        outPath,
-        force,
-        "export-asm",
-        " with generated source -- acme-build's own convention pairs <stem>.a with <stem>.prg, so " +
-          "the default target is very often hand-written source",
-      )
-    ) {
-      return 1;
-    }
-    const argv = buildExportAsmArgs({ projectPath, outPath });
-    const result = runR2000(argv);
-    if (result.status !== 0) {
-      console.error(`export-asm: regenerator2000 exited ${result.status}`);
-      if (result.stderr) console.error(result.stderr);
-      return result.status ?? 1;
-    }
-    console.log(`export-asm: wrote ${outPath}`);
-    return 0;
-  } finally {
-    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
-  }
-}
-
-/**
- * `verify <input-or-project>` -- the criterion-4 (R2000-06) reassembly
- * proof. Accepts a `.regen2000proj` directly, or bootstraps a bare input to
- * a temporary project first, exactly like `cmdExportAsm()` above. Prints
- * every parsed assembler result line, then the verdict's own reason. The
- * exit code comes from `verifyProject()`'s `ok` field -- which
- * `r2000-verify.ts`'s `acmeVerdict()` derives ONLY from the parsed ACME
- * result line, never from regenerator2000's own process exit code (D-10).
- * A skipped ACME therefore prints and exits as a failure here, reading as
- * exactly that -- never as a silent absence -- even though the underlying
- * `--verify` process may itself have exited 0 with a summary line claiming
- * success (r2000-verify.test.ts's pinned trap transcript is the live
- * incident this guards against).
- */
-function cmdVerify(rest: string[]): number {
-  const { positional, entry, entryMissingValue } = parseArgs(rest);
-  // WR-08: `--out` is not in verify's own accepted set (VERB_OPTIONS above),
-  // so `checkAcceptedOptions()` already refuses it before this function ever
-  // runs -- only `--entry`'s missing-value case is reachable here.
-  if (entryMissingValue) {
-    console.error("verify: --entry requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-  const input = positional[0];
-  if (!input) {
-    console.error("verify: usage: verify <input-or-project> [--entry NAME]");
-    return 1;
-  }
-  if (!existsSync(input)) {
-    console.error(`verify: input file not found: ${input}`);
-    return 1;
-  }
-
-  const ext = extname(input).toLowerCase();
-  let projectPath: string;
-  let tmpDir: string | undefined;
-
-  try {
-    if (ext === ".regen2000proj") {
-      projectPath = input;
-    } else {
-      // Bootstrap to a temp project first, so a bare .prg (or .d64/.raw)
-      // can be verified in one command with no human interaction.
-      tmpDir = mkdtempSync(join(tmpdir(), "r2000-cli-"));
-      const tmpProjectPath = join(tmpDir, "bootstrap.regen2000proj");
-      const outcome = bootstrapProject(input, { entry, outPath: tmpProjectPath });
-      if (outcome.code !== 0) return outcome.code;
-      projectPath = outcome.path!;
-    }
-
-    const result = verifyProject(projectPath);
-    for (const line of result.lines) {
-      const glyph = line.outcome === "ok" ? "✓" : "✗";
-      console.log(`  ${glyph} ${line.assembler} — ${line.detail}`);
-    }
-
-    if (!result.ok) {
-      // Print the reason verbatim -- especially a "skipped" reason, which
-      // must read as a failure and not as an absence (D-10).
-      console.error(`verify: ${result.reason}`);
-      return 1;
-    }
-    console.log(`verify: ${result.reason}`);
-    return 0;
-  } finally {
-    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
-  }
-}
-
-interface GenEnumsParsedArgs {
-  positional: string[];
-  maxResults?: number;
-  maxResultsRaw?: string;
-  unknownOption?: string;
-}
-
-/** Fixed, closed option set for gen-enums -- exactly `--max-results`. Per
- * WR-08's posture (do not silently accept a flag a verb does not
- * implement), any OTHER `--flag`-shaped token is recorded as `unknownOption`
- * and refused by the caller, rather than silently treated as a positional
- * argument the way the other verbs' `parseArgs()` does. */
-function parseGenEnumsArgs(rest: string[]): GenEnumsParsedArgs {
-  const positional: string[] = [];
-  let maxResults: number | undefined;
-  let maxResultsRaw: string | undefined;
-  let unknownOption: string | undefined;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i]!;
-    if (a === "--max-results") {
-      maxResultsRaw = rest[++i];
-      maxResults = maxResultsRaw !== undefined ? Number.parseInt(maxResultsRaw, 10) : Number.NaN;
-    } else if (a.startsWith("--")) {
-      unknownOption ??= a;
-    } else {
-      positional.push(a);
-    }
-  }
-  return { positional, maxResults, maxResultsRaw, unknownOption };
-}
-
-/**
- * `gen-enums <project> [--max-results N]` -- D-20/D-22/D-23's whole pass,
- * driven through `generateEnums()` (`r2000-enum-gen.ts`, Task 2). Prints the
- * coverage report's own summary lines (total/paired/unpaired counts, one
- * line per created/updated enum) and returns non-zero when: an unknown
- * option was given (WR-08); no project path was given; the project file
- * does not exist; `--max-results` did not parse as a positive integer;
- * either search pass returned exactly its own ceiling (a possible-
- * truncation signal, D-23's "no silent caps" applied at the CLI's own exit
- * code); or `generateEnums()` itself threw (an illegal generated
- * identifier, or an enum install/apply call that failed outright).
- */
-async function cmdGenEnums(rest: string[]): Promise<number> {
-  const { positional, maxResults, maxResultsRaw, unknownOption } = parseGenEnumsArgs(rest);
-  if (unknownOption) {
-    console.error(`gen-enums: unknown option "${unknownOption}"\n`);
-    console.log(USAGE);
-    return 1;
-  }
-
-  const project = positional[0];
-  if (!project) {
-    console.error("gen-enums: usage: gen-enums <project> [--max-results N]");
-    return 1;
-  }
-  if (!existsSync(project)) {
-    console.error(`gen-enums: input file not found: ${project}`);
-    return 1;
-  }
-  if (maxResults !== undefined && (!Number.isInteger(maxResults) || maxResults <= 0)) {
-    console.error(`gen-enums: --max-results must be a positive integer, got "${maxResultsRaw}"`);
-    return 1;
-  }
-
-  let report: Awaited<ReturnType<typeof generateEnums>>;
-  try {
-    report = maxResults !== undefined ? await generateEnums({ projectPath: project, maxResults }) : await generateEnums({ projectPath: project });
-  } catch (err) {
-    console.error(`gen-enums: ${errMsg(err)}`);
-    return 1;
-  }
-
-  for (const line of report.summaryLines) {
-    console.log(`  ${line}`);
-  }
-
-  if (report.pass1Truncated || report.pass2Truncated) {
-    console.error(
-      "gen-enums: a search pass returned exactly its own max_results ceiling -- coverage may be incomplete; " +
-        "re-run with a higher --max-results",
-    );
-    return 1;
-  }
-
-  console.log(`gen-enums: ${report.enums.length} enum(s) created/updated`);
-  return 0;
-}
-
-interface ExportLblParsedArgs {
-  positional: string[];
-  out?: string;
-  outMissingValue?: boolean;
-  unknownOption?: string;
-}
-
-/** Fixed, closed option set for export-lbl -- exactly `--out`. Per WR-08's
- * posture (do not silently accept a flag a verb does not implement, or a
- * flag missing its value), any OTHER `--flag`-shaped token is refused as
- * `unknownOption`, and `--out` with no value (or a flag-shaped "value") is
- * refused as `outMissingValue`, rather than silently treated the way
- * bootstrap/export-asm's own looser `parseArgs()` does. */
-function parseExportLblArgs(rest: string[]): ExportLblParsedArgs {
-  const positional: string[] = [];
-  let out: string | undefined;
-  let outMissingValue = false;
-  let unknownOption: string | undefined;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i]!;
-    if (a === "--out") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("--")) {
-        outMissingValue = true;
-      } else {
-        out = value;
-        i++;
-      }
-    } else if (a.startsWith("--")) {
-      unknownOption ??= a;
-    } else {
-      positional.push(a);
-    }
-  }
-  return { positional, out, outMissingValue, unknownOption };
-}
-
-interface ImportLblParsedArgs {
-  positional: string[];
-  unknownOption?: string;
-}
-
-/** import-lbl takes no options at all besides its two positional arguments
- * -- any `--flag`-shaped token is refused as `unknownOption` (WR-08
- * posture), never silently treated as a positional. */
-function parseImportLblArgs(rest: string[]): ImportLblParsedArgs {
-  const positional: string[] = [];
-  let unknownOption: string | undefined;
-  for (const a of rest) {
-    if (a.startsWith("--")) unknownOption ??= a;
-    else positional.push(a);
-  }
-  return { positional, unknownOption };
-}
-
-/**
- * `export-lbl <project> [--out FILE]` -- the R2000-14 export leg, via
- * `r2000-symbols.ts`'s `exportLabels()`. Prints the written path and the
- * symbol count parsed back from the file (never the raw regenerator2000
- * exit code alone -- `exportLabels()` itself already re-reads and validates
- * the file through stock-symbols.ts's parser before returning).
- */
-async function cmdExportLbl(rest: string[]): Promise<number> {
-  const { positional, out, outMissingValue, unknownOption } = parseExportLblArgs(rest);
-  if (unknownOption) {
-    console.error(`export-lbl: unknown option "${unknownOption}"\n`);
-    console.log(USAGE);
-    return 1;
-  }
-  if (outMissingValue) {
-    console.error("export-lbl: --out requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-
-  const project = positional[0];
-  if (!project) {
-    console.error("export-lbl: usage: export-lbl <project> [--out FILE]");
-    return 1;
-  }
-  if (!existsSync(project)) {
-    console.error(`export-lbl: project file not found: ${project}`);
-    return 1;
-  }
-
-  const outPath = out ?? project.replace(/\.[^./\\]+$/, "") + ".lbl";
-  let result: Awaited<ReturnType<typeof exportLabels>>;
-  try {
-    result = await exportLabels({ projectPath: project, outPath });
-  } catch (err) {
-    console.error(`export-lbl: ${errMsg(err)}`);
-    return 1;
-  }
-
-  console.log(`export-lbl: wrote ${outPath} (${result.symbolCount} symbol(s))`);
-  return 0;
-}
-
-/**
- * `import-lbl <project> <lbl>` -- the R2000-15/D-28 import leg, via
- * `r2000-symbols.ts`'s `importLabels()`. Prints the names imported, then an
- * explicit line naming that persistence was proven by an independent disk
- * re-read (never left implicit, so the transcript itself shows the D-28
- * trap was avoided). Exits non-zero -- naming the reason, which includes
- * stock-symbols.ts's own ceiling messages verbatim when the given `.lbl`
- * fails them -- whenever the result is not disk-verified.
- */
-async function cmdImportLbl(rest: string[]): Promise<number> {
-  const { positional, unknownOption } = parseImportLblArgs(rest);
-  if (unknownOption) {
-    console.error(`import-lbl: unknown option "${unknownOption}"\n`);
-    console.log(USAGE);
-    return 1;
-  }
-
-  const [project, lbl] = positional;
-  if (!project || !lbl) {
-    console.error("import-lbl: usage: import-lbl <project> <lbl>");
-    return 1;
-  }
-  if (!existsSync(project)) {
-    console.error(`import-lbl: project file not found: ${project}`);
-    return 1;
-  }
-  if (!existsSync(lbl)) {
-    console.error(`import-lbl: label file not found: ${lbl}`);
-    return 1;
-  }
-
-  let result: Awaited<ReturnType<typeof importLabels>>;
-  try {
-    result = await importLabels({ projectPath: project, lblPath: lbl });
-  } catch (err) {
-    console.error(`import-lbl: ${errMsg(err)}`);
-    return 1;
-  }
-
-  console.log(`import-lbl: imported ${result.importedNames.length} name(s): ${result.importedNames.join(", ")}`);
-  if (!result.diskVerified) {
-    console.error(`import-lbl: ${result.reason}`);
-    return 1;
-  }
-  console.log(
-    "import-lbl: persisted by an explicit r2000_save_project call over the same --mcp-server-stdio session " +
-      "(D-28) -- verified by re-reading the project from disk in a fresh process, not merely trusted from the " +
-      "child's own success text.",
-  );
-  return 0;
-}
-
-interface RenderMemmapParsedArgs {
-  positional: string[];
-  provenance?: string;
-  provenanceMissingValue?: boolean;
-  out?: string;
-  outMissingValue?: boolean;
-  check?: boolean;
-  unknownOption?: string;
-}
-
-/** Fixed, closed option set for render-memmap -- exactly `--provenance`,
- * `--out` and `--check`. Per WR-08's posture (do not silently accept a flag
- * a verb does not implement, or a flag missing its value), any OTHER
- * `--flag`-shaped token is refused as `unknownOption`, and `--provenance`/
- * `--out` with no value (or a flag-shaped "value") is refused via their own
- * `*MissingValue` fields. */
-function parseRenderMemmapArgs(rest: string[]): RenderMemmapParsedArgs {
-  const positional: string[] = [];
-  let provenance: string | undefined;
-  let provenanceMissingValue = false;
-  let out: string | undefined;
-  let outMissingValue = false;
-  let check = false;
-  let unknownOption: string | undefined;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i]!;
-    if (a === "--provenance") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("--")) {
-        provenanceMissingValue = true;
-      } else {
-        provenance = value;
-        i++;
-      }
-    } else if (a === "--out") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("--")) {
-        outMissingValue = true;
-      } else {
-        out = value;
-        i++;
-      }
-    } else if (a === "--check") {
-      check = true;
-    } else if (a.startsWith("--")) {
-      unknownOption ??= a;
-    } else {
-      positional.push(a);
-    }
-  }
-  return { positional, provenance, provenanceMissingValue, out, outMissingValue, check, unknownOption };
-}
-
-/**
- * `render-memmap <project> --provenance FILE [--out FILE] [--check]` --
- * D-24's generated-view verb, via `r2000-memmap-render.ts`'s
- * `renderMemoryMap()`/`checkRenderedMemoryMap()`. Never writes a file when
- * `--check` is given -- that mode only reads and reports.
- */
-async function cmdRenderMemmap(rest: string[]): Promise<number> {
-  const {
-    positional,
-    provenance,
-    provenanceMissingValue,
-    out,
-    outMissingValue,
-    check,
-    unknownOption,
-  } = parseRenderMemmapArgs(rest);
-
-  if (unknownOption) {
-    console.error(`render-memmap: unknown option "${unknownOption}"\n`);
-    console.log(USAGE);
-    return 1;
-  }
-  if (provenanceMissingValue) {
-    console.error("render-memmap: --provenance requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-  if (outMissingValue) {
-    console.error("render-memmap: --out requires a value\n");
-    console.log(USAGE);
-    return 1;
-  }
-
-  const project = positional[0];
-  if (!project) {
-    console.error("render-memmap: usage: render-memmap <project> --provenance FILE [--out FILE] [--check]");
-    return 1;
-  }
-  if (!existsSync(project)) {
-    console.error(`render-memmap: project file not found: ${project}`);
-    return 1;
-  }
-  if (!provenance) {
-    console.error("render-memmap: --provenance FILE is required\n");
-    console.log(USAGE);
-    return 1;
-  }
-  if (!existsSync(provenance)) {
-    console.error(`render-memmap: provenance sidecar not found: ${provenance}`);
-    return 1;
-  }
-
-  const outPath = out ?? join(dirname(project), "memory-map.md");
-
-  if (check) {
-    let result: Awaited<ReturnType<typeof checkRenderedMemoryMap>>;
-    try {
-      result = await checkRenderedMemoryMap({ projectPath: project, provenancePath: provenance, renderedPath: outPath });
-    } catch (err) {
-      console.error(`render-memmap: ${errMsg(err)}`);
-      return 1;
-    }
-    if (result.status === "in-sync") {
-      console.log(`render-memmap: in sync (${outPath})`);
-      return 0;
-    }
-    if (result.status === "missing") {
-      console.error(`render-memmap: missing -- ${outPath} does not exist yet. Run render-memmap without --check first.`);
-      return 1;
-    }
-    console.error(`render-memmap: drifted at line ${result.line}`);
-    console.error(`  expected: ${result.expected}`);
-    console.error(`  actual:   ${result.actual}`);
-    return 1;
-  }
-
-  let rendered: Awaited<ReturnType<typeof renderMemoryMap>>;
-  try {
-    rendered = await renderMemoryMap({ projectPath: project, provenancePath: provenance });
-  } catch (err) {
-    console.error(`render-memmap: ${errMsg(err)}`);
-    return 1;
-  }
-  try {
-    writeFileSync(outPath, rendered.markdown);
-  } catch (err) {
-    // WR-09 (D-11.1-04): the same shape as bootstrapProject()'s write above,
-    // one verb over -- an ordinary write failure (missing parent directory,
-    // permissions, full disk) must not throw past this verb's own
-    // never-throw contract.
-    console.error(`render-memmap: could not write ${outPath}: ${errMsg(err)}`);
-    return 1;
-  }
-  console.log(
-    `render-memmap: wrote ${outPath} (${rendered.rowCount} row(s), ${rendered.unknownCount} [unknown], digest ${rendered.renderDigest})`,
-  );
-  return 0;
-}
-
-/**
- * Entry point for the `r2000` subcommand. Returns an exit code; never calls
- * exit the process directly (the bin does that). Handles `--help`/no verb/unknown
- * verb per `acme.mjs`'s own dispatch convention (`.claude/skills/acme-build/
- * scripts/acme.mjs`), with one deliberate difference: an explicit `--help`
- * returns 0 (a no-op invocation with no verb also returns 0), while an
- * unrecognised verb returns 1.
- */
-export async function runR2000Cli(argv: string[]): Promise<number> {
-  const [verb, ...rest] = argv;
-
-  if (!verb || verb === "--help" || verb === "-h") {
-    console.log(USAGE);
-    return 0;
-  }
-
-  // IN-06 (D-11.1-04): the single call site for the shared verb-options
-  // check, run BEFORE dispatch so a refused option never reaches any cmd*
-  // function -- one place enforces the closed option set for every verb,
-  // rather than seven places each doing (or, as `verify` proved, NOT doing)
-  // it themselves.
-  const optionError = checkAcceptedOptions(verb, rest);
-  if (optionError) {
-    console.error(optionError);
-    console.log(USAGE);
-    return 1;
-  }
-
-  try {
-    switch (verb) {
-      case "bootstrap":
-        return cmdBootstrap(rest);
-      case "export-asm":
-        return cmdExportAsm(rest);
-      case "verify":
-        return cmdVerify(rest);
-      case "gen-enums":
-        return await cmdGenEnums(rest);
-      case "export-lbl":
-        return await cmdExportLbl(rest);
-      case "import-lbl":
-        return await cmdImportLbl(rest);
-      case "render-memmap":
-        return await cmdRenderMemmap(rest);
-      default:
-        console.error(`r2000: unknown verb "${verb}"\n`);
-        console.log(USAGE);
-        return 1;
-    }
-  } catch (err) {
-    // An R2000ViceFlagError from the seam (or any other unexpected throw)
-    // must be re-thrown or reported verbatim, never swallowed -- the loud
-    // failure is the point (D-07). This is a last-resort net: every expected
-    // failure path above already returns its own code with its own message.
-    if (err instanceof R2000ViceFlagError) {
-      console.error(err.message);
-      return 1;
-    }
-    console.error(`r2000: ${errMsg(err)}`);
-    return 1;
-  }
-}