@henols/c64-re-tools 1.0.0 → 2.0.0-rc.2

package/src/script.ts

@@ -0,0 +1,59 @@
+// The one error envelope for the skill scripts and the CLI: a script prints one JSON line,
+// a refusal prints {"error":{code,message}} with exit status 1, and a usage error prints the
+// usage text as an invalid-input error with exit status 2.
+
+import { WireFailure } from "./protocol/messages.ts";
+import { elapsedMs, startTrace, trace, type TraceFields } from "./trace.ts";
+
+/** A wrong command line. The message names the problem; an empty message asks for the usage text alone. */
+export class UsageError extends Error {}
+
+/** A refusal class: an Error with a stable `code` (WireFailure, KnowledgeError, ...). */
+export type RefusalClass = abstract new (...args: never[]) => Error & { code: string };
+
+/** True for an error that node:util parseArgs throws for a wrong command line. */
+function isParseArgsError(error: unknown): error is Error {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  return error instanceof Error && typeof code === "string" && code.startsWith("ERR_PARSE_ARGS_");
+}
+
+function printLine(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+/**
+ * Runs a script body. Prints its result as one JSON line when it returns a value (undefined prints nothing).
+ * A refusal (WireFailure always, plus `refusals`) prints {"error":{code,message}} with exit status 1.
+ * A UsageError or a node:util parseArgs error (code ERR_PARSE_ARGS_*) prints {"error":{"code":"invalid-input",
+ * "message": message === "" ? usage : message + "\n\n" + usage}} with exit status 2. Anything else is rethrown.
+ * The body may set process.exitCode itself for an extra exit status; a value it returns is printed as usual.
+ */
+export async function runScript(body: () => unknown, options: { usage: string; refusals?: readonly RefusalClass[] }): Promise<void> {
+  // The trace of the script, when C64RT_TRACE is set; its start event carries the script and its arguments.
+  startTrace("script", { warn: (line) => process.stderr.write(`${line}\n`) });
+  const started = performance.now();
+  const end = (fields: TraceFields) => trace().event("script.end", { ms: elapsedMs(started), status: process.exitCode ?? 0, ...fields });
+  let result: unknown;
+  try {
+    result = await body();
+  } catch (error) {
+    if ([WireFailure, ...(options.refusals ?? [])].some((refusal) => error instanceof refusal)) {
+      const { code, message } = error as Error & { code: string };
+      printLine({ error: { code, message } });
+      process.exitCode = 1;
+      end({ error: { code, message } });
+      return;
+    }
+    if (error instanceof UsageError || isParseArgsError(error)) {
+      const { message } = error;
+      printLine({ error: { code: "invalid-input", message: message === "" ? options.usage : `${message}\n\n${options.usage}` } });
+      process.exitCode = 2;
+      end({ error: { code: "invalid-input", message } });
+      return;
+    }
+    end({ status: 1, error });
+    throw error;
+  }
+  if (result !== undefined) printLine(result);
+  end({ result });
+}

package/src/time.ts

@@ -0,0 +1,15 @@
+// Every date and time the code writes is ISO 8601 at the fixed CET offset
+// +01:00, also in summer: no timestamp repeats when the clocks go back, and
+// the text of two timestamps sorts in time order.
+
+const CET_OFFSET_MS = 60 * 60 * 1000;
+
+/** `time` as `2026-10-09T14:03:21.123+01:00`. */
+export function isoCet(time: Date = new Date()): string {
+  return `${new Date(time.getTime() + CET_OFFSET_MS).toISOString().slice(0, -1)}+01:00`;
+}
+
+/** `time` to the second, for a file name: `2026-10-09T14-03-21`. A colon is not allowed in a name on Windows. */
+export function fileStampCet(time: Date = new Date()): string {
+  return isoCet(time).slice(0, 19).replace(/:/g, "-");
+}

package/src/trace.ts

@@ -0,0 +1,162 @@
+// An opt-in trace for the person who debugs a run. With C64RT_TRACE=<directory>
+// in the environment, each process appends its events as JSON lines to a file
+// of its own in that directory; unset, every call does nothing. The trace is
+// for people: nothing of it reaches the agent, and no result depends on it.
+
+import { appendFileSync, copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { fileStampCet, isoCet } from "./time.ts";
+
+export const TRACE_VARIABLE = "C64RT_TRACE";
+
+/** The programs that write a trace, each to a file named after it. */
+export type TraceKind = "host" | "mcp" | "script" | "cli";
+
+/** The fields of one event. `t`, `kind` and `event` are set by the trace; a field that is undefined is left out. */
+export type TraceFields = Record<string, unknown>;
+
+const TEXT_LIMIT = 2_000;
+const ITEM_LIMIT = 32;
+const DEPTH_LIMIT = 4;
+const RESERVED = new Set(["t", "kind", "event"]);
+
+/**
+ * A value as the trace records it: bytes become their count, text and arrays
+ * beyond a limit are cut and say so, an Error keeps its name, message and
+ * code, and an object deeper than four levels ends in "…".
+ */
+export function summarize(value: unknown, depth = 0): unknown {
+  if (value instanceof Uint8Array) return { bytes: value.length };
+  if (typeof value === "string") return value.length > TEXT_LIMIT ? `${value.slice(0, TEXT_LIMIT)}… (${value.length} characters)` : value;
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Error) {
+    const code = (value as { code?: unknown }).code;
+    return { name: value.name, message: value.message, ...(typeof code === "string" ? { code } : {}) };
+  }
+  if (typeof value !== "object" || value === null) return value;
+  if (depth >= DEPTH_LIMIT) return "…";
+  if (Array.isArray(value)) {
+    const items = value.slice(0, ITEM_LIMIT).map((item) => summarize(item, depth + 1));
+    return value.length > ITEM_LIMIT ? [...items, `… (${value.length} items)`] : items;
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, summarize(item, depth + 1)]));
+}
+
+/**
+ * The version of c64-re-tools that runs, from the package.json next to src/:
+ * the package's own, or the one that install writes into a skill. Undefined
+ * when there is none.
+ */
+function runningVersion(): string | undefined {
+  try {
+    const { version } = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { version?: unknown };
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Milliseconds since `since`, a performance.now() reading, to a tenth. */
+export function elapsedMs(since: number): number {
+  return Math.round((performance.now() - since) * 10) / 10;
+}
+
+export class Trace {
+  readonly kind: TraceKind;
+  /** The directory of the trace, or undefined when the trace is off. */
+  readonly dir: string | undefined;
+  /** The file this trace appends to, or undefined when the trace is off. */
+  readonly file: string | undefined;
+  #broken = false;
+
+  private constructor(kind: TraceKind, dir: string | undefined, file: string | undefined) {
+    this.kind = kind;
+    this.dir = dir;
+    this.file = file;
+  }
+
+  /** A trace that records nothing. */
+  static off(kind: TraceKind): Trace {
+    return new Trace(kind, undefined, undefined);
+  }
+
+  /**
+   * A trace into `dir`, created when it is missing. The file is
+   * `<kind>-<CET time>-<pid>.jsonl`, and its first event is `trace.start`.
+   * Throws when the directory cannot be used.
+   */
+  static open(kind: TraceKind, dir: string, now = new Date()): Trace {
+    mkdirSync(dir, { recursive: true });
+    const trace = new Trace(kind, dir, join(dir, `${kind}-${fileStampCet(now)}-${process.pid}.jsonl`));
+    trace.event("trace.start", { version: runningVersion(), pid: process.pid, argv: process.argv.slice(1), cwd: process.cwd(), node: process.version, platform: process.platform });
+    return trace;
+  }
+
+  get on(): boolean {
+    return this.file !== undefined && !this.#broken;
+  }
+
+  /** Appends one event. A write that fails turns the trace off; nothing throws. */
+  event(name: string, fields: TraceFields = {}): void {
+    if (!this.on) return;
+    const line: Record<string, unknown> = { t: isoCet(), kind: this.kind, event: name };
+    for (const [key, value] of Object.entries(fields)) {
+      if (!RESERVED.has(key) && value !== undefined) line[key] = summarize(value);
+    }
+    try {
+      appendFileSync(this.file!, `${JSON.stringify(line)}\n`);
+    } catch {
+      this.#broken = true;
+    }
+  }
+
+  /** A free-text line, as the programs print to stderr, recorded as the event `log`. */
+  log(line: string): void {
+    this.event("log", { line });
+  }
+
+  /**
+   * Copies a file that would otherwise go away (VICE's own log) next to the
+   * trace, as `<kind>-<pid>-<name>`. A copy that fails is recorded, not thrown.
+   */
+  keep(source: string, name: string): void {
+    if (!this.on) return;
+    const target = join(this.dir!, `${this.kind}-${process.pid}-${name}`);
+    try {
+      copyFileSync(source, target);
+      this.event("trace.kept", { source, file: target });
+    } catch (error) {
+      this.event("trace.keep-failed", { source, error });
+    }
+  }
+}
+
+// Off until a program calls startTrace; the kind is a placeholder until then.
+let current = Trace.off("script");
+
+/**
+ * Switches the trace of this process on when `env` (the environment by
+ * default) has C64RT_TRACE, and off otherwise. A directory that cannot be used
+ * leaves the trace off and reports that through `warn`. Called once, at the
+ * start of a program.
+ */
+export function startTrace(kind: TraceKind, options: { env?: NodeJS.ProcessEnv; warn?: (line: string) => void } = {}): Trace {
+  const dir = (options.env ?? process.env)[TRACE_VARIABLE];
+  if (dir === undefined || dir === "") {
+    current = Trace.off(kind);
+    return current;
+  }
+  try {
+    current = Trace.open(kind, dir);
+  } catch (error) {
+    current = Trace.off(kind);
+    options.warn?.(`${TRACE_VARIABLE}=${dir} cannot be used (${error instanceof Error ? error.message : String(error)}); the trace is off.`);
+  }
+  return current;
+}
+
+/** The trace of this process: off until startTrace switches it on. */
+export function trace(): Trace {
+  return current;
+}

package/THIRD-PARTY-NOTICES.md

@@ -1,26 +0,0 @@
-# Third-Party Notices for `@henols/c64-re-tools`
-
-This package is MIT-licensed, copyright Henrik Olsson (see `LICENSE` at the
-repository root). It ships the C64 reverse-engineering **skill playbooks**
-under `skills/` plus the installer CLI under `bin/`, and it declares one
-runtime dependency, `@henols/vice-mcp`, which carries its own notices file.
-
-This document covers only the third-party material that ships **in this
-package**. It is deliberately not a second, competing inventory: the canonical
-third-party notices for the whole repository — including the cc65 opcode-table
-transcription and the ACME/VICE not-incorporated scope notes, none of which
-ship here — live in the `@henols/vice-mcp` package at
-`src/mcp/vice/THIRD-PARTY-NOTICES.md` in the repository, and inside that
-package's own tarball as `THIRD-PARTY-NOTICES.md`. Read that file for the full
-inventory; read this one for what `@henols/c64-re-tools` itself carries.
-
-## Incorporated material
-
-None. The skill playbooks under `skills/` are this project's own prose,
-written against this project's own curated tool surface.
-
-## Runtime dependency
-
-- **`@henols/vice-mcp`** — this repository's own MCP server package, MIT. Its
-  own third-party notices ship inside it as `THIRD-PARTY-NOTICES.md`, and that
-  file is the canonical inventory referred to at the top of this document.

package/bin/cli.mjs

@@ -1,283 +0,0 @@
-#!/usr/bin/env node
-// @henols/c64-re-tools installer.
-//
-// Installs the C64 reverse-engineering skills and wires the VICE MCP server into
-// a target project:
-//   npx @henols/c64-re-tools [targetDir] [--force] [--dry-run] [--vendor]
-//
-//   * copies the bundled skills into <target>/.claude/skills/
-//   * merges a `vice` server entry into <target>/.mcp.json (never clobbering
-//     other servers), launching it via `npx -y @henols/vice-mcp`
-//   * with --vendor, also `npm install`s @henols/vice-mcp into the project and
-//     wires .mcp.json to the local copy (pinned/offline use)
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve } from "node:path";
-// Entry-point dispatch guard (see the bottom of this file): the same idiom
-// `src/skills/c64-memory-mapping/scripts/driver.mjs` already uses, so a bare
-// `import` from a test file does not also execute the CLI.
-import {
-  existsSync,
-  readFileSync,
-  writeFileSync,
-  mkdirSync,
-  readdirSync,
-  cpSync,
-} from "node:fs";
-
-const HERE = dirname(fileURLToPath(import.meta.url)); // installer/bin (packed) or repo installer/bin (dev)
-const PKG_ROOT = dirname(HERE);
-const SKILLS_SRC = join(PKG_ROOT, "skills");
-
-// The single version-resolution seam this repo maintains is
-// `src/mcp/vice/version.ts` -- one algorithm for resolving a VERSION
-// template against a published version, kept in exactly one place after
-// this repo once carried several independent copies of it. This package
-// deliberately does NOT import it: it ships without the seam file (its
-// `files[]` is `bin/`, `skills/`, `README.md`) and targets node >= 18, which
-// cannot type-strip the seam's `.ts` the way the vice-mcp package's own
-// node >= 24 runtime can. What follows is exactly the seam's own
-// precedence step 1 -- "read my own package.json's `.version`, trust it
-// when it is a real published number" -- not a second, independent
-// implementation of the resolution algorithm; there is no template/`-`
-// handling here because this package is never resolved from `VERSION`,
-// only ever published with a concrete version already stamped in. That
-// number is PRODUCED elsewhere: `scripts/version.mjs stamp` writes the
-// working-tree placeholder, and CI's `npm version` writes the real one at
-// publish time. Do not reimplement the seam's own VERSION-template
-// parsing and prefix-resolution rules here.
-const SELF = readJson(join(PKG_ROOT, "package.json")) ?? {};
-const SELF_VERSION = typeof SELF.version === "string" ? SELF.version : "0.0.0";
-const MCP_PKG = "@henols/vice-mcp";
-// The dev placeholder every derived, publishable version string carries in
-// the working tree outside a stamped release. Defined authoritatively as
-// `DEV_PLACEHOLDER` in `src/mcp/vice/version.ts` -- repeated here as a
-// literal, NOT imported, because this package deliberately ships without
-// that seam file (see the comment above) and targets node >= 18, which
-// cannot type-strip a `.ts` import the way the vice-mcp package's own
-// node >= 24 runtime can. This is the same disclosed divergence as
-// `SELF_VERSION` above: one literal, kept in sync by hand, documented here
-// so a future edit to the seam's placeholder is not missed.
-const MCP_DEV_PLACEHOLDER = "0.0.0-dev";
-// Wire the project to the exact vice-mcp version this installer was built
-// against -- EXCEPT when run from an unstamped dev checkout:
-// `installer/package.json`'s dependency pin is the permanent working-tree
-// placeholder outside a CI-stamped publish job, and `@henols/vice-mcp` at
-// that literal version will never exist on the npm registry. Silently
-// writing it into a consumer's .mcp.json would 404 every time Claude Code
-// tries to launch the server, with no error until the user actually tries
-// to use it -- strictly worse than falling back to "latest". Fall back AND
-// warn loudly, so a developer testing the installer locally knows their
-// .mcp.json is unpinned rather than discovering it via a silent 404 later.
-const MCP_VERSION_RAW =
-  SELF.dependencies && typeof SELF.dependencies[MCP_PKG] === "string"
-    ? SELF.dependencies[MCP_PKG].replace(/^[\^~]/, "")
-    : SELF_VERSION;
-if (MCP_VERSION_RAW === MCP_DEV_PLACEHOLDER) {
-  console.error(
-    `c64-re-tools: WARNING -- running from an unstamped dev checkout (installer/package.json pins ` +
-      `${MCP_PKG}@${MCP_DEV_PLACEHOLDER}, the dev placeholder, not a real published version). ` +
-      `Falling back to "${MCP_PKG}@latest" in the generated .mcp.json instead of writing an ` +
-      `unresolvable pin. If you intended to test against a specific version, pass --vendor or fix ` +
-      `installer/package.json's dependency pin before packaging a release.`
-  );
-}
-const MCP_VERSION = MCP_VERSION_RAW === MCP_DEV_PLACEHOLDER ? "latest" : MCP_VERSION_RAW;
-
-function readJson(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return undefined;
-  }
-}
-
-function parseArgs(argv) {
-  const opts = { force: false, dryRun: false, vendor: false, help: false, target: undefined };
-  for (const arg of argv) {
-    if (arg === "--force") opts.force = true;
-    else if (arg === "--dry-run" || arg === "-n") opts.dryRun = true;
-    else if (arg === "--vendor") opts.vendor = true;
-    else if (arg === "--help" || arg === "-h") opts.help = true;
-    else if (arg.startsWith("-")) {
-      console.error(`c64-re-tools: unknown flag ${JSON.stringify(arg)} (try --help)`);
-      process.exit(2);
-    } else if (opts.target === undefined) opts.target = arg;
-    else {
-      console.error(`c64-re-tools: unexpected extra argument ${JSON.stringify(arg)} (try --help)`);
-      process.exit(2);
-    }
-  }
-  return opts;
-}
-
-const HELP = `c64-re-tools -- install the C64 reverse-engineering skills + VICE MCP server into a project
-
-Usage:
-  npx @henols/c64-re-tools [targetDir] [options]
-
-Arguments:
-  targetDir            Project to install into (default: current directory)
-
-Options:
-  --force              Overwrite existing skills and an existing 'vice' MCP entry
-  --vendor             Also 'npm install -D ${MCP_PKG}' into the project and wire
-                       .mcp.json to the local copy (pinned/offline), instead of npx
-  --dry-run, -n        Show what would change without writing anything
-  --help, -h           Show this help
-
-What it does:
-  1. Copies bundled skills into <target>/.claude/skills/
-  2. Adds a 'vice' server to <target>/.mcp.json (other servers are preserved)
-
-Requires Node >= 24 to RUN the vice MCP server (this installer runs on Node >= 18).`;
-
-function viceServerEntry(vendor) {
-  return {
-    command: "npx",
-    args: vendor ? [MCP_PKG] : ["-y", `${MCP_PKG}@${MCP_VERSION}`],
-    timeout: 150000,
-    env: { MASTRA_TELEMETRY_DISABLED: "1" },
-  };
-}
-
-function installSkills(target, { force, dryRun }) {
-  if (!existsSync(SKILLS_SRC)) {
-    console.error(
-      `c64-re-tools: FAIL -- bundled skills not found at ${SKILLS_SRC}. ` +
-        `(In a dev checkout, run 'node scripts/sync-skills.mjs' first.)`
-    );
-    process.exit(1);
-  }
-  const names = readdirSync(SKILLS_SRC, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name)
-    .sort();
-  const destRoot = join(target, ".claude", "skills");
-  const installed = [];
-  const skipped = [];
-  for (const name of names) {
-    const dest = join(destRoot, name);
-    if (existsSync(dest) && !force) {
-      skipped.push(name);
-      continue;
-    }
-    if (!dryRun) {
-      mkdirSync(destRoot, { recursive: true });
-      cpSync(join(SKILLS_SRC, name), dest, { recursive: true, force: true });
-    }
-    installed.push(name);
-  }
-  return { destRoot, installed, skipped, total: names.length };
-}
-
-function wireMcp(target, { force, dryRun, vendor }) {
-  const mcpPath = join(target, ".mcp.json");
-  let config = { mcpServers: {} };
-  if (existsSync(mcpPath)) {
-    const parsed = readJson(mcpPath);
-    if (parsed === undefined) {
-      console.error(
-        `c64-re-tools: FAIL -- ${mcpPath} exists but is not valid JSON. ` +
-          `Refusing to overwrite it; fix or remove it and re-run.`
-      );
-      process.exit(1);
-    }
-    config = parsed;
-    if (typeof config !== "object" || config === null || Array.isArray(config)) {
-      console.error(`c64-re-tools: FAIL -- ${mcpPath} is not a JSON object.`);
-      process.exit(1);
-    }
-    if (typeof config.mcpServers !== "object" || config.mcpServers === null) {
-      config.mcpServers = {};
-    }
-  }
-  const existed = Object.prototype.hasOwnProperty.call(config.mcpServers, "vice");
-  let action;
-  if (existed && !force) {
-    action = "kept"; // leave the user's existing entry alone
-  } else {
-    action = existed ? "updated" : "added";
-    if (!dryRun) {
-      config.mcpServers.vice = viceServerEntry(vendor);
-      mkdirSync(dirname(mcpPath), { recursive: true });
-      writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
-    }
-  }
-  return { mcpPath, action };
-}
-
-function vendorInstall(target, { dryRun }) {
-  const spec = `${MCP_PKG}@${MCP_VERSION}`;
-  if (dryRun) return { ran: false, spec };
-  const res = spawnSync("npm", ["install", "--save-dev", spec], {
-    cwd: target,
-    stdio: "inherit",
-  });
-  if (res.status !== 0) {
-    console.error(
-      `c64-re-tools: WARN -- 'npm install --save-dev ${spec}' exited ${res.status}. ` +
-        `Skills and .mcp.json were still written; install the package manually if needed.`
-    );
-    return { ran: true, ok: false, spec };
-  }
-  return { ran: true, ok: true, spec };
-}
-
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  if (opts.help) {
-    console.log(HELP);
-    return;
-  }
-  const target = resolve(opts.target ?? process.cwd());
-  if (!existsSync(target)) {
-    console.error(`c64-re-tools: FAIL -- target directory does not exist: ${target}`);
-    process.exit(1);
-  }
-
-  console.error(`c64-re-tools ${SELF_VERSION} -> ${target}${opts.dryRun ? "  (dry run)" : ""}`);
-
-  const skills = installSkills(target, opts);
-  if (opts.vendor) vendorInstall(target, opts);
-  const mcp = wireMcp(target, opts);
-
-  // Summary
-  console.error("");
-  console.error(`  skills  -> ${skills.destRoot}`);
-  console.error(
-    `            ${skills.installed.length} installed${
-      opts.force ? "" : `, ${skills.skipped.length} already present (use --force to overwrite)`
-    } of ${skills.total}`
-  );
-  if (skills.installed.length) console.error(`            + ${skills.installed.join(", ")}`);
-  if (skills.skipped.length && !opts.force)
-    console.error(`            = ${skills.skipped.join(", ")} (kept)`);
-  console.error(`  mcp     -> ${mcp.mcpPath}`);
-  if (mcp.action === "kept") {
-    console.error(`            'vice' already configured -- kept (use --force to overwrite)`);
-  } else {
-    console.error(
-      `            'vice' ${mcp.action}${
-        opts.vendor ? ` (local ${MCP_PKG})` : ` (npx -y ${MCP_PKG}@${MCP_VERSION})`
-      }`
-    );
-  }
-  console.error("");
-  if (opts.dryRun) {
-    console.error("Dry run -- nothing was written.");
-  } else {
-    console.error("Done. Restart Claude Code in this project so it picks up the skills and MCP server.");
-    console.error("Note: running the vice MCP server requires Node >= 24.");
-  }
-}
-
-// Only dispatch when this module is the process entry point -- i.e. run as
-// `node bin/cli.mjs ...` or via the `c64-re-tools` bin shim -- not when
-// imported by a test (installer/wire-mcp.test.mjs imports `wireMcp`/`readJson`
-// below and must not trigger a real install as a side effect).
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main();
-}
-
-export { wireMcp, readJson };