@henols/c64-re-tools 0.1.4

package/README.md

@@ -0,0 +1,61 @@
+# @henols/c64-re-tools
+
+One-command installer that adds the **C64 reverse-engineering skills** and the
+**VICE emulator MCP server** ([`@henols/vice-mcp`](https://www.npmjs.com/package/@henols/vice-mcp))
+to a project, so an MCP client such as Claude Code can drive a Commodore 64
+emulator for reverse-engineering work.
+
+## Usage
+
+From the project you want to set up:
+
+```sh
+npx @henols/c64-re-tools
+```
+
+That will:
+
+1. Copy the bundled skills into `<project>/.claude/skills/`
+2. Add a `vice` server to `<project>/.mcp.json` (existing servers are preserved),
+   launched via `npx -y @henols/vice-mcp`
+
+Then restart Claude Code in that project.
+
+### Options
+
+| Option | Effect |
+| --- | --- |
+| `[targetDir]` | Install into this directory instead of the current one. |
+| `--force` | Overwrite existing skills and an existing `vice` MCP entry. |
+| `--vendor` | Also `npm install -D @henols/vice-mcp` 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 help. |
+
+Re-running is safe: existing skills and an existing `vice` entry are kept unless
+you pass `--force`.
+
+## What gets installed
+
+- **Skills** — `acme-build`, `c64-memory-mapping`, `c64-program-recon`,
+  `c64-provenance-diff`, `c64-ram-capture`, `vice-wedge-triage`.
+- **MCP server** — `@henols/vice-mcp`, exposing the `vice` tools.
+
+## Requirements
+
+- **This installer** runs on Node ≥ 18.
+- **The VICE MCP server** it wires up requires **Node ≥ 22.18** (or ≥ 23.6), 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.
+
+## Alternative: Claude Code plugin
+
+If you use Claude Code, you can instead install everything as a plugin:
+
+```
+/plugin marketplace add henols/c64-re-tools
+/plugin install c64-re-tools@c64-re-tools
+```
+
+## License
+
+MIT © Henrik Olsson

package/bin/cli.mjs

@@ -0,0 +1,226 @@
+#!/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";
+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");
+
+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";
+// Wire the project to the exact vice-mcp version this installer was built against.
+const MCP_VERSION =
+  (SELF.dependencies && typeof SELF.dependencies[MCP_PKG] === "string"
+    ? SELF.dependencies[MCP_PKG].replace(/^[\^~]/, "")
+    : SELF_VERSION);
+
+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 >= 22.18 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 >= 22.18 (or >= 23.6).");
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@henols/c64-re-tools",
+  "version": "0.1.4",
+  "description": "Installer that adds the C64 reverse-engineering skills and the VICE emulator MCP server (@henols/vice-mcp) to a project.",
+  "type": "module",
+  "bin": {
+    "c64-re-tools": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Henrik Olsson",
+    "url": "https://github.com/henols"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/henols/c64-re-tools.git",
+    "directory": "installer"
+  },
+  "homepage": "https://github.com/henols/c64-re-tools#readme",
+  "bugs": {
+    "url": "https://github.com/henols/c64-re-tools/issues"
+  },
+  "keywords": [
+    "c64",
+    "commodore-64",
+    "vice",
+    "6502",
+    "6510",
+    "acme",
+    "reverse-engineering",
+    "mcp",
+    "claude",
+    "installer"
+  ],
+  "dependencies": {
+    "@henols/vice-mcp": "0.1.4"
+  },
+  "scripts": {
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "prepack": "node scripts/sync-skills.mjs"
+  }
+}

package/skills/acme-build/SKILL.md

@@ -0,0 +1,224 @@
+---
+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.
+---
+
+# Assembling C64 source with ACME
+
+Source in, `.prg` out. Everything goes through one script:
+
+```bash
+A=.claude/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 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.
+
+Options: `-o FILE` `--out-dir DIR` `-f FORMAT` `--setpc ADDR` `-DSYM=VAL`
+`-I DIR` `--no-report` `--json`.
+
+## Build
+
+```bash
+node $A build game.asm
+```
+```
+  Saving 53 (0x35) bytes (0x801 - 0x836 exclusive).
+built game.prg (55 bytes)  load $0801-$0836  53 bytes of code
+symbols: game.sym (4 used / 121 total)
+debug labels: game.vs (4 addresses)
+```
+
+The indented line is ACME's own `-v1` note, passed straight through. Three side
+files land next to the `.prg`, and `--no-report` drops the `.rep`:
+
+| file | contents |
+|---|---|
+| `.prg` | the program, with its load address |
+| `.sym` | every symbol, with the used ones marked |
+| `.vs` | address labels, ready for a debugger or monitor |
+| `.rep` | each source line with the address and bytes it produced |
+
+Only address-typed *and* referenced symbols survive into the `.vs` — raw
+`--vicelabels` output lists constants too, and a debugger reading
+`viccolor_WHITE = $1` would relabel the 6510 processor port at `$0001`
+(`curateLabels`, `scripts/acme.mjs`) — hence 4 addresses against 121 total
+symbols above. Load it with `mcp__plugin_c64-re-tools_vice__vice_symbols_load` (format `vice`), this
+project's only route to the emulator (`.claude/CLAUDE.md` § Version Compatibility
+/ § Emulator Access).
+
+Re-run `build` until it exits 0 — a clean exit means every symbol resolved.
+
+Add `--json` to act on diagnostics programmatically:
+
+```bash
+node $A build game.asm --json
+```
+```json
+{ "ok": false,
+  "diags": [ { "file": "game.asm", "line": 26, "severity": "error",
+               "zone": "Zone <untitled>",
+               "message": "Number does not fit in 8 bits." } ] }
+```
+
+Use the `.rep` listing to map source to memory:
+
+```
+    16  0801 0b080a00                   !word .eol, 10          ; link to next line, line number
+    26  080d a900                       lda #viccolor_BLACK
+    27  080f 8d21d0                     sta vic_cbg             ; $d021 background
+    29  0814 8d20d0                     sta vic_cborder         ; $d020 border
+```
+
+Build variants with `-D`, giving each its own `-o` so the symbol files stay
+separate:
+
+```bash
+node $A build game.asm -DBORDER=2 -o v2.prg    # -> v2.prg v2.sym v2.vs
+node $A build game.asm -DBORDER=5 -o v5.prg    # -> v5.prg v5.sym v5.vs
+```
+
+Inspect the result with `od`:
+
+```bash
+od -An -tx1 game.prg | head -2
+```
+
+The first two bytes are the little-endian load address (`01 08` = `$0801`); code
+follows.
+
+## Writing source
+
+Start from the scaffold — it carries a BASIC stub whose `SYS` target is computed,
+so the entry point stays correct as the program grows:
+
+```bash
+node $A new game.asm
+```
+
+Use the C64 symbol library instead of writing addresses by hand:
+
+| `!source <...>` | gives you | example |
+|---|---|---|
+| `<cbm/c64/vic.a>` | `vic_*` registers, `viccolor_*` constants | `vic_cborder` = `$d020` |
+| `<cbm/c64/kernal.a>` | `k_*` KERNAL entry points `$ff81`–`$fff5` | `k_chrout` = `$ffd2` |
+| `<cbm/c64/cia1.a>` / `<cbm/c64/cia2.a>` | `cia1_*` / `cia2_*` | keyboard, joystick, timers |
+| `<cbm/c64/sid.a>` | `sid_*` | sound |
+
+KERNAL routines use the **`k_`** prefix — `k_chrout`, `k_getin`, `k_setnam`,
+`k_plot`. Several have aliases (`k_bsout` and `k_basout` are also `$ffd2`).
+Run `node $A sym game.asm` to see what a build resolved:
+
+```
+addr    $80d  entry
+addr   $ffd2  k_chrout
+addr   $d021  vic_cbg
+addr   $d020  vic_cborder
+```
+
+Let `-o` name the output and leave `!to` out of the source, so the filename you
+pass is the filename you get.
+
+The 6510's illegal opcodes are always available: `lax dcp sax slo rla sre rra
+isc anc alr arr sbx las tas sha shx shy jam`. Verified — `lax $fb / dcp $fc /
+sax $fd / slo $02 / anc #$0f / sbx #$10` assembles to
+`a7 fb c7 fc 87 fd 07 02 0b 0f cb 10`. Keep `!cpu 6510` at the top of any source
+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):
+
+```bash
+node $A disasm game.prg game.dis.asm
+```
+
+`game.dis.asm` itself then holds:
+
+```
+		*=$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
+```
+
+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.
+
+## 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.
+
+Copy `acme.mjs` into any project's `.claude/skills/acme-build/scripts/`, and
+`template.a` into `.claude/skills/acme-build/`, to use this elsewhere.
+
+## Which skill does what
+
+This one turns source into bytes. It does not restate what the others carry.
+
+| Need | Go to |
+|---|---|
+| 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 |
+
+## 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` |
+
+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
+the new evidence, never by editing a grade in place. File-changing work enters
+through a GSD command (`/gsd-quick`).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `install the ACME cross assembler and put acme on PATH` | Install ACME. |
+| `for <...> includes, set $ACME to …` | `export ACME=<dir holding cbm/c64/vic.a>`. |
+| `Value not defined (kernal_chrout)` | Use the `k_` prefix — `k_chrout`. `node $A sym` lists what resolved. |
+| `Label name not in leftmost column` + `Syntax error` on a mnemonic | Add `!cpu 6510`. |
+| `Output file already chosen` | Remove `!to` from the source and keep `-o`. |
+| `Number does not fit in 8 bits` | Pass a value 0–255, or drop the `#` if you meant an address. |
+| `This tool cannot read binary files. The file appears to be a binary .a file.` | The file is fine — ACME source is plain text; the agent's Read tool refuses the `.a` extension regardless of content, and Edit needs a prior successful Read. Scaffold and write source as `.asm` instead — the driver accepts `.a`/`.asm`/`.s`, all three assemble byte-identically (verified both directions in this container, 2026-08-04). To read an existing `.a` file, use `sed -n '1,60p' file.a`. |