@henols/vice-mcp 0.2.0 → 0.2.1

package/r2000-verify.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// r2000-verify.ts -- the ONE place that interprets regenerator2000's
+// `--verify` output.
+//
+// WHY PARSING IS REQUIRED AT ALL (D-10, the concrete incident): with ACME
+// absent from PATH and ca65 present, a real `regenerator2000 0.9.20 --verify`
+// run on this host printed
+//
+//   ✗ ACME — ACME not found in PATH (skipped)
+//   ✓ All roundtrip verifications passed.
+//   EXIT=0
+//
+// -- exit 0, and a summary line that reads as a full pass, while the one
+// assembler this project actually cares about (`!cpu 6510`, ACME 0.97) never
+// ran at all. Trusting the exit code here would let ACME be silently
+// skipped and still report success. This is the WHAT-NOT-TO-DO for any
+// future edit to this file: never derive `ok` from `status`, ever, no
+// matter how tempting a bare zero-exit-status check looks. The verdict this
+// module produces comes ONLY from parsing the per-assembler result lines
+// and reading ACME's own line -- never from the process exit code, and
+// never from the aggregate "All roundtrip verifications passed." summary
+// line, which is itself the thing that lied in the transcript above.
+//
+// Both captured transcripts (the honest pass and this exact false-pass trap)
+// are pinned verbatim as fixtures in r2000-verify.test.ts, so a future
+// "simplification" back to an exit-code check fails a unit test immediately.
+//
+// WR-04 (10-REVIEW.md, fixed in plan 11-01): the verdict must also never
+// trust just the FIRST ACME result line. `acmeVerdict()` used to select
+// ACME's line with a bare array .find() over the first matching entry, so
+// a transcript containing both a
+// passing and a failing ACME line (a shape --verify has never printed as of
+// 0.9.20, but one this defensive parser is explicitly meant to survive)
+// reported `ok: true` from the first (passing) line while discarding the
+// later failure -- exactly the "misleading success" this module exists to
+// refuse. The fix requires UNANIMITY: every parsed ACME line must be `ok`,
+// the first non-ok line (if any) drives the verdict, and if more than one
+// ACME line is present after passing that check, the module refuses to
+// guess which one is authoritative rather than picking one arbitrarily.
+// Both the mixed-transcript case and the too-many-ACME-lines case are pinned
+// verbatim as fixtures in r2000-verify.test.ts.
+//
+// Import nothing from `hostpath.ts`/`containerpath.ts` -- plan 10-01's
+// absence assertion in `hostpath-consumers.test.ts` already names this file.
+
+import { buildVerifyArgs, runR2000 } from "./r2000-launch.ts";
+
+/** The three possible outcomes for a single per-assembler `--verify` result
+ * line. `"skipped"` and `"ok"` are DIFFERENT outcomes and must never be
+ * conflated -- a skipped assembler did not run, so it proves nothing, while
+ * an `ok` assembler was actually invoked and its output byte-diffed. */
+export type AssemblerOutcome = "ok" | "skipped" | "failed";
+
+export interface VerifyLine {
+  assembler: string;
+  outcome: AssemblerOutcome;
+  detail: string;
+}
+
+// Matches exactly a per-assembler result line, e.g.:
+//   ✓ ACME — byte-identical (44 bytes)
+//   ✗ 64tass — 64tass not found in PATH (skipped)
+// Tolerates an em-dash (U+2014), en-dash (U+2013) or plain hyphen as the
+// separator, since only the ACME verdict is load-bearing here and the exact
+// glyph regenerator2000 prints is an upstream formatting detail, not
+// something this parser should be brittle against. Deliberately does NOT
+// match the aggregate "✓ All roundtrip verifications passed." summary line
+// (no separator token present there) or the "EXIT=N" line some transcripts
+// carry -- both are excluded from the returned array by construction, not
+// by a special-cased skip: they simply never match this shape.
+const VERIFY_LINE_PATTERN = /^[✓✗]\s+(.+?)\s+[—–-]\s+(.+)$/;
+
+/**
+ * Parses `regenerator2000 --verify`'s stdout into one `VerifyLine` per
+ * per-assembler result line. The aggregate `✓ All roundtrip verifications
+ * passed.` line is a summary, not an assembler line -- it never matches
+ * `VERIFY_LINE_PATTERN` (no `—`/`-` separator), so it is excluded from the
+ * result by construction rather than filtered out after the fact.
+ */
+export function parseVerifyOutput(stdout: string): VerifyLine[] {
+  const lines: VerifyLine[] = [];
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(VERIFY_LINE_PATTERN);
+    if (!match) continue;
+    const [, assemblerRaw, detailRaw] = match;
+    const assembler = assemblerRaw!.trim();
+    const detail = detailRaw!.trim();
+    // A "(skipped)" suffix always means skipped, regardless of the leading
+    // glyph. Anything else takes its outcome from the leading glyph: a
+    // leading ✓ is "ok", any other non-skipped result line is "failed" --
+    // this project has never observed a real ACME/ca65 failure transcript,
+    // but a future one must not silently parse as "ok".
+    const outcome: AssemblerOutcome = /\(skipped\)\s*$/i.test(detail)
+      ? "skipped"
+      : trimmed.startsWith("✓")
+        ? "ok"
+        : "failed";
+    lines.push({ assembler, outcome, detail });
+  }
+  return lines;
+}
+
+/**
+ * Derives the ACME-specific verdict from a parsed line set. `ok` only when
+ * at least one ACME line exists, EVERY parsed ACME line has outcome `"ok"`
+ * (unanimity -- WR-04), AND exactly one ACME line is present. A missing
+ * ACME line, any ACME line with outcome `"skipped"` or `"failed"`, and more
+ * than one `"ok"` ACME line each return `ok: false` with a distinct,
+ * quotable reason -- never conflate "skipped" with "passed", never let a
+ * passing line hide a later failing one, and never fall back to the summary
+ * line (which this module never even parses as a VerifyLine, see
+ * `parseVerifyOutput`).
+ */
+export function acmeVerdict(lines: VerifyLine[]): { ok: boolean; reason: string } {
+  const acmeLines = lines.filter((l) => l.assembler.toLowerCase() === "acme");
+
+  if (acmeLines.length === 0) {
+    return {
+      ok: false,
+      reason:
+        "no ACME line found in --verify output -- ACME was never invoked at all, which is a failure, " +
+        "not an absence of evidence",
+    };
+  }
+
+  // First non-ok line wins -- so a passing ACME line earlier in the
+  // transcript can never hide a failing one later in it (WR-04).
+  const bad = acmeLines.find((l) => l.outcome !== "ok");
+
+  if (bad?.outcome === "skipped") {
+    return {
+      ok: false,
+      reason:
+        `ACME was skipped, not run -- "${bad.detail}". A skipped ACME is a failure, never a pass ` +
+        `(D-10): --verify can print "✓ All roundtrip verifications passed." and exit 0 even when ` +
+        `ACME never ran at all -- exactly the false pass observed live on this host with ACME absent ` +
+        `and ca65 present.`,
+    };
+  }
+
+  if (bad?.outcome === "failed") {
+    return { ok: false, reason: `ACME reported a failure: "${bad.detail}"` };
+  }
+
+  // Every ACME line is ok at this point. Still refuse to guess which one is
+  // authoritative if more than one was printed (WR-04) -- unanimous is not
+  // the same as unambiguous.
+  if (acmeLines.length > 1) {
+    return {
+      ok: false,
+      reason: `--verify printed ${acmeLines.length} ACME result lines -- refusing to guess which one is the verdict`,
+    };
+  }
+
+  return { ok: true, reason: `ACME reported: ${acmeLines[0]!.detail}` };
+}
+
+export interface VerifyProjectResult {
+  ok: boolean;
+  reason: string;
+  lines: VerifyLine[];
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Runs `regenerator2000 --verify` against `projectPath` (via
+ * `buildVerifyArgs()`/`runR2000()`, so the `--vice` scan applies here too),
+ * parses stdout, and derives `ok` from `acmeVerdict()` -- deliberately NOT
+ * from `status`. Returns the raw status and streams so a caller can print
+ * them for diagnostics, but no code path in this function ever lets a zero
+ * exit status alone make `ok` true. A warning on stderr is never treated as
+ * a failure -- only the parsed ACME result line decides the verdict.
+ */
+export function verifyProject(projectPath: string): VerifyProjectResult {
+  const argv = buildVerifyArgs({ projectPath });
+  const { status, stdout, stderr } = runR2000(argv);
+  const lines = parseVerifyOutput(stdout);
+  const verdict = acmeVerdict(lines);
+  return { ok: verdict.ok, reason: verdict.reason, lines, status, stdout, stderr };
+}

package/stock-symbols.ts

@@ -26,11 +26,17 @@
 // The confirmed input format is a VICE label file, one `al C:xxxx .Name`
 // line per symbol, verified against ACME's `--vicelabels` output via
 // acme-build/scripts/acme.mjs's own parser (curateLabels(),
-// `/^al\s+C:[0-9a-f]+\s+\.(\S+)/i`). STATED ASSUMPTION, NOT A VERIFIED FACT:
-// regenerator2000's `--export_lbl` is *expected* to emit the same syntax,
-// but R2000-16(c) has never been run -- hence the parser below SKIPS
-// unrecognised lines rather than refusing the whole file, and no comment or
-// doc here may claim "regenerator2000-compatible" as verified.
+// `/^al\s+C:[0-9a-f]+\s+\.(\S+)/i`). VERIFIED (Phase 9, R2000-16(c)):
+// regenerator2000 0.9.20's `--export_lbl` was run against the
+// probe-illegal.prg-derived fixture and emitted `al C:0810 .init_screen`,
+// which matches this module's own VICE_LABEL_LINE_RE
+// (`/^al\s+C:([0-9a-fA-F]{1,4})\s+\.(\S+)/`) exactly. This claim is SCOPED to
+// regenerator2000 0.9.20 and that fixture -- not to all inputs forever (the
+// same scoping caveat ROADMAP.md applies to Phase 9's criterion 3(3) `pass`).
+// The parser below still SKIPS unrecognised lines rather than refusing the
+// whole file: a future regenerator2000 version, a hand-edited label file, or
+// a different exporter entirely can still produce lines this format should
+// tolerate rather than reject outright.
 //
 // WHAT NOT TO DO:
 //   - Never add a second resolver holder or call setSymbolResolver() from
@@ -75,8 +81,12 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 const VICE_LABEL_LINE_RE = /^al\s+C:([0-9a-fA-F]{1,4})\s+\.(\S+)/;
 
 /** T-05-02-03: three independent resource ceilings, each refusing with both
- * the observed value and the limit named. */
-const MAX_LABEL_FILE_BYTES = 2 * 1024 * 1024;
+ * the observed value and the limit named. `MAX_LABEL_FILE_BYTES` is exported
+ * (11-08, Rule A20) so `r2000-symbols.ts`'s `exportLabels()`/`importLabels()`
+ * can apply the SAME byte ceiling to a regenerator2000-produced/-consumed
+ * `.lbl` file before ever calling `parseViceLabelFile()` below -- never a
+ * second hand-copied number. */
+export const MAX_LABEL_FILE_BYTES = 2 * 1024 * 1024;
 const MAX_LABEL_FILE_LINES = 50000;
 const MAX_SYMBOLS = 20000;
 
@@ -98,7 +108,11 @@ export class StockSymbolsError extends ViceError {
   }
 }
 
-interface SymbolTable {
+/** Exported alongside `parseViceLabelFile()` (11-08, Rule A20) purely so a
+ * cross-module caller can name this shape in its own type annotations --
+ * this module's own internal state (`loadedTable` below) still never leaves
+ * this file. */
+export interface SymbolTable {
   byName: Map<string, number>;
   byAddress: Map<number, string>;
 }
@@ -186,7 +200,17 @@ function resolveLabelFilePath(pathArg: unknown): string {
 // counted, never a whole-file refusal.
 // ---------------------------------------------------------------------------
 
-function parseViceLabelFile(text: string): {
+/**
+ * Exported (11-08, Rule A20) so `r2000-symbols.ts` can validate a
+ * regenerator2000-produced `.lbl` file (or check a caller-supplied one
+ * BEFORE it is ever handed to a spawned regenerator2000 child) through THIS
+ * parser -- the ONE `al C:xxxx .Name` reader in this repo -- rather than
+ * adding a second copy of `VICE_LABEL_LINE_RE`. Ceiling violations
+ * (`MAX_LABEL_FILE_LINES`/`MAX_SYMBOLS`) throw `StockSymbolsError` exactly as
+ * they do for `handleSymbolsLoad` below; a caller across the module boundary
+ * is expected to surface that error verbatim, never re-wrap it.
+ */
+export function parseViceLabelFile(text: string): {
   table: SymbolTable;
   symbolCount: number;
   skippedLines: number;

package/vice-proxy.ts

@@ -185,6 +185,126 @@ import * as stockDispatch from "./stock-dispatch.ts";
 // below, strictly after the DENY_LIST check -- see the comment at that call
 // site for why the ordering is load-bearing.
 import { capabilityRefusalMessage } from "./capability-registry.ts";
+// Plan 11-05: the curated r2000_* tool surface's DEFINITIONS, imported
+// STATICALLY -- registration below happens synchronously at module scope, so
+// a dynamic import cannot serve it. This costs no child process and no
+// socket: the heavy part (the MCP client, the spawned regenerator2000 child)
+// stays behind r2000-tools.ts's own `await import("./r2000-mcp-client.ts")`
+// inside runR2000Tool() itself, reached only when a tool is actually called.
+import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
+
+// ------------------------------------------------------------ r2000 subcommand
+//
+// D-06 / RESEARCH.md Open Question #1 (plan 10-04): `vice-mcp r2000 <verb>` 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 (`--vendor` only pre-resolves the package; it never
+// places `.claude/mcp/vice/*.ts` as plain files inside a consuming project),
+// so any design resolving a filesystem path to the seam would silently fail
+// to resolve for npm-installed users. This bin is the one surface proven to
+// work in all three routes.
+//
+// This branch runs as the first executable statement of the module body,
+// deliberately ABOVE `ACTIVE_BACKEND`'s backend probe (which shells out to a
+// binary's `--help`), above the manifest read, and above
+// `new MCPServer(...)`/`server.startStdio()` far below -- a CLI invocation
+// must never open a socket, never probe a binary, and never write a byte of
+// JSON-RPC to stdout. WHAT NOT TO DO: never let this branch fall through
+// into the server path, and never print anything on stdout on the server
+// path that a CLI caller could confuse for `r2000` output.
+//
+// Ending the process here is deliberate and is NOT a violation of this
+// file's standing "never end the process from a teardown handler" rule (see
+// that handler's own comment further down): that rule protects the
+// long-lived server's lease-release path, and this branch ends the process
+// before any lease, socket or handler exists. A dynamic import is used
+// (not a static one) so the CLI module is not part of the server's startup
+// cost on the normal, non-`r2000` path.
+//
+// IN-01 (10-REVIEW.md; 11.1-CONTEXT.md AUDIT-01, D-11.1-04): `console.log`/
+// `console.error` writes to `process.stdout`/`process.stderr` are
+// ASYNCHRONOUS on POSIX once the fd is a pipe (Node opens pipe/socket fds
+// non-blocking, unlike a TTY or a regular file), so a bare `process.exit()`
+// immediately after can discard whatever write has not yet drained --
+// measured at a 128 KiB truncation point on this host's Node for a single
+// write exceeding the OS pipe's capacity. The reachable trigger is
+// `cmdExportAsm`'s `console.error(result.stderr)` in r2000-cli.ts, which can
+// carry a large diagnostic from the spawned regenerator2000 child: the one
+// case where the user most needs the diagnostic is exactly the case a piped
+// invocation could silently lose it in. `drainStdio()` below explicitly
+// awaits both streams' own pending writes (a `write("", cb)`-style
+// zero-length write's callback fires only once every prior queued write has
+// actually flushed) before the terminating `process.exit(code)`.
+//
+// T-11.1-EXITHANG: the drain is BOUNDED to `R2000_CLI_DRAIN_TIMEOUT_MS`. An
+// exit that hangs forever waiting on a pipe nobody reads is worse than a
+// truncated diagnostic -- this project's standing rule is that a teardown
+// path never becomes a hang (see the "never end the process from a teardown
+// handler" comment above; a BOUNDED drain here does not violate that rule
+// for the same reason the original unbounded `process.exit()` did not: this
+// still runs before any lease, socket or handler exists, and now also can
+// never block indefinitely).
+const R2000_CLI_DRAIN_TIMEOUT_MS = 300;
+
+/** Resolves once `stream`'s own pending writes have flushed, or after
+ * `timeoutMs`, whichever comes first. A zero-length `write("", cb)`'s
+ * callback fires strictly after every write queued ahead of it on the same
+ * stream has completed -- so this is a genuine drain barrier, not a fixed
+ * sleep. Guarded so a stream that is not writable (already closed/ended,
+ * e.g. under `> /dev/null` teardown races) resolves immediately rather than
+ * calling `write()` on it. */
+function drainStdio(stream: NodeJS.WriteStream): Promise<void> {
+  return new Promise((resolve) => {
+    if (!stream.writable) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, R2000_CLI_DRAIN_TIMEOUT_MS);
+    stream.write("", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+if (process.argv[2] === "r2000") {
+  // A broken pipe (the reader closing early, e.g. `| head`) makes
+  // `stream.write()` fail with EPIPE. Awaiting `drainStdio()` below gives
+  // that failure the chance to actually surface as Node's stream 'error'
+  // event -- which throws UNCAUGHT and crashes the process if nothing is
+  // listening, converting what used to be a silent (bare `process.exit()`
+  // outran the async error) success into a stack-trace crash. This
+  // mirrors the SAME EPIPE class this file already guards against for the
+  // server path further down (see that handler's own
+  // modelcontextprotocol/typescript-sdk#1564 citation) -- registered here
+  // too because this branch exits long before reaching that one.
+  process.stdout.on("error", () => {});
+  process.stderr.on("error", () => {});
+
+  // Test-only escape hatch, never documented to end users and inert unless
+  // this exact env var is set: writes a deterministic filler payload
+  // through this SAME drained-exit path, so vice-proxy.test.ts can measure
+  // an exact byte count well above any OS pipe capacity without needing a
+  // real regenerator2000 project (empirically, neither `--help`'s ~5.6 KB
+  // USAGE text nor a synthesized/garbage `.regen2000proj` fed to
+  // export-asm's error path scales anywhere near 128 KiB on this host's
+  // regenerator2000 0.9.20 -- both were measured before this hatch was
+  // added; see 11.1-05-SUMMARY.md for the measurements). Never reachable
+  // from a real `r2000 <verb>` invocation: the check is against a specific,
+  // unambiguous env var name no real caller would ever set.
+  const testFillBytes = process.env.VICE_TEST_R2000_CLI_STDOUT_FILL_BYTES;
+  if (testFillBytes) {
+    process.stdout.write("x".repeat(Number(testFillBytes)));
+    await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
+    process.exit(0);
+  }
+
+  const { runR2000Cli } = await import("./r2000-cli.ts");
+  const code = await runR2000Cli(process.argv.slice(3));
+  await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
+  process.exit(code);
+}
 
 const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -3220,6 +3340,32 @@ tools[RESULT_CONTINUE_TOOL.name] = buildViceTool(RESULT_CONTINUE_TOOL, (args) =>
 // entry in `tools/list`.
 tools[RECYCLE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(RECYCLE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleRecycle(args));
 tools[DIAGNOSE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(DIAGNOSE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleDiagnose(args));
+// Backend-INDEPENDENT by construction (plan 11-05): the r2000_* family never
+// touches VICE at all -- regenerator2000 is a separate, static-analysis child
+// process, so there is no fork/stock distinction to make and
+// buildBackendAwareTool() would be flatly wrong here (there is nothing for it
+// to dispatch to on either backend). The family is in NEITHER
+// tools-manifest.json NOR tools-manifest.stock.json: both are regenerated by
+// refresh-manifest.ts from a live HOST VICE server's own tools/list, and an
+// r2000 child process is never that host -- a hand-added entry in either
+// manifest would be silently wiped on the next refresh. Registered here via
+// buildViceTool() directly (the SAME exception RESULT_CONTINUE_TOOL above
+// is), so no r2000_* runner can ever reach forwardToVice(), call(), or
+// ensureViceSession() -- CLAUDE.md's "derived tools must be intercepted
+// before forwardToVice()" constraint is satisfied by construction for this
+// family, not by an interception, because the runner is never wired to
+// forwardToVice() in the first place.
+// Deliberately NOT named `def` (the manifest loop's own loop variable,
+// above): `stock-dispatch.test.ts`'s `proxyToolRegistrations()` regex-scans
+// this file's own `tools[...] = ...;` lines and keys each one by its raw
+// captured text, so an identically-named loop variable here would make this
+// registration textually indistinguishable from the manifest loop's -- a
+// distinct name (`r2000Def`) keeps the r2000 family's own exemption from
+// `buildBackendAwareTool()` from ever being confused with, or accidentally
+// widened to cover, the manifest loop's registration.
+for (const r2000Def of R2000_TOOL_DEFINITIONS) {
+  tools[r2000Def.name] = buildViceTool(r2000Def, (args) => runR2000Tool(r2000Def.name, args));
+}
 
 const server = new MCPServer({ name: "vice", version: PROXY_VERSION, tools });
 await server.startStdio();