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

package/skills/c64-ram-capture/scripts/dump-artifacts.mjs

@@ -1,317 +0,0 @@
-#!/usr/bin/env node
-// The artifact renderer (01-04 Task 1, Part B). This module exists because
-// of a structural fact worth stating up front: the executing agent can
-// write text, not binary, so the only shape a committable 65536-byte image
-// can take under the one permitted route to the emulator is *the agent
-// serialises what it fetched via mcp__plugin_c64-re-tools_vice__* tool calls, and a pure
-// function renders it*. Every function below takes already-fetched data as
-// an argument -- nothing here contacts the emulator.
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve, relative } from "node:path";
-
-import { releaseDir } from "./releases.mjs";
-import { projectRoot } from "./project-paths.mjs";
-import { addrNum, hex4 } from "./watch-loads.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = projectRoot();
-
-const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
-
-function rel(p) {
-  return relative(REPO_ROOT, p);
-}
-
-// ---------------------------------------------------------------- assembleImage
-
-/**
- * Assemble the ordered `{ address, hex }` chunk records the agent wrote
- * after its `mcp__plugin_c64-re-tools_vice__vice_memory_read` calls into a 65536-byte buffer.
- * Asserts contiguity from $0000 with no gap and no overlap and a total of
- * exactly 65536 bytes, naming the offending address in every failure.
- */
-export function assembleImage(chunks) {
-  const sorted = [...chunks].sort((a, b) => addrNum(a.address) - addrNum(b.address));
-  const bufs = [];
-  let expected = 0;
-  for (const c of sorted) {
-    const addr = addrNum(c.address);
-    const buf = Buffer.from(c.hex, "hex");
-    if (addr > expected) {
-      throw new Error(`assembleImage: gap before address ${hex4(expected)} -- next chunk starts at ${hex4(addr)}`);
-    }
-    if (addr < expected) {
-      throw new Error(`assembleImage: overlap at address ${hex4(addr)} -- a previous chunk already covered up to ${hex4(expected - 1)}`);
-    }
-    bufs.push(buf);
-    expected += buf.length;
-  }
-  const total = Buffer.concat(bufs);
-  if (total.length !== 65536) {
-    throw new Error(`assembleImage: assembled ${total.length} bytes ending at ${hex4(expected)}, expected exactly 65536`);
-  }
-  return total;
-}
-
-/** SHA-256 of a buffer, hex-encoded. `node:crypto` only -- no package added. */
-export function sha256Buffer(buf) {
-  return createHash("sha256").update(buf).digest("hex");
-}
-
-// ----------------------------------------------------------------- vicBank
-
-/**
- * VIC-II bank number (0-3) from CIA2 port A ($DD00)'s low two bits. The
- * stored value is the INVERSE of the bank number (c64-memory-mapping skill
- * memmap: raw value %00 = "Bank #3" $C000-$FFFF ... %11 = "Bank #0"
- * $0000-$3FFF), so bank = 3 - (raw & 3). Verified against
- * a committed chip-state sidecar's own recorded
- * dd00_raw=193 (0xC1, low bits %01) -> vic_bank=2, which this formula
- * reproduces exactly.
- */
-export function vicBank(dd00Raw) {
-  return 3 - (dd00Raw & 3);
-}
-
-// --------------------------------------------------------------- screenBase
-
-/**
- * Screen memory base address, derived from $D018's bits 4-7 (screen pointer,
- * in 1024-byte units relative to the VIC bank) added to the VIC bank's own
- * base (bank * 16384). Verified against the same committed sidecar:
- * dd00_raw=193, d018_raw=49 (0x31) -> screen_base=35840, reproduced exactly.
- */
-export function screenBase(d018Raw, dd00Raw) {
-  const bank = vicBank(dd00Raw);
-  const bankBase = bank * 16384;
-  const screenOffset = ((d018Raw >> 4) & 0xf) * 1024;
-  return bankBase + screenOffset;
-}
-
-/** Character memory base: $D018 bits 1-3, in 2048-byte units relative to the VIC bank. */
-function charsetBase(d018Raw, dd00Raw) {
-  const bank = vicBank(dd00Raw);
-  const bankBase = bank * 16384;
-  const charsetOffset = ((d018Raw >> 1) & 0x7) * 2048;
-  return bankBase + charsetOffset;
-}
-
-// -------------------------------------------------------------- buildChipState
-
-/**
- * Build the chip-state sidecar in the exact shape the committed
- * primary sidecars already use (same top-level keys, same `derived` field
- * set), from the register/state readings the agent recorded. `raw` carries
- * whatever the agent fetched via vice_registers_get / vice_sprite_get /
- * vice_memory_read, keyed to match: `registers`, `sprites`, `cpu` pass
- * through verbatim; `dd00_raw`, `d018_raw`, `port01_raw` and
- * `sprite_pointers` (the bytes read from the sprite-pointer table at
- * screen_base+$3F8..$3FF) feed the derivation.
- */
-export function buildChipState(raw) {
-  const dd00 = raw.dd00_raw;
-  const d018 = raw.d018_raw;
-  const bank = vicBank(dd00);
-  const bankBase = bank * 16384;
-  const screenBaseAddr = screenBase(d018, dd00);
-  const charsetBaseAddr = charsetBase(d018, dd00);
-  const port01raw = raw.port01_raw;
-  const spritePointers = raw.sprite_pointers ?? [];
-  const spriteDataAddresses = spritePointers.map((p) => bankBase + p * 64);
-
-  return {
-    schema_version: 1,
-    release: raw.release,
-    label: raw.label,
-    snapshot_name: raw.snapshot_name ?? null,
-    registers: raw.registers,
-    sprites: raw.sprites,
-    cpu: raw.cpu,
-    derived: {
-      port01: {
-        raw: port01raw,
-        loram: !!(port01raw & 1),
-        hiram: !!(port01raw & 2),
-        charen: !!(port01raw & 4),
-      },
-      dd00_raw: dd00,
-      dd00_direct_read: raw.dd00_direct_read ?? dd00,
-      vic_bank: bank,
-      d018_raw: d018,
-      screen_base: screenBaseAddr,
-      charset_base: charsetBaseAddr,
-      sprite_pointers: spritePointers,
-      sprite_data_addresses: spriteDataAddresses,
-    },
-    captured_at: raw.captured_at ?? new Date().toISOString(),
-  };
-}
-
-// ---------------------------------------------------------- buildRangeManifest
-
-const IO_START = 0xd000;
-const IO_END = 0xdfff;
-
-function powerOnRunLength(image, start) {
-  const b = image[start];
-  if (b !== 0x00 && b !== 0xff) return 0;
-  let end = start;
-  while (end < image.length && image[end] === b) end++;
-  return end - start;
-}
-
-/**
- * Emit the range manifest in the committed shape: ranges whose union
- * covers $0000-$FFFF with no gap and no overlap, a contiguous power-on-
- * pattern run of at least 16 bytes marked kind `unused`, the I/O window
- * ($D000-$DFFF) marked `io`, everything else `unclassified`, and
- * `classification_state` set to the same transient `ranges-only` state the
- * committed primary manifests carry.
- */
-export function buildRangeManifest(image, meta = {}) {
-  if (image.length !== 65536) {
-    throw new Error(`buildRangeManifest: image must be exactly 65536 bytes, got ${image.length}`);
-  }
-  const ranges = [];
-  let i = 0;
-  while (i < 65536) {
-    if (i >= IO_START && i <= IO_END) {
-      ranges.push({ start: i, end: IO_END, kind: "io", source: "capture", note: "VIC-II/SID/CIA/color-RAM I/O window" });
-      i = IO_END + 1;
-      continue;
-    }
-    const runLen = powerOnRunLength(image, i);
-    if (runLen >= 16) {
-      const end = i + runLen - 1;
-      ranges.push({ start: i, end, kind: "unused", source: "capture", note: "contiguous $00/$FF power-on-pattern run of at least 16 bytes" });
-      i = end + 1;
-      continue;
-    }
-    let j = i;
-    while (j < 65536 && !(j >= IO_START && j <= IO_END) && powerOnRunLength(image, j) < 16) {
-      j++;
-    }
-    ranges.push({ start: i, end: j - 1, kind: "unclassified", source: "capture", note: "awaiting the loader/cracktro/game three-bucket partition" });
-    i = j;
-  }
-  return {
-    schema_version: 1,
-    release: meta.release,
-    label: meta.label,
-    snapshot_name: meta.snapshot_name ?? null,
-    image_bytes: image.length,
-    offset_equals_address: true,
-    classification_state: "ranges-only",
-    ranges,
-    note: meta.note ?? "",
-    generated_at: meta.generated_at ?? new Date().toISOString(),
-  };
-}
-
-// -------------------------------------------------------------- writeDumpSet
-
-/**
- * Render and write the four-file dump set from a committed chunk file's
- * contents plus the chip-state raw readings. Returns the written paths and
- * the image digest, so a caller can register a `dumps[]` entry.
- */
-export function writeDumpSet({ releaseId, label, chunks, chipStateRaw, meta = {}, captureExtra = {} }) {
-  const image = assembleImage(chunks);
-  const digest = sha256Buffer(image);
-  const dumpsDir = join(releaseDir(releaseId), "dumps");
-  mkdirSync(dumpsDir, { recursive: true });
-
-  const binPath = join(dumpsDir, `${releaseId}-${label}.bin`);
-  writeFileSync(binPath, image);
-
-  const stateOut = buildChipState({ ...chipStateRaw, release: releaseId, label });
-  const statePath = join(dumpsDir, `${releaseId}-${label}.state.json`);
-  writeFileSync(statePath, JSON.stringify(stateOut, null, 2) + "\n");
-
-  const manifestOut = buildRangeManifest(image, { release: releaseId, label, ...meta });
-  const mapPath = join(dumpsDir, `${releaseId}-${label}.map.json`);
-  writeFileSync(mapPath, JSON.stringify(manifestOut, null, 2) + "\n");
-
-  const captureOut = {
-    release: releaseId,
-    label,
-    sha256: digest,
-    bytes: image.length,
-    ...captureExtra,
-  };
-  const capturePath = join(dumpsDir, `${releaseId}-${label}.capture.json`);
-  writeFileSync(capturePath, JSON.stringify(captureOut, null, 2) + "\n");
-
-  return {
-    bin: rel(binPath),
-    state: rel(statePath),
-    map: rel(mapPath),
-    capture: rel(capturePath),
-    sha256: digest,
-  };
-}
-
-// -------------------------------------------------------------------- CLI
-
-function optValue(rest, name) {
-  const i = rest.indexOf(`--${name}`);
-  return i === -1 ? undefined : rest[i + 1];
-}
-
-function readJsonArg(rest, name) {
-  const p = optValue(rest, name);
-  if (!p) return undefined;
-  return JSON.parse(readFileSync(resolve(p), "utf8"));
-}
-
-const VERBS = {
-  assemble(rest) {
-    const chunks = readJsonArg(rest, "chunks");
-    if (!chunks) die("usage: assemble --chunks <chunks.json> [--json]");
-    const image = assembleImage(chunks);
-    const digest = sha256Buffer(image);
-    const result = { bytes: image.length, sha256: digest };
-    console.log(rest.includes("--json") ? JSON.stringify(result, null, 2) : `${result.bytes} bytes, sha256 ${result.sha256}`);
-  },
-
-  "chip-state"(rest) {
-    const raw = readJsonArg(rest, "raw");
-    if (!raw) die("usage: chip-state --raw <raw.json> [--json]");
-    const result = buildChipState(raw);
-    console.log(JSON.stringify(result, null, 2));
-  },
-
-  manifest(rest) {
-    const chunks = readJsonArg(rest, "chunks");
-    const metaArg = readJsonArg(rest, "meta") ?? {};
-    if (!chunks) die("usage: manifest --chunks <chunks.json> [--meta <meta.json>] [--json]");
-    const image = assembleImage(chunks);
-    const result = buildRangeManifest(image, metaArg);
-    console.log(JSON.stringify(result, null, 2));
-  },
-
-  "write-set"(rest) {
-    const releaseId = optValue(rest, "release");
-    const label = optValue(rest, "label");
-    const chunks = readJsonArg(rest, "chunks");
-    const chipStateRaw = readJsonArg(rest, "raw");
-    const metaArg = readJsonArg(rest, "meta") ?? {};
-    if (!releaseId || !label || !chunks || !chipStateRaw) {
-      die("usage: write-set --release <id> --label <label> --chunks <chunks.json> --raw <raw.json> [--meta <meta.json>] [--json]");
-    }
-    const result = writeDumpSet({ releaseId, label, chunks, chipStateRaw, meta: metaArg });
-    console.log(JSON.stringify(result, null, 2));
-  },
-};
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [cmd, ...rest] = process.argv.slice(2);
-  if (!cmd || !VERBS[cmd]) {
-    console.log(`usage: node ${fileURLToPath(import.meta.url)} <assemble|chip-state|manifest|write-set> [--json]`);
-    process.exitCode = cmd ? 1 : 0;
-  } else {
-    VERBS[cmd](rest);
-  }
-}

package/skills/c64-ram-capture/scripts/mcp-module.mjs

@@ -1,174 +0,0 @@
-#!/usr/bin/env node
-// mcp-module.mjs -- the ONE resolution ladder a skill script uses to reach a
-// module that lives in the OTHER package (`@henols/vice-mcp`'s `src/mcp/vice/`
-// tree, as opposed to this file's own `@henols/c64-re-tools` skills tree).
-//
-// ---------------------------------------------------------------------------
-// WHY THIS FILE EXISTS
-// ---------------------------------------------------------------------------
-// Before this file existed, `vsf-slice.mjs`
-// carried its own copy of this exact three-rung ladder (`ladder()` /
-// `resolveTarget()`), and TWO MORE skill scripts (`acme.mjs`,
-// `packer-finding.mjs`) were about to migrate onto the host-tool execution
-// seam and were each going to need the identical lookup to reach
-// `host-tool-client.ts`. Three production consumers were about to carry
-// three copies of one ladder -- so it is extracted here instead, and
-// `vsf-slice.mjs` is rewritten to import it rather than keep its own.
-//
-// The underlying constraint this ladder exists to answer is
-// `vsf-slice.mjs`'s own recorded finding: the MCP server ships as
-// `@henols/vice-mcp`, whose `files[]` lists only `src/mcp/vice/` contents,
-// while `src/skills/**` ships in a DIFFERENT package (`@henols/c64-re-tools`).
-// A plain `import` from a skill script into the MCP tree resolves on NEITHER
-// npm-installer route, so a skill script that needs an MCP-side module must
-// LOCATE it on disk and invoke it as a subprocess (`process.execPath
-// <resolved-path> ...argv`) -- never a static `import`.
-//
-// ---------------------------------------------------------------------------
-// WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR
-// ---------------------------------------------------------------------------
-//   - the three-rung resolution order (`$VICE_MCP_DIR`, the in-repo relative
-//     path, then `require.resolve()` against the published package) for
-//     locating ANY named file inside `src/mcp/vice/` from a skill's own
-//     `scripts/` directory;
-//   - refusing BY NAME, listing every rung tried, when none resolves
-//     (`refusalMessage()`);
-//   - computing the in-repo hop count from `import.meta.url` rather than a
-//     fixed `".."` count -- `hostpath.ts` and `containerpath.ts` both record
-//     dropping a hard-coded four-level hop when they moved directories once
-//     already, and this project has ALSO shipped a stale hardcoded snapshot
-//     offset before (see `vsf-slice.mjs`'s own header) -- a fixed `".."`
-//     count is a mistake this project keeps making, not a one-off.
-//
-// ---------------------------------------------------------------------------
-// WHAT NOT TO DO
-// ---------------------------------------------------------------------------
-//   - Never carry a second copy of these three rungs, their ordering, or
-//     their refusal text anywhere else in this repository. A future
-//     skill-side consumer of an MCP-side module imports `resolveMcpModule`
-//     from HERE.
-//   - Never let a resolution failure become a local re-implementation of
-//     whatever was being resolved -- refuse by name instead. A silent
-//     fallback that reimplements the target module's own logic is exactly
-//     the divergence this ladder exists to prevent (see `vsf-slice.mjs`'s own
-//     header on the stale-offset incident this project has already had).
-//   - `process.execPath` spawned on a resolved `.ts`/`.mjs` file inside this
-//     project's OWN tree reaches NO external host binary -- it is the
-//     interpreter already running the calling script, pointed at an in-tree
-//     module. This is NOT what the host-tool execution seam (`host-tool.mts`
-//     / `host-tool-client.ts`) exists for, and must never be confused with
-//     it: the seam is for binaries that live on the HOST, outside any
-//     container; this ladder is for locating a file inside this project's own
-//     two npm packages.
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-import { basename, dirname, join, resolve } from "node:path";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-/** The package the MCP-side module ships in, for the npm-installer rung. */
-export const TARGET_PACKAGE = "@henols/vice-mcp";
-
-/**
- * Walks UP from `startDir` until a directory literally named `name` is
- * found, returning its absolute path -- or `null` if the filesystem root is
- * reached first without a match. This is what lets the in-repo hop count be
- * COMPUTED from `import.meta.url` instead of a fixed `".."` count: whichever
- * skill's `scripts/` directory this module is imported from, walking up to
- * the `skills/` ancestor and back down to `mcp/vice/` is the same operation.
- */
-function findAncestorDir(startDir, name) {
-  let dir = startDir;
-  for (;;) {
-    if (basename(dir) === name) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return null; // reached the filesystem root, no match
-    dir = parent;
-  }
-}
-
-// Computed once, at module load: HERE is .../src/skills/<skill>/scripts/, so
-// walking up to the "skills" ancestor and taking ITS parent ("src") gives the
-// root from which "mcp/vice" is a sibling of "skills" -- with no fixed hop
-// count written down anywhere in this file.
-const SKILLS_DIR = findAncestorDir(HERE, "skills");
-const IN_REPO_MCP_VICE_DIR = SKILLS_DIR ? join(dirname(SKILLS_DIR), "mcp", "vice") : null;
-
-/**
- * The resolution ladder for `fileName`, in order, as `{ rung, path, note }`
- * records -- returned IN FULL (never short-circuited), so a refusal message
- * can name every path tried, which is the whole point of refusing rather
- * than guessing:
- *
- *   1. `$VICE_MCP_DIR` -- an explicit override, checked first so a caller can
- *      always point this ladder at a known-good tree.
- *   2. The in-repo relative path (see `findAncestorDir()` above). The plugin
- *      distribution keeps both trees in one checkout, so this is the rung
- *      that resolves during development and in CI.
- *   3. `require.resolve()` against the published package, for the
- *      npm-installer route where the two packages are installed separately.
- */
-function ladder(fileName) {
-  const rungs = [];
-
-  const override = process.env.VICE_MCP_DIR;
-  rungs.push({
-    rung: "VICE_MCP_DIR",
-    path: override ? join(resolve(override), fileName) : null,
-    note: override ? null : "VICE_MCP_DIR is not set",
-  });
-
-  rungs.push({
-    rung: "in-repo relative path",
-    path: IN_REPO_MCP_VICE_DIR ? join(IN_REPO_MCP_VICE_DIR, fileName) : null,
-    note: IN_REPO_MCP_VICE_DIR ? null : `could not locate an ancestor "skills" directory from ${HERE}`,
-  });
-
-  let resolved = null;
-  let note = null;
-  try {
-    resolved = createRequire(import.meta.url).resolve(`${TARGET_PACKAGE}/${fileName}`);
-  } catch (err) {
-    note = `${TARGET_PACKAGE} is not resolvable from here (${err.code ?? err.message})`;
-  }
-  rungs.push({ rung: `${TARGET_PACKAGE} package`, path: resolved, note });
-
-  return rungs;
-}
-
-/**
- * Builds the refusal text naming every rung tried plus the instruction to
- * set `VICE_MCP_DIR` -- the ONE place this message is worded, so callers
- * that construct their own additional context around it (e.g.
- * `vsf-slice.mjs`'s own domain-specific rationale) do not restate it.
- */
-export function refusalMessage(fileName, rungs) {
-  const tried = rungs
-    .map((r) => `  ${r.rung}: ${r.path ?? "(no path)"}${r.note ? ` -- ${r.note}` : ""}`)
-    .join("\n");
-  return (
-    `could not resolve ${fileName}.\n` +
-    `Tried, in order:\n${tried}\n` +
-    `Set VICE_MCP_DIR to the directory holding ${fileName}.`
-  );
-}
-
-/**
- * Resolves `fileName` (e.g. `"vsf-slice.ts"`, `"host-tool-client.ts"`) against
- * the three-rung ladder above, with NO per-file special-casing -- every
- * caller gets the same three rungs in the same order.
- *
- * Returns `{ ok: true, rung, path }` for the first rung whose path exists on
- * disk, or `{ ok: false, rungs, message }` when none resolves -- `rungs`
- * carries the full attempt list (so a caller can build its own message from
- * the raw records instead of `refusalMessage()`, if it wants extra context),
- * and `message` is `refusalMessage(fileName, rungs)` already computed. Never
- * throws.
- */
-export function resolveMcpModule(fileName) {
-  const rungs = ladder(fileName);
-  const hit = rungs.find((r) => r.path && existsSync(r.path));
-  if (hit) return { ok: true, rung: hit.rung, path: hit.path };
-  return { ok: false, rungs, message: refusalMessage(fileName, rungs) };
-}

package/skills/c64-ram-capture/scripts/project-paths.mjs

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-// Where this toolkit's data lives, resolved portably.
-//
-// These modules ship as a bundled skill toolkit and may be installed at any
-// depth in any project, so nothing here counts directory hops. Two rules:
-//
-//   1. The project root is found by walking UP for a `.git` marker. Counting
-//      hops from `import.meta.url` breaks the moment the toolkit is installed
-//      somewhere other than `src/skills/<skill>/scripts/`, and it breaks
-//      silently -- paths resolve to a plausible wrong place rather than erroring.
-//   2. Every data location is overridable by environment variable, so a project
-//      that does not use this repo's `recovery/` + `disks/` layout can point the
-//      toolkit at its own without editing any module.
-//
-// Pure path arithmetic over the filesystem. Contacts nothing.
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve, parse } from "node:path";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-/**
- * Nearest ancestor directory containing a `.git` entry, starting from this
- * file. Falls back to `C64RE_PROJECT_ROOT` when set, which also covers the
- * case of running from an export with no git metadata at all.
- */
-export function projectRoot() {
-  if (process.env.C64RE_PROJECT_ROOT) return resolve(process.env.C64RE_PROJECT_ROOT);
-  let dir = HERE;
-  const { root } = parse(dir);
-  while (true) {
-    if (existsSync(join(dir, ".git"))) return dir;
-    if (dir === root) break;
-    dir = dirname(dir);
-  }
-  throw new Error(
-    "project-paths: could not locate the project root -- no `.git` found above " +
-      `${HERE}. Set C64RE_PROJECT_ROOT to the directory that holds your data dirs.`,
-  );
-}
-
-/**
- * Directory holding the release registry and the per-release dump directories.
- * Defaults to `<project root>/recovery`; override with `C64RE_DATA_DIR`.
- */
-export function dataRoot() {
-  return process.env.C64RE_DATA_DIR
-    ? resolve(process.env.C64RE_DATA_DIR)
-    : join(projectRoot(), "recovery");
-}
-
-/**
- * Directory holding the disk images a registry entry's `disk_image` is
- * relative to. Defaults to the project root itself, because registry entries
- * record project-relative paths like `disks/foo.d64`; override with
- * `C64RE_DISKS_ROOT` when they are relative to something else.
- */
-export function disksRoot() {
-  return process.env.C64RE_DISKS_ROOT
-    ? resolve(process.env.C64RE_DISKS_ROOT)
-    : projectRoot();
-}
-
-/** The release registry file. Override the whole path with `C64RE_REGISTRY`. */
-export function registryFile() {
-  return process.env.C64RE_REGISTRY
-    ? resolve(process.env.C64RE_REGISTRY)
-    : join(dataRoot(), "RELEASES.json");
-}
-
-/** One release's own data directory. */
-export function releaseDataDir(id) {
-  return join(dataRoot(), id);
-}
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  console.log(`project root: ${projectRoot()}`);
-  console.log(`data root:    ${dataRoot()}`);
-  console.log(`disks root:   ${disksRoot()}`);
-  console.log(`registry:     ${registryFile()}`);
-}

package/skills/c64-ram-capture/scripts/releases.mjs

@@ -1,109 +0,0 @@
-#!/usr/bin/env node
-// N-way release registry accessor. This is the only module that reads a release
-// identifier out of the registry -- every other module takes the id as an
-// argument and never touches the registry file directly. `release` is the
-// primary noun rather than "the canonical image": there are N releases, each
-// owning a set of dumps, with `canonical` demoted to a boolean on one entry.
-//
-// Portable: the registry's location comes from `project-paths.mjs`, so a project
-// with a different data layout points the toolkit at its own via
-// `C64RE_DATA_DIR` / `C64RE_REGISTRY` rather than editing this file.
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { resolve } from "node:path";
-
-import { registryFile, releaseDataDir } from "./project-paths.mjs";
-
-export const registryPath = registryFile();
-
-const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
-
-export function loadRegistry() {
-  if (!existsSync(registryPath)) {
-    throw new Error(`no registry at ${registryPath}`);
-  }
-  return JSON.parse(readFileSync(registryPath, "utf8"));
-}
-
-/**
- * Persist the registry. JSON.stringify preserves each object's insertion
- * (key) order, so a read-modify-write via upsertRelease keeps a stable key
- * order automatically -- callers should not rebuild release objects from
- * scratch with a different key order.
- */
-function saveRegistry(reg) {
-  writeFileSync(registryPath, JSON.stringify(reg, null, 2) + "\n");
-}
-
-/** The full entry for `id`, or throws with the known-id list on a miss. */
-export function release(id) {
-  const reg = loadRegistry();
-  const r = reg.releases.find((r) => r.id === id);
-  if (!r) assertKnownRelease(id, reg);
-  return r;
-}
-
-/**
- * The registry's own N-readiness documentation:
- * a top-level `schema_notes` string, sibling to `schema_version` and
- * `releases`, stating the mechanical claim that adding a release is one
- * `releases[]` entry plus one invocation of `tools/recover.mjs`. Kept as a
- * plain top-level field rather than a JSON comment (JSON has none) or a
- * per-release field (it describes the registry's shape, not any one
- * release). Rehearsed against the real validator in
- * a release's own NOTES.md.
- */
-export function schemaNotes() {
-  return loadRegistry().schema_notes ?? null;
-}
-
-export function releaseDir(id) {
-  const reg = loadRegistry();
-  assertKnownRelease(id, reg);
-  return releaseDataDir(id);
-}
-
-/** Dies with the list of known ids on a miss -- see plan Layer 2. */
-export function assertKnownRelease(id, reg) {
-  const registry = reg || loadRegistry();
-  const known = registry.releases.map((r) => r.id);
-  if (!known.includes(id)) {
-    throw new Error(`unknown release "${id}" -- known releases: ${known.join(", ")}`);
-  }
-}
-
-/**
- * Read-modify-write: `fn` receives a shallow copy of the release entry and
- * returns the replacement; the whole registry is then re-persisted with
- * stable key order. This is the only sanctioned way to mutate an entry.
- */
-export function upsertRelease(id, fn) {
-  const reg = loadRegistry();
-  const idx = reg.releases.findIndex((r) => r.id === id);
-  if (idx === -1) {
-    throw new Error(`unknown release "${id}" -- known releases: ${reg.releases.map((r) => r.id).join(", ")}`);
-  }
-  reg.releases[idx] = fn({ ...reg.releases[idx] });
-  saveRegistry(reg);
-  return reg.releases[idx];
-}
-
-// -------------------------------------------------------------------- CLI
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [cmd, ...rest] = process.argv.slice(2);
-  if (cmd === "list") {
-    const reg = loadRegistry();
-    for (const r of reg.releases) {
-      console.log(`${r.id}  canonical=${r.canonical}  disk_image=${r.disk_image}  dumps=${r.dumps.length}`);
-    }
-  } else if (cmd === "show") {
-    if (!rest[0]) die("usage: show <release-id>");
-    console.log(JSON.stringify(release(rest[0]), null, 2));
-  } else if (cmd === "schema-notes") {
-    console.log(schemaNotes() ?? "(no schema_notes field set)");
-  } else {
-    console.log(`usage: node ${fileURLToPath(import.meta.url)} <list|show <id>|schema-notes>`);
-    process.exit(cmd ? 1 : 0);
-  }
-}