@henols/c64-re-tools 0.2.2 → 0.2.3

package/skills/c64-memory-mapping/SKILL.md

@@ -182,9 +182,9 @@ combined (driver.mjs:262, 268) — so a partially-reachable or partially-changed
 source set can silently replace good tracked data with less of it. Rebuild, then
 run `git diff --stat` on `memmap.json` before accepting the result, and
 `git checkout` the file if the diff is not explainable as the correction you
-were expecting. Because it mutates the repo, `memmap` belongs behind a GSD
-command (`/gsd-quick`), per this project's GSD Workflow Enforcement rule — it is
-not a read-only lookup like `lookup` and `annotate`.
+were expecting. **`memmap` mutates tracked files** — unlike `lookup` and
+`annotate`, which are read-only — so run it deliberately, on a clean working
+tree, and review the diff before you commit it.
 
 ## Feeding the enum generator
 
@@ -224,7 +224,14 @@ for any other enum.** `anno_create_project_enum` defines the variants and `anno_
 binds one to the accessing instruction's address — see "Name it" and "Document it" below. That is
 manual where `gen-enums` was bulk, but it writes exactly the same rows into the store.
 
-## Classifying every region of an annotation project
+## Reference material for annotating
+
+Two deeper jobs feed the annotate/lookup job above, rather than standing apart from it: knowing
+what a whole region actually is (code, or one of eight kinds of data) before it can be annotated
+at all, and knowing what one of a program's own addresses represents when no published table can
+say. Both exist to serve a documented listing; neither is invoked as a job on its own.
+
+### Classifying every region of an annotation project
 
 Everything above answers *what does this published address mean*. This section
 answers a different question over the same map: **given a loaded binary in an
@@ -243,7 +250,7 @@ entry point and marks it **Code**. Everything else is **Undefined** — not
 "data", just unexplored. The job here is to walk the Undefined regions, work
 out what each one actually is, and set it.
 
-### The one mistake that matters more than the rest
+#### The one mistake that matters more than the rest
 
 **Never disassemble a region without concrete proof that it executes.** Random
 data routinely disassembles into plausible-looking instruction sequences, and
@@ -269,7 +276,7 @@ None of those? Leave it **Undefined**, or classify it as data — even when the
 bytes disassemble cleanly. "It looked like code" is how a sprite sheet becomes
 four hundred lines of fiction.
 
-### The order of the passes
+#### The order of the passes
 
 Work the Undefined blocks in four passes, in this order. Do not interleave
 them; each pass makes the next one cheaper.
@@ -287,7 +294,7 @@ them; each pass makes the next one cheaper.
    **Never** speculatively disassemble in this pass; by definition nothing here
    met the proof bar.
 
-### Scope, and reading a region
+#### Scope, and reading a region
 
 1. `anno_get_binary_info` first. Keep `origin`, `size`, `system`, `filename`,
    `description` and `may_contain_undocumented_opcodes`.
@@ -315,7 +322,7 @@ them; each pass makes the next one cheaper.
    classification; a 4096-byte hexdump is more than can be read carefully in
    one pass.
 
-### Applying the classification
+#### Applying the classification
 
 - **Code**: `anno_disassemble` from the entry-point address to READ, then
   `anno_set_data_type` with `"code"` to RECORD the range you verified.
@@ -357,7 +364,7 @@ then: anno_set_data_type start=2049 end=2303 data_type="code"
 then: anno_get_blocks max_results=500        # refresh
 ```
 
-### The block types
+#### The block types
 
 | Block type | `data_type` | When |
 |---|---|---|
@@ -374,7 +381,7 @@ then: anno_get_blocks max_results=500        # refresh
 | External file | `external_file` | Large blobs to export as-is: SID tunes, bitmaps, charsets |
 | Undefined | `undefined` | Reset to unknown. The honest answer for a region you cannot place |
 
-### Recognising each kind
+#### Recognising each kind
 
 **Byte data** — regular patterns that form no valid instruction sequence;
 addressed by `LDA addr,X` / `LDA addr,Y` table lookups; sprite data in 63-byte
@@ -413,7 +420,7 @@ in multiples of 64, or a bitmap. Export it rather than annotate it.
 it is passed to CHROUT, it is PETSCII. Getting this backwards produces text
 that renders as garbage in exactly one of the two places.
 
-### The adjacent-table limitation, and how it was closed
+#### The adjacent-table limitation, and how it was closed
 
 **Dated limitation, recorded 2026-08-24; CLOSED 2026-08-29 when the store
 changed underneath it.** The old store auto-merged two adjacent regions of the
@@ -440,7 +447,7 @@ So the working rules are now the ordinary ones:
 - **Do not** carry the old over-merge caveat into a report taken from this
   store. It was true of the retired one and is not true here.
 
-### Labelling, and the report
+#### Labelling, and the report
 
 Name what you classified — `anno_set_label_name` on entry points, tables and
 strings — and comment it with `anno_set_comment` (`"line"` above,
@@ -460,7 +467,7 @@ Then report, and mean it:
   own — so quoting the revision is how the report is pinned to an exact store
   state rather than to "after the pass".
 
-### What goes wrong
+#### What goes wrong
 
 | Symptom | What it actually is |
 |---|---|
@@ -471,7 +478,7 @@ Then report, and mean it:
 | Two tables you classified separately show up as one block | The adjacent-table limitation above. Not your error. |
 | Text renders as garbage on screen but fine through CHROUT | It is PETSCII, typed as screencode — or the reverse. |
 
-## What a symbol in the store actually represents
+### What a symbol in the store actually represents
 
 `lookup` at the top of this page answers what a **published** address means —
 a hardware register, a KERNAL entry point, an OS variable. That answer comes
@@ -483,7 +490,7 @@ When `lookup` returns a region-only answer — the dominant case for a game's ow
 code and variables, as noted above — this is the procedure that gets you a
 name.
 
-### 1. Target and context
+#### 1. Target and context
 
 - **Always start from an explicit address**, `$XXXX` or its decimal
   equivalent. There is no editor cursor in this project's route, and upstream's
@@ -497,7 +504,7 @@ name.
   remember that `LAX`, `SAX` and `DCP` have real read/write side effects that
   belong in the data-flow picture.
 
-### 2. Gather the usage
+#### 2. Gather the usage
 
 `anno_get_cross_references` on the address — naming the `store`, the `image` and
 a REQUIRED `max_results` — returns everywhere it is touched. Read the
@@ -519,7 +526,7 @@ order of likelihood:
 3. It is genuinely **dead**: unused variable, or code no longer reached. Say so
    in the report rather than inventing a purpose.
 
-### 3. Place it
+#### 3. Place it
 
 **A hardware register?** `lookup` it. If one of the four tables names it, take
 the published name and the per-bit breakdown with it — that reading rests on
@@ -557,7 +564,7 @@ define one (`0 = INIT`, `1 = TITLE`, `2 = GAMEPLAY`, `3 = GAME_OVER`) with a
 real `description` if none matches, then apply it to every instruction reading
 or writing the variable.
 
-### 4. Name it
+#### 4. Name it
 
 | Symbol kind | Convention | Example |
 |---|---|---|
@@ -578,7 +585,7 @@ or writing the variable.
 
 Apply it with `anno_set_label_name`.
 
-### 5. Document it
+#### 5. Document it
 
 - `anno_set_comment` `"line"` at the definition: the range it occupies, its
   purpose, its bitfield layout if it has one.
@@ -590,15 +597,15 @@ Apply it with `anno_set_label_name`.
 initialised by immediate loads of a target's low and high bytes — `LDA #<target
 / STA ptr / LDA #>target / STA ptr+1` — upstream calls `set_immediate_format`
 twice to turn both immediates into a single readable symbol reference. **That
-call is not exposed on this project's surface.** `BUILD-03` ("every branch,
-`JSR`/`JMP` and data reference goes through a symbol, so code can move") is the
-requirement that supplies its criterion, and the per-call disposition is
+call is not exposed on this project's surface.** The rule it would serve — "every branch,
+`JSR`/`JMP` and data reference goes through a symbol, so code can move" — still
+supplies the criterion, and the per-call disposition is
 recorded in the manifest named in the attribution header above. Until then,
 reconstruct the target by hand and put it in a side comment on both
 instructions — `; low byte of ptr_sprite_table ($C240)` — so the pointer is
 still readable even though the store cannot format it.
 
-### 6. Report
+#### 6. Report
 
 - **Address** and its current label.
 - **Classification**: flag, counter, pointer, hardware register, state

package/skills/c64-memory-mapping/scripts/driver.mjs

@@ -21,7 +21,7 @@ import { dirname, join, resolve } from "node:path";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 // memmap.json lives at the skill root, one level up from scripts/, by decision
-// (D-03): only .mjs modules move into scripts/, data files stay put.
+// only .mjs modules move into scripts/, data files stay put.
 const MEMMAP_JSON = join(HERE, "..", "memmap.json");
 
 // Reference tables, merged into one address -> meaning index. `kind` selects the

package/skills/c64-petcat/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: c64-petcat
+description: Convert a Commodore .prg between PETSCII and ASCII, detokenize a BASIC program into readable text, and read the machine-code handover address out of its startup line, using VICE's own petcat conversion tool as the reference implementation. Use when asked to detokenize a BASIC listing, list what a BASIC stub does, find where a program hands over to machine code, or convert C64 text between PETSCII and ASCII.
+---
+
+# Detokenizing BASIC with petcat
+
+One capability, one script, one binary (`petcat`) reached only through the
+host-tool execution seam:
+
+```bash
+S=src/skills/c64-petcat/scripts/petcat.mjs   # from the repo root
+
+node $S decode --image path/to/program.prg   # detokenize + resolve the SYS handover
+```
+
+The script wraps `petcat` and nothing else. `--image` is required; `--out-dir`
+is optional, defaulting to the image's own directory, exactly like
+`acme-build`'s own `--out-dir` default. Both are resolved
+**workspace-relative** to the smallest ancestor directory containing both,
+before the request ever reaches the seam — the same resolution
+`acme-build`/`c64-disk-access` already go through.
+
+Options: `--image PATH` `--out-dir DIR` `--json`.
+
+## Detokenizing and resolving the handover point
+
+```bash
+node $S decode --image game.prg --json
+```
+
+Prints the seam's response verbatim as one line of JSON:
+
+```json
+{"ok":true,"tool":"petcat.decode","exitStatus":0,"results":[{"path":"/abs/path/game.bas.txt","sha256":"...","byteLength":21}],"stderrTail":"","entrypoint":2064,"entrypointReason":"literal SYS argument on BASIC line 10: sys2064"}
+```
+
+`results[0].path` names the detokenized listing file the seam wrote —
+`petcat`'s own decoded text, captured and digested. The listing itself never
+crosses inline, no matter how short it is.
+
+Two fields carry the handover verdict, and BOTH are present on every
+`ok: true` response:
+
+- **`entrypoint`** — a number when the program's `SYS` argument is a literal
+  decimal value, `null` otherwise.
+- **`entrypointReason`** — always a string. When `entrypoint` is a number, it
+  names the BASIC line the value came from. When `entrypoint` is `null`, it
+  quotes the unresolved expression verbatim, or states that the listing
+  carries no handover instruction at all.
+
+A `null` entrypoint is **not a failure** — it is a resolved "no": the tool
+detokenized the program correctly and correctly concluded the entry point is
+not a static address. Reported this way, never as a guessed address: a
+guessed entry point is expensive downstream, spent on a disassembler that
+then has nothing real to work from.
+
+Non-JSON mode prints the same information as two lines — the resolved entry
+point (or the decline and its reason) and the listing file's path — never the
+listing's contents inline.
+
+## The BASIC dialect
+
+Fixed server-side, not a flag on this script or a field on the wire — this
+project's target is fixed to C64 BASIC V2.0 everywhere already, the same
+posture `acme-build` already takes for its own assembler target.
+
+## Failure shape
+
+A file `petcat` does not recognise as a BASIC program at all — including a
+missing file — is reported as `{"ok":false,"message":"..."}` with a
+non-zero exit code, never a success envelope carrying an empty or guessed
+verdict. `petcat` itself exits `0` even on garbage input; the seam's own
+classifier, not the exit code, is what decides success here.
+
+## What this skill does NOT do
+
+- **No direct binary spawn.** `petcat` runs host-side; this script only ever
+  constructs a typed request and reads the produced listing file back off
+  the shared workspace tree — the host-tool execution seam is the only
+  route.
+- **No guessed entry point.** A computed or otherwise unresolvable `SYS`
+  argument is always reported as a named decline with `entrypoint: null` —
+  never a fallback value, never an inline listing scan for "something that
+  looks like an address".
+- **No emulator dependency.** This skill names no VICE emulator tool at all
+  — it works entirely on files, never on a running machine, by construction.

package/skills/c64-petcat/scripts/petcat.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// petcat -> BASIC detokenization + SYS-handover driver. One capability:
+// decode a BASIC program's stub to readable text and resolve the numeric
+// address it hands over to machine code, when that address is a literal.
+//
+// Reached ONLY through the host-tool execution seam -- the project owner's
+// rule of 2026-08-28 is that this script runs container-side, `petcat` lives
+// host-side, and there is no container PATH to find it on. This file never spawns `petcat` itself; it constructs a
+// TYPED request (`petcat.decode`) and reads the produced listing file back
+// off the shared workspace tree, mirroring
+// src/skills/c64-disk-access/scripts/c1541.mjs's own invokeSeam() shape
+// verbatim.
+//
+// WHAT NOT TO DO:
+//   - Never spawn the conversion binary (`petcat`) directly from this
+//     script, even as a "just this once" fallback. A direct call works on
+//     the developer's own host and silently fails inside a container -- the
+//     exact failure this seam exists to remove.
+//   - Never guess an entry point when the seam reports a null one. A
+//     guessed address is spent on a disassembler downstream, and a wrong
+//     one is expensive there -- report the decline and its reason exactly
+//     as the seam gave them, never a fallback value.
+import { dirname, relative, isAbsolute, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+import { resolveMcpModule, refusalMessage } from "../../c64-ram-capture/scripts/mcp-module.mjs";
+
+const SELF = fileURLToPath(import.meta.url);
+const HERE = dirname(SELF);
+
+/** The MCP-side module this script reaches -- never imported statically
+ * (cross-package: this file ships in `@henols/c64-re-tools`, the seam client
+ * ships in `@henols/vice-mcp`), only located via the ladder and invoked with
+ * `process.execPath`, the interpreter already running this script, on an
+ * in-tree module -- not an external host binary. */
+const HOST_TOOL_CLIENT_FILE = "host-tool-client.ts";
+
+/**
+ * Invokes the host-tool execution seam for `tool`/`args`, rooted at
+ * `repoRoot` for THIS invocation's workspace-relative path resolution.
+ * Never rejects: a resolution failure, a spawn failure, or unparseable
+ * output all resolve to `{ ok: false, message }` -- the same shape a tool's
+ * own refusal uses, so a caller never needs a try/catch. Copied verbatim
+ * from acme.mjs's own invokeSeam() -- see this file's own header for why a
+ * shared import is not possible across the two npm packages.
+ */
+function invokeSeam(tool, args, repoRoot) {
+  return new Promise((resolvePromise) => {
+    const resolved = resolveMcpModule(HOST_TOOL_CLIENT_FILE);
+    if (!resolved.ok) {
+      resolvePromise({ ok: false, message: refusalMessage(HOST_TOOL_CLIENT_FILE, resolved.rungs) });
+      return;
+    }
+
+    const cliArgs = [resolved.path, "run", "--tool", tool, "--args", JSON.stringify(args), "--repo-root", repoRoot];
+    let child;
+    try {
+      child = spawn(process.execPath, cliArgs, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (e) {
+      resolvePromise({ ok: false, message: e instanceof Error ? e.message : String(e) });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk.toString("utf8"); });
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
+    child.on("error", (err) => resolvePromise({ ok: false, message: err.message }));
+    child.on("close", () => {
+      const lines = stdout.split("\n").filter((line) => line.trim() !== "");
+      const last = lines[lines.length - 1];
+      if (last === undefined) {
+        resolvePromise({ ok: false, message: `host-tool-client.ts produced no output${stderr ? ` (stderr: ${stderr})` : ""}` });
+        return;
+      }
+      try {
+        resolvePromise(JSON.parse(last));
+      } catch {
+        resolvePromise({ ok: false, message: `host-tool-client.ts produced non-JSON output: ${last}` });
+      }
+    });
+  });
+}
+
+/** The smallest common ancestor directory of two absolute paths -- computed,
+ * never a fixed guess, so the request's `--repo-root` for THIS invocation is
+ * always exactly big enough to contain both the image and the output
+ * directory, and no bigger. Copied verbatim from acme.mjs's own
+ * commonAncestorDir() -- see this file's own header for why a shared import
+ * is not possible. */
+function commonAncestorDir(a, b) {
+  const partsA = resolve(a).split(sep);
+  const partsB = resolve(b).split(sep);
+  const common = [];
+  for (let i = 0; i < Math.min(partsA.length, partsB.length); i++) {
+    if (partsA[i] === partsB[i]) common.push(partsA[i]);
+    else break;
+  }
+  const joined = common.join(sep);
+  return joined === "" ? sep : joined;
+}
+
+/** `path.relative()`, except the "same directory" case yields `"."` rather
+ * than `""` -- the seam's `resolveWorkspacePath()` refuses an empty string,
+ * but accepts `"."` as a no-op relative reference to its own root. */
+function toRel(root, abs) {
+  const r = relative(root, abs);
+  return r === "" ? "." : r;
+}
+
+// How to refer to this script in hints, from wherever we were run.
+function selfPath() {
+  const r = relative(process.cwd(), SELF);
+  return !r || r.startsWith("..") || isAbsolute(r) ? SELF : r;
+}
+
+const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+
+// ------------------------------------------------------------- capabilities
+
+/**
+ * Detokenizes `--image` (required) to readable BASIC text and resolves its
+ * `SYS` handover point, when it has one. `--out-dir` is optional, defaulting
+ * to the seam's own dirname(image) default exactly as acme.build's own
+ * outDir default does. Prints the seam's response verbatim as one line of
+ * JSON when `--json` is given -- the response IS the reportable shape
+ * (`{ ok, tool, exitStatus, results, stderrTail, entrypoint,
+ * entrypointReason }` / `{ ok: false, message }`), so no reshaping happens
+ * here.
+ */
+async function runDecode(argv) {
+  const o = parseOpts(argv);
+  if (!o.image) die(`usage: decode --image <path.prg> [--out-dir <dir>] [--json]`);
+
+  const imageAbs = resolve(o.image);
+  const outDirAbs = o.outDir ? resolve(o.outDir) : dirname(imageAbs);
+
+  // Workspace-relative request construction (mirrors acme.mjs's own build()):
+  // the root for THIS invocation is the smallest ancestor containing both
+  // the image and the output directory.
+  const repoRoot = commonAncestorDir(dirname(imageAbs), outDirAbs);
+  const args = { image: toRel(repoRoot, imageAbs) };
+  if (o.outDir) args.outDir = toRel(repoRoot, outDirAbs);
+
+  const response = await invokeSeam("petcat.decode", args, repoRoot);
+  report(response, o);
+  process.exit(response.ok ? 0 : 1);
+}
+
+function report(response, { json }) {
+  if (json) {
+    console.log(JSON.stringify(response));
+    return;
+  }
+  if (!response.ok) {
+    console.error(`petcat call FAILED: ${response.message}`);
+    return;
+  }
+  // WHAT NOT TO DO (this file's own header): never guess an entry point --
+  // print exactly what the seam reported, decline included.
+  if (response.entrypoint !== null) {
+    console.log(`entry point: ${response.entrypoint} (${response.entrypointReason})`);
+  } else {
+    console.log(`entry point not resolved: ${response.entrypointReason}`);
+  }
+  for (const r of response.results ?? []) {
+    console.log(`${r.path}  (${r.byteLength} bytes, sha256 ${r.sha256})`);
+  }
+}
+
+// ------------------------------------------------------------------ options
+
+// Exported so petcat.test.mjs can cover this file's
+// own CLI-option parsing as a pure unit, mirroring c1541.mjs's own exported
+// parsers -- never spawns anything, never needs petcat installed.
+export function parseOpts(argv) {
+  const o = { json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") o.json = true;
+    else if (a === "--image") o.image = argv[++i];
+    else if (a === "--out-dir") o.outDir = argv[++i];
+  }
+  return o;
+}
+
+// --------------------------------------------------------------------- main
+//
+// The CLI dispatch below MUST be guarded to run only
+// when this file is the actual entry point, not merely imported -- mirrors
+// c1541.mjs's own entry-point guard verbatim (the "Rule 3
+// fix, discovered mid-execution"), added there after an unguarded dispatch
+// ran with the TEST RUNNER's own process.argv on every import of
+// c1541.test.mjs, printing the usage banner and calling process.exit(0)
+// before a single test() call ever registered. Nothing imports petcat.mjs as
+// a module today (confirmed by grep across src/ and scripts/), so this was
+// latent rather than live here -- but the next petcat.test.mjs that imports
+// a pure helper from this file would reintroduce the exact bug c1541.mjs
+// already found and fixed once. Same shape
+// (`resolve(process.argv[1]) === fileURLToPath(import.meta.url)`), never a
+// second guard shape invented for this sibling script.
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const VERBS = {
+    decode: (argv) => runDecode(argv),
+  };
+  if (!cmd || !VERBS[cmd]) {
+    console.log(`usage: node ${selfPath()} <command> [options]
+
+  decode --image <path.prg> [--out-dir <dir>] [--json]   detokenize a BASIC program and resolve its SYS handover point
+
+Never invokes petcat directly and never guesses an entry point -- a computed
+SYS argument is reported as a named decline, never an address.
+
+options: --image PATH  --out-dir DIR  --json`);
+    process.exit(cmd ? 1 : 0);
+  }
+  await VERBS[cmd](rest);
+}