@henols/c64-re-tools 0.1.4

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

@@ -0,0 +1,81 @@
+#!/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 `.claude/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

@@ -0,0 +1,109 @@
+#!/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 (01-03-PLAN.md's Task 2):
+ * 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);
+  }
+}

package/skills/c64-ram-capture/scripts/test-corpus.mjs

@@ -0,0 +1,75 @@
+// Locates committed artifacts through the registry, so tests exercise whatever
+// corpus the host project actually has instead of naming one project's files.
+//
+// The point is portability without losing coverage: a project with captures gets
+// the real-artifact assertions; a project with none gets them skipped, not
+// failed. Hardcoding `recovery/<some-release>/dumps/<some-label>.state.json`
+// meant this toolkit's tests could only ever pass in the repo they were written
+// in, which is the opposite of shippable.
+//
+// Test-support only. Pure filesystem reads; contacts nothing.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { projectRoot } from "./project-paths.mjs";
+import { loadRegistry } from "./releases.mjs";
+
+/**
+ * First dump in the registry whose `field` names a file that exists, as
+ * `{ release, label, path }` -- or null when the registry is absent, empty, or
+ * names nothing on disk. Never throws: a missing registry is a skip, not a
+ * failure.
+ */
+export function firstDumpArtifact(field) {
+  let reg;
+  try {
+    reg = loadRegistry();
+  } catch {
+    return null;
+  }
+  for (const r of reg.releases ?? []) {
+    for (const d of r.dumps ?? []) {
+      const value = d[field];
+      if (!value) continue;
+      const path = join(projectRoot(), value);
+      if (existsSync(path)) return { release: r.id, label: d.label, path };
+    }
+  }
+  return null;
+}
+
+/** Every dump in the registry whose `field` names an existing file. */
+export function allDumpArtifacts(field) {
+  let reg;
+  try {
+    reg = loadRegistry();
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const r of reg.releases ?? []) {
+    for (const d of r.dumps ?? []) {
+      const value = d[field];
+      if (!value) continue;
+      const path = join(projectRoot(), value);
+      if (existsSync(path)) out.push({ release: r.id, label: d.label, path });
+    }
+  }
+  return out;
+}
+
+/** Parsed JSON for a `firstDumpArtifact` hit, or null. */
+export function readJsonArtifact(field) {
+  const hit = firstDumpArtifact(field);
+  if (!hit) return null;
+  return { ...hit, json: JSON.parse(readFileSync(hit.path, "utf8")) };
+}
+
+/**
+ * node:test `skip` value: `false` to run, or a human-readable reason string.
+ * Pass the thing you looked for so a skipped run explains itself.
+ */
+export function skipUnless(found, what) {
+  if (found && (!Array.isArray(found) || found.length > 0)) return false;
+  return `no ${what} found via this project's registry -- corpus-dependent check skipped`;
+}