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

package/skills/acme-build/SKILL.md

@@ -1,260 +0,0 @@
----
-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, or list which symbols an assembled build actually used from its symbol file.
----
-
-# Assembling C64 source with ACME
-
-Source in, `.prg` out. Everything goes through one script:
-
-```bash
-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
-```
-
-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.
-
-Options: `-o FILE` `--out-dir DIR` `-f FORMAT` `--setpc ADDR` `-DSYM=VAL`
-`-I DIR` `--no-report` `--json`.
-
-The seam resolves `-I DIR` **workspace-relative** to the project root the host
-broker starts with — the same resolution `source`/`--out-dir` already
-go through — before it ever reaches the assembler. The seam refuses an absolute
-or escaping `-I` directory rather than passing it to ACME. This is a
-documented contract change from earlier releases, when an absolute include
-reached the assembler unchecked.
-
-## 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 that computes its `SYS` target
-rather than hard-coding it, 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
-
-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 — this document keeps
-both halves, because the withdrawal records why the route has its current shape.**
-Whole-program static disassembly was WITHDRAWN on 2026-08-29 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 the removed route: its
-correctness comes from **assembling the output with a real ACME and diffing
-the bytes against the input** — never from an exit code, and never from a string
-match on the exporter's own output.
-
-**The live invocation:**
-
-```bash
-npx -y @henols/vice-mcp anno export-asm game.prg --store game.annostore --out game-src
-node <plugin-root>/src/mcp/vice/vice-proxy.ts anno export-asm game.prg --store game.annostore
-```
-
-`<image>` and `--store` are **two separate arguments, and neither one derives 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` names
-a **directory**: the verb writes the whole export into it, defaulting to the image's
-basename stem beside the **store**, not beside the image, because the export is a
-generated view of the annotations. The directory holds a root file that sources
-the rest, one file per annotation scope, and an `unscoped.a` for anything inside
-no scope. The verb refuses a non-empty destination rather than overwriting it, unless you
-pass `--force`.
-
-**The verb writes source text and runs no assembler.** Its own second output line
-says so, in as many words:
-
-```
-export-asm: this file has NOT been assembled -- this command writes source text and runs no assembler.
-```
-
-The real-ACME byte-diff oracle is **test-only** — it lives in
-`src/mcp/vice/acme-verify.ts`, `acme-verify.test.ts` exercises it (hard-failed
-in CI with `VICE_REQUIRE_ACME=1`), and it stays deliberately absent from the published
-package, so nothing on the runtime path can reach it. A clean `export-asm` run is
-therefore evidence that the verb wrote source 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
-
-`acme` on `$PATH` — **on the host**, never inside a container — 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.
-
-**Route:** `scripts/acme.mjs` never spawns `acme` itself
-and never probes a container PATH for it — a container has no such PATH to
-probe (the project owner's rule of 2026-08-28). The script reaches the
-assembler only through the host-tool execution seam
-(`src/mcp/vice/host-tool.mts`'s `acme.build` allowlist entry), which runs on
-the HOST and probes the library there — the same handful of conventional
-install locations `acme.mts`'s own `findAcmeLib()` names, none of them
-documented a second time here. `$ACME` still matters for **your own** sources
-that use angle-bracket includes (see "Writing source" above), not for the
-scaffold — but set it in the environment the **host** broker process sees, not
-this script's own environment, since the probe now runs host-side inside the
-seam's executor. If you don't have that library, 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 (the path Claude Code auto-discovers and `installSkills()` deploys to).
-
-## 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` |
-| 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`, five local hardware constants (no library needed), no `!to` |
-
-Record findings that make RE faster in your own project notes **at the moment you
-find them**, graded with `Evidence:` and `Confidence:`. Promote a finding by
-re-logging it with the new evidence, never by editing an old grade in place — the
-grade is only worth anything if it says what you actually knew when you wrote it.
-
-## Troubleshooting
-
-| Symptom | Correct |
-|---|---|
-| `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. 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`. |

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

@@ -1,341 +0,0 @@
-#!/usr/bin/env node
-// ACME -> C64 assembler driver.  Target is fixed: C64, 6510 CPU, cbm output.
-// Scope is assembling only: source in, .prg + symbol files out.  Running the
-// result on a C64 belongs to the emulator skill.
-//
-// The assembler is reached ONLY through the host-tool execution seam -- the
-// project owner's rule of 2026-08-28 is that this script runs container-side,
-// `acme` lives host-side, and there is no container PATH to find it on. This file used to spawn `acme` directly (a synchronous
-// `spawnSync("acme", args, { env })`) and probed FOUR fixed HOST paths
-// (`/usr/local/share/acme`, `/usr/share/acme`, `/usr/lib/acme`, `~/.acme`)
-// for its `<...>`-include library -- both are exactly what the owner's rule
-// says cannot work from inside a container. The spawn and the library probe
-// both moved to `src/mcp/vice/host-tool.mts`'s `acme.build` allowlist entry;
-// this file now only constructs a TYPED request and reads the produced files
-// back off the shared workspace tree.
-//
-// WHAT NOT TO DO: never reintroduce a local child-process call to the
-// assembler as a fallback when the seam is unreachable -- a fallback that
-// works on the developer's own host and silently fails inside a container is
-// the exact failure this seam exists to remove. A seam refusal is reported
-// and the build fails; it is never retried by spawning `acme` here.
-import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
-import { dirname, join, basename, 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.
- */
-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 source and the output
- * directory, and no bigger. This is what keeps a build entirely outside this
- * project's own tree (this repo's `skill-acme-build-cli.test.ts`'s own
- * scratch directories under the SYSTEM temp dir, and CI's own
- * `RUNNER_TEMP`-rooted scaffold check) working after the migration: the
- * seam's `resolveWorkspacePath()` refuses any path outside its given root, so
- * the root for one invocation is chosen to be wherever that invocation's own
- * files actually live, never a client-supplied absolute path sent as-is. */
-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); };
-
-// ------------------------------------------------------------------- build
-
-// ACME's --msvc format:  file(line) : Error (Zone <z>): message.
-const MSVC = /^(.*?)\((\d+)\)\s*:\s*(Error|Warning|Serious error)\s*(?:\(([^)]*)\))?\s*:\s*(.*)$/;
-
-function parseDiagnostics(text) {
-  const out = [];
-  for (const line of text.split("\n")) {
-    const m = line.match(MSVC);
-    if (m) {
-      out.push({
-        file: m[1], line: Number(m[2]),
-        severity: m[3].toLowerCase().replace(" ", "_"),
-        zone: m[4] || null, message: m[5].trim(),
-      });
-    } else if (line.trim()) {
-      out.push({ file: null, line: null, severity: "note", zone: null, message: line.trim() });
-    }
-  }
-  return out;
-}
-
-// The symbol list marks address-typed symbols with a leading "!addr" and
-// never-referenced ones with a trailing "; unused".  Both matter downstream.
-function parseSymbols(path) {
-  if (!existsSync(path)) return [];
-  return readFileSync(path, "utf8").split("\n").flatMap((raw) => {
-    const m = raw.match(/^(!addr\s+)?(\S+)\s*=\s*(\S+?)\s*(?:;\s*(.*))?$/);
-    if (!m) return [];
-    return [{
-      name: m[2], value: m[3],
-      isAddress: Boolean(m[1]),
-      used: !/^unused/.test(m[4] || ""),
-    }];
-  });
-}
-
-// ACME's label file lists every global symbol, constants included, in address
-// form.  A debugger reads `viccolor_WHITE = $1` as a name for address $0001 and
-// relabels the 6510 processor port with it.  Keep referenced addresses only, so
-// the emitted file is safe to load anywhere.
-function curateLabels(vsPath, symbols) {
-  if (!existsSync(vsPath)) return { kept: 0, dropped: 0 };
-  const addr = new Set(symbols.filter((s) => s.isAddress && s.used).map((s) => s.name));
-  const kept = [];
-  let dropped = 0;
-  for (const l of readFileSync(vsPath, "utf8").split("\n")) {
-    const m = l.match(/^al\s+C:[0-9a-f]+\s+\.(\S+)/i);
-    if (!m) continue;
-    if (addr.has(m[1])) kept.push(l); else dropped++;
-  }
-  writeFileSync(vsPath, kept.join("\n") + (kept.length ? "\n" : ""));
-  return { kept: kept.length, dropped };
-}
-
-async function build(src, opts) {
-  if (!existsSync(src)) die(`no such source file: ${src}`);
-
-  const srcAbs = resolve(src);
-  // Side files follow the .prg, not the source: two -DVARIANT builds of one
-  // source must not overwrite each other's symbol tables.
-  const desiredPrg = opts.out
-    ? resolve(opts.out)
-    : join(resolve(opts.outDir || dirname(src)), basename(src).replace(/\.(a|asm|s)$/i, "") + ".prg");
-  const desiredOutDirAbs = dirname(desiredPrg);
-  if (!existsSync(desiredOutDirAbs)) mkdirSync(desiredOutDirAbs, { recursive: true });
-  const desiredStem = desiredPrg.replace(/\.prg$/i, "");
-
-  // Workspace-relative request construction (A-03): the root for THIS
-  // invocation is the smallest ancestor containing both the source and the
-  // output directory -- see commonAncestorDir()'s own header.
-  const repoRoot = commonAncestorDir(dirname(srcAbs), desiredOutDirAbs);
-  const autoOutDirAbs = dirname(srcAbs); // the executor's own default when outDir is omitted
-
-  const args = { source: toRel(repoRoot, srcAbs) };
-  if (desiredOutDirAbs !== autoOutDirAbs) args.outDir = toRel(repoRoot, desiredOutDirAbs);
-  if (opts.format) args.format = opts.format;
-  if (opts.setpc) args.setpc = opts.setpc;
-  if (opts.defines && opts.defines.length) args.defines = opts.defines;
-  if (opts.includes && opts.includes.length) args.includes = opts.includes;
-  if (opts.noReport) args.noReport = true;
-
-  const response = await invokeSeam("acme.build", args, repoRoot);
-
-  if (!response.ok) {
-    // A seam-level refusal (unresolvable seam, unreachable broker, a bad
-    // request) -- never a local fallback that spawns the assembler itself.
-    die(response.message);
-  }
-
-  // The executor always names outputs after the SOURCE's own basename (never
-  // a caller-chosen stem) -- see host-tool.mts's buildHostToolArgv(). When
-  // `-o`/`--out-dir` asked for a DIFFERENT stem (a rename, not just a
-  // different directory), the produced files are moved here to the exact
-  // requested names -- a workspace file operation, not a second copy of
-  // argv construction.
-  const autoStem = join(desiredOutDirAbs, basename(srcAbs).replace(/\.(a|asm|s)$/i, ""));
-  if (autoStem !== desiredStem) {
-    for (const ext of [".prg", ".sym", ".vs", ".rep"]) {
-      const from = `${autoStem}${ext}`;
-      const to = `${desiredStem}${ext}`;
-      if (existsSync(from) && from !== to) {
-        mkdirSync(dirname(to), { recursive: true });
-        renameSync(from, to);
-      }
-    }
-  }
-
-  const stem = desiredStem;
-  const prg = desiredPrg;
-
-  const diags = parseDiagnostics((response.stderrTail || "").trim());
-  const errors = diags.filter((d) => d.severity.endsWith("error"));
-  const ok = response.exitStatus === 0 && existsSync(prg);
-
-  let range = null, size = null, symbols = [], labels = null;
-  if (ok) {
-    symbols = parseSymbols(`${stem}.sym`);
-    labels = curateLabels(`${stem}.vs`, symbols);
-    const buf = readFileSync(prg);
-    size = buf.length;
-    if ((opts.format || "cbm") === "cbm" && buf.length >= 2) {
-      const load = buf[0] | (buf[1] << 8);
-      range = { load, end: load + buf.length - 2, bytes: buf.length - 2 };
-    }
-  }
-  return { ok, prg, stem, diags, errors, symbols, labels, range, size };
-}
-
-const hex = (n, w = 4) => n.toString(16).padStart(w, "0");
-
-function reportBuild(res, { json }) {
-  if (json) { console.log(JSON.stringify(res, null, 2)); return; }
-  for (const d of res.diags) {
-    if (d.file) console.log(`${d.file}:${d.line}: ${d.severity}: ${d.message}`);
-    else console.log(`  ${d.message}`);
-  }
-  if (!res.ok) { console.error(`build FAILED (${res.errors.length} error(s))`); return; }
-  const r = res.range;
-  console.log(
-    `built ${res.prg} (${res.size} bytes)` +
-    (r ? `  load $${hex(r.load)}-$${hex(r.end)}  ${r.bytes} bytes of code` : "")
-  );
-  const used = res.symbols.filter((s) => s.used).length;
-  console.log(`symbols: ${res.stem}.sym (${used} used / ${res.symbols.length} total)`);
-  if (res.labels) {
-    console.log(`debug labels: ${res.stem}.vs (${res.labels.kept} addresses)`);
-  }
-}
-
-// -------------------------------------------------------------------- verbs
-
-async function cmdBuild(argv) {
-  const o = parseOpts(argv);
-  const res = await build(o.src, o);
-  reportBuild(res, o);
-  process.exit(res.ok ? 0 : 1);
-}
-
-async function cmdSym(argv) {
-  const o = parseOpts(argv);
-  const res = await build(o.src, { ...o, noReport: true });
-  if (!res.ok) { reportBuild(res, o); process.exit(1); }
-  const used = res.symbols.filter((s) => s.used).sort((a, b) => a.name.localeCompare(b.name));
-  if (o.json) { console.log(JSON.stringify(used, null, 2)); return; }
-  for (const s of used) console.log(`${s.isAddress ? "addr " : "const"} ${s.value.padStart(6)}  ${s.name}`);
-}
-
-// A skeleton that is correct on the first try: BASIC stub with a computed SYS
-// target, the C64 symbol libraries, and no !to (the CLI supplies -o).
-function cmdNew(argv) {
-  const path = argv[0];
-  if (!path) die("usage: new <file.a>");
-  if (existsSync(path)) die(`${path} already exists`);
-  // template.a lives at the skill root, one level up from scripts/, by
-  // decision: only .mjs modules move into scripts/.
-  writeFileSync(path, readFileSync(join(HERE, "..", "template.a"), "utf8"));
-  console.log(`wrote ${path}`);
-  console.log(`next: node ${selfPath()} build ${path}`);
-}
-
-// ------------------------------------------------------------------ options
-
-function parseOpts(argv) {
-  const o = { defines: [], includes: [], json: false };
-  const rest = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--json") o.json = true;
-    else if (a === "--no-report") o.noReport = true;
-    else if (a === "-o" || a === "--out") o.out = argv[++i];
-    else if (a === "--out-dir") o.outDir = argv[++i];
-    else if (a === "-f" || a === "--format") o.format = argv[++i];
-    else if (a === "--setpc") o.setpc = argv[++i];
-    else if (a === "-D") o.defines.push(argv[++i]);
-    else if (a.startsWith("-D")) o.defines.push(a.slice(2));
-    else if (a === "-I") o.includes.push(argv[++i]);
-    else rest.push(a);
-  }
-  o.src = rest[0];
-  if (!o.src) die("no source file given");
-  return o;
-}
-
-// --------------------------------------------------------------------- main
-
-const [cmd, ...rest] = process.argv.slice(2);
-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, no libraries needed)
-  build <file.a>            assemble -> .prg .sym .vs .rep
-  sym <file.a>              list the symbols the program uses
-
-options: -o FILE  --out-dir DIR  -f FORMAT  --setpc ADDR  -DSYM=VAL  -I DIR
-         --no-report  --json`);
-  process.exit(cmd ? 1 : 0);
-}
-await VERBS[cmd](rest);

package/skills/acme-build/template.a

@@ -1,53 +0,0 @@
-; C64 / 6510 program skeleton.
-; 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 - 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
-
-!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
-
-; --- BASIC stub: "10 SYS <entry>", so LOAD"...",8,1 + RUN reaches the code.
-; The SYS digits are computed from `entry`, so inserting code above never
-; breaks the stub - which is the classic way to lose an afternoon.
-        !word .eol, 10          ; link to next line, line number
-        !byte $9e               ; SYS token
-        !byte '0' + entry % 10000 / 1000
-        !byte '0' + entry %  1000 /  100
-        !byte '0' + entry %   100 /   10
-        !byte '0' + entry %    10
-        !byte 0                 ; end of BASIC line
-.eol    !word 0                 ; end of BASIC program
-
-entry
-        lda #viccolor_BLACK
-        sta vic_cbg             ; $d021 background
-        lda #viccolor_GREEN
-        sta vic_cborder         ; $d020 border
-
-        ldx #0
--       lda .msg,x
-        beq +
-        jsr k_chrout            ; $ffd2 print one PETSCII char
-        inx
-        bne -
-+       rts
-
-.msg    !pet "hello from acme", 13, 0