@henols/c64-re-tools 0.2.0 → 0.2.2

package/README.md

@@ -43,7 +43,7 @@ you pass `--force`.
 ## Requirements
 
 - **This installer** runs on Node ≥ 18.
-- **The VICE MCP server** it wires up requires **Node ≥ 22.18** (or ≥ 23.6), and a
+- **The VICE MCP server** it wires up requires **Node ≥ 24**, and a
   host with VICE (`x64sc`) reachable from the MCP client. See the
   [`@henols/vice-mcp`](https://www.npmjs.com/package/@henols/vice-mcp) readme.
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,26 @@
+# 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

@@ -13,6 +13,9 @@
 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,
@@ -27,11 +30,11 @@ const PKG_ROOT = dirname(HERE);
 const SKILLS_SRC = join(PKG_ROOT, "skills");
 
 // The single version-resolution seam this repo maintains is
-// `.claude/mcp/vice/version.ts` (quick-260819-tsz, D-5). This package
+// `src/mcp/vice/version.ts` (quick-260819-tsz, D-5). 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 >= 22.18 runtime can. What follows is exactly the seam'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/`-`
@@ -45,11 +48,11 @@ 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 (R-2, quick-260819-tsz). Defined authoritatively as
-// `DEV_PLACEHOLDER` in `.claude/mcp/vice/version.ts` -- repeated here as a
+// `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 >= 22.18 runtime can. This is the same disclosed divergence as
+// 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";
@@ -124,7 +127,7 @@ 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 >= 22.18 to RUN the vice MCP server (this installer runs on Node >= 18).`;
+Requires Node >= 24 to RUN the vice MCP server (this installer runs on Node >= 18).`;
 
 function viceServerEntry(vendor) {
   return {
@@ -262,8 +265,16 @@ function main() {
     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 >= 22.18 (or >= 23.6).");
+    console.error("Note: running the vice MCP server requires Node >= 24.");
   }
 }
 
-main();
+// 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Installer that adds the C64 reverse-engineering skills and the VICE emulator MCP server (@henols/vice-mcp) to a project.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin/",
     "skills/",
-    "README.md"
+    "README.md",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
     "node": ">=18"
@@ -44,10 +45,11 @@
     "installer"
   ],
   "dependencies": {
-    "@henols/vice-mcp": "0.2.0"
+    "@henols/vice-mcp": "0.2.2"
   },
   "scripts": {
     "sync-skills": "node scripts/sync-skills.mjs",
-    "prepack": "node scripts/sync-skills.mjs"
+    "prepack": "node scripts/sync-skills.mjs",
+    "test": "node --test '*.test.mjs'"
   }
 }

package/skills/acme-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acme-build
-description: Assemble Commodore 64 6510 assembly with the ACME cross assembler. Use when asked to assemble, build, compile or link .a/.asm 6502/6510 source, produce a C64 .prg, scaffold a new C64 program, list the symbols a program uses, or turn a .prg back into ACME source.
+description: Assemble Commodore 64 6510 assembly with the ACME cross assembler. Use when asked to assemble, build, compile or link .a/.asm 6502/6510 source, produce a C64 .prg, scaffold a new C64 program, or list which symbols an assembled build actually used from its symbol file.
 ---
 
 # Assembling C64 source with ACME
@@ -8,15 +8,14 @@ description: Assemble Commodore 64 6510 assembly with the ACME cross assembler.
 Source in, `.prg` out. Everything goes through one script:
 
 ```bash
-A=.claude/skills/acme-build/scripts/acme.mjs   # from the repo root
+A=src/skills/acme-build/scripts/acme.mjs   # from the repo root
 
 node $A new game.asm          # scaffold a C64 program
 node $A build game.asm        # assemble -> .prg .sym .vs .rep
 node $A sym game.asm          # the symbols the program uses
-node $A disasm game.prg       # object code back into ACME source
 ```
 
-The script wraps `acme` and `toacme` and nothing else — **assembling only**. Running
+The script wraps `acme` and nothing else — **assembling only**. Running
 the result on a C64 belongs to the emulator skills (`acme.mjs:3-4` says so, and the
 absent `run` verb is not an omission). It contacts nothing.
 
@@ -133,60 +132,80 @@ you also assemble by hand, so these stay recognised as mnemonics.
 
 ## Disassembly
 
-```bash
-node $A disasm game.prg
-```
-```
-game.dis.a: 28 lines
-Read it as a linear decode: trust the instruction stream, and
-treat strings, tables and the BASIC stub as data. To reassemble,
-define the out-of-range labels it emits (Ld020, Lffd2, ...) and
-indent its illegal-opcode lines to the operand column.
-```
-
-The default output is `<stem>.dis.a` — one more `.a` file the agent's Read tool
-refuses (see Troubleshooting). Pass a second positional ending `.asm` for an
-agent-readable listing instead (same stdout shape, `game.dis.asm: 28 lines` in
-place of the first line):
+This skill does not disassemble. The route that does is `anno export-asm`, and
+it lives in the `anno` CLI rather than here.
+
+**Dated withdrawal 2026-08-29, dated return 2026-08-31 — both halves are kept,
+because the withdrawal is the record of why the route is shaped the way it is.**
+Whole-program static disassembly was WITHDRAWN on 2026-08-29 (`D-02`/`D-14`)
+rather than left standing on an unverified reassembly claim: the removed route
+settled correctness with a transcript parser, and the recorded false pass that
+discipline exists against read `ACME not found in PATH (skipped)` / `All
+roundtrip verifications passed.` / `EXIT=0` — exit zero, an aggregate line
+reading as a full pass, and the one assembler this project cares about never
+having run. On **2026-08-31 the route returned**, rebuilt over the annotation
+store as `anno export-asm`. It is not a rename of what was removed: its
+correctness is settled by **assembling the output with a real ACME and diffing
+the bytes against the input** — never by an exit code, and never by a string
+match on the exporter's own output.
+
+**The live invocation:**
 
 ```bash
-node $A disasm game.prg game.dis.asm
+npx -y @henols/vice-mcp anno export-asm game.prg --store game.annostore --out game.a
+node <plugin-root>/src/mcp/vice/vice-proxy.ts anno export-asm game.prg --store game.annostore
 ```
 
-`game.dis.asm` itself then holds:
+`<image>` and `--store` are **two separate arguments and neither is derived from
+the other** — the image supplies the bytes, the store supplies the names, ranges,
+typed regions and comments, and naming one does not name the other. `--out`
+defaults to a `.a` beside the **store**, not beside the image, because the export
+is a generated view of the annotations. An existing destination is refused rather
+than overwritten unless you pass `--force`.
+
+**The verb writes source text and runs no assembler.** Its own second output line
+says so, in as many words:
 
 ```
-		*=$0801
-L0801		!by$0b;ANC#      <- BASIC stub, read as data
-L0802		php
-L0805		 SHX L3032, y
-...
-L080d		lda #$00         <- code, decoded correctly
-L080f		sta Ld021
-L0812		lda #$05
-L0814		sta Ld020
-L081e		jsr Lffd2
-L0824		rts
-L0825		pha              <- PETSCII string, read as data
+export-asm: this file has NOT been assembled -- this command writes source text and runs no assembler.
 ```
 
-Read it as a linear decode: the instruction stream is accurate, and strings,
-tables and the BASIC stub appear as instructions — interpret those regions as
-data. To reassemble the listing, define the out-of-range labels it emits
-(`Ld020`, `Lffd2`) and indent its illegal-opcode lines to the operand column.
+The real-ACME byte-diff oracle is **test-only** — it lives in
+`src/mcp/vice/acme-verify.ts`, is exercised by `acme-verify.test.ts` (hard-failed
+in CI with `VICE_REQUIRE_ACME=1`), and is deliberately absent from the published
+package, so nothing on the runtime path can reach it. A clean `export-asm` run is
+therefore evidence that source was written and nothing more; it is not an
+assembler verdict. If you need to know the emitted source reassembles, assemble
+it yourself — that is what this skill's own build route is for.
+
+**Reading one range at a time is still the right move for a single routine.**
+`anno_read_region` and `anno_disassemble` render an explicit inclusive range out
+of the image on demand, capped at 4096 bytes per call and REFUSED by name above
+the cap rather than truncated. `c64-program-recon` documents that route and this
+history together; it is not restated there.
 
 ## Setup
 
-Put `acme` and `toacme` on `$PATH`. The wrapper auto-probes `$ACME`,
-`/usr/local/share/acme`, `/usr/share/acme`, `/usr/lib/acme` and `~/.acme` itself,
-so `$ACME` only needs setting by hand when calling `acme` directly. Verified live
-in this container on 2026-08-04: the library resolves to `/usr/local/share/acme`
-(`/usr/share/acme` doesn't exist), ACME release 0.97 "Zem" (31 Jan 2021) at
-`/usr/bin/acme`. **Confidence: HIGH** — read off `acme --version` and the probe
-result, not off a package manifest.
+`acme` on `$PATH` is the **only** requirement. The scaffold that `new` writes
+assembles against a bare install with no standard hardware-register library —
+that's deliberate: neither a plain `~/.local/bin/acme` build nor the Debian
+trixie `apt` candidate ships one, so a scaffold that depended on it would fail
+to assemble on a fresh install (Phase 8.1 FINDING-A1).
+
+`$ACME` and the wrapper's auto-probe (`$ACME`, `/usr/local/share/acme`,
+`/usr/share/acme`, `/usr/lib/acme`, `~/.acme`) still exist and still matter —
+but only for **your own** sources that use angle-bracket includes (see
+"Writing source" above), not for the scaffold. If you have that library
+somewhere, point `$ACME` at its directory and angle-bracket includes work as
+before; if you don't, the scaffold doesn't need it.
+
+Re-checked against ACME release 0.97 "Zem" (31 Jan 2021). CI now assembles
+the shipped scaffold on every build with `$ACME` cleared (the "Assemble the
+acme-build scaffold (library-free)" step in `.github/workflows/ci.yml`), so
+this claim is re-checkable rather than a one-machine observation.
 
 Copy `acme.mjs` into any project's `.claude/skills/acme-build/scripts/`, and
-`template.a` into `.claude/skills/acme-build/`, to use this elsewhere.
+`template.a` into `.claude/skills/acme-build/`, to use this elsewhere (the path Claude Code auto-discovers and `installSkills()` deploys to).
 
 ## Which skill does what
 
@@ -197,14 +216,15 @@ This one turns source into bytes. It does not restate what the others carry.
 | Where to start on an unknown program, and which address to read next | `c64-program-recon` |
 | What a specific address or bit means, or annotating a listing | `c64-memory-mapping` — `node … lookup '$D018'` |
 | A verified 64K image, or comparing two captures | `c64-ram-capture` |
-| **Source in, `.prg` out — and a first-pass dead listing back** | here |
+| Static disassembly of a `.prg` or flat image | **`anno export-asm`** — withdrawn 2026-08-29, returned 2026-08-31 behind a real-ACME byte-diff oracle that is test-only, so the verb writes source and assembles nothing (see Disassembly above) |
+| **Source in, `.prg` out** | here |
 
 ## References
 
 | File | Covers |
 |---|---|
 | `scripts/acme.mjs` | The driver. Its comments are the contract for every flag above |
-| `template.a` | The scaffold `new` writes: BASIC stub with a computed `SYS`, the three `!source` libraries, no `!to` |
+| `template.a` | The scaffold `new` writes: BASIC stub with a computed `SYS`, five local hardware constants (no library needed), no `!to` |
 
 Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you
 find them**, graded with `Evidence:` and `Confidence:`. Promote by re-logging with

package/skills/acme-build/scripts/acme.mjs

@@ -205,22 +205,6 @@ function cmdNew(argv) {
   console.log(`next: node ${selfPath()} build ${path}`);
 }
 
-// `toacme` ships with ACME and turns object code back into ACME source.
-function cmdDisasm(argv) {
-  const src = argv[0];
-  if (!src) die("usage: disasm <file.prg> [out.a]");
-  const out = argv[1] || src.replace(/\.prg$/i, "") + ".dis.a";
-  const r = spawnSync("toacme", ["object", src, out], { encoding: "utf8" });
-  if (r.error) die("install the ACME cross assembler and put `toacme` on PATH");
-  if (r.status !== 0) die(`toacme: ${(r.stderr || r.stdout).trim()}`);
-  const n = readFileSync(out, "utf8").split("\n").filter((l) => /^L[0-9a-f]{4}/.test(l)).length;
-  console.log(`${out}: ${n} lines`);
-  console.log("Read it as a linear decode: trust the instruction stream, and");
-  console.log("treat strings, tables and the BASIC stub as data. To reassemble,");
-  console.log("define the out-of-range labels it emits (Ld020, Lffd2, ...) and");
-  console.log("indent its illegal-opcode lines to the operand column.");
-}
-
 // ------------------------------------------------------------------ options
 
 function parseOpts(argv) {
@@ -247,14 +231,13 @@ function parseOpts(argv) {
 // --------------------------------------------------------------------- main
 
 const [cmd, ...rest] = process.argv.slice(2);
-const VERBS = { new: cmdNew, build: cmdBuild, sym: cmdSym, disasm: cmdDisasm };
+const VERBS = { new: cmdNew, build: cmdBuild, sym: cmdSym };
 if (!cmd || !VERBS[cmd]) {
   console.log(`usage: node ${selfPath()} <command> [options]
 
-  new <file.a>              scaffold a C64 program (BASIC stub + libs)
+  new <file.a>              scaffold a C64 program (BASIC stub, no libraries needed)
   build <file.a>            assemble -> .prg .sym .vs .rep
   sym <file.a>              list the symbols the program uses
-  disasm <file.prg> [out.a] turn object code back into ACME source
 
 options: -o FILE  --out-dir DIR  -f FORMAT  --setpc ADDR  -DSYM=VAL  -I DIR
          --no-report  --json`);

package/skills/acme-build/template.a

@@ -2,11 +2,25 @@
 ; Build:  node .claude/skills/acme-build/scripts/acme.mjs build THIS.a
 ; No !to here on purpose - the driver passes -o, and having both makes ACME
 ; warn "Output file already chosen" and silently ignore the !to.
+;
+; No angle-bracket library includes here on purpose. Neither documented ACME
+; provisioning route ships the standard hardware-register library - a bare
+; `~/.local/bin/acme` install and the Debian trixie `apt` candidate were both
+; verified to lack it (Phase 8.1 FINDING-A1) - so a scaffold that depends on
+; it fails to assemble on a fresh install. The five constants below are
+; exactly what this scaffold's body uses, defined locally instead. If you
+; want the full library for your own sources' angle-bracket includes, set
+; $ACME to a directory containing that library (with vic.a inside it);
+; acme.mjs's findAcmeLib() already probes for it and passes it through to
+; the child.
 
 !cpu 6510                       ; C64's CPU: legal 6502 + the illegal opcodes
-!source <cbm/c64/vic.a>         ; vic_*  registers, viccolor_* constants
-!source <cbm/c64/kernal.a>      ; k_*    KERNAL entry points ($ff81-$fff5)
-!source <cbm/c64/cia1.a>        ; cia1_* keyboard / joystick 2
+
+!address vic_cborder = $d020    ; VIC-II border color register
+!address vic_cbg     = $d021    ; VIC-II background color register
+viccolor_BLACK = 0
+viccolor_GREEN = 5
+!address k_chrout    = $ffd2    ; KERNAL: print one PETSCII char
 
 * = $0801                       ; start of BASIC RAM