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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henrik Olsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,61 +1,162 @@
-# @henols/c64-re-tools
+# 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.
+An agent-friendly Commodore 64 engineering toolkit for reverse engineering
+unknown applications and for developing, debugging, building and testing new
+C64 applications.
 
-## Usage
+An agent drives a real VICE emulator through an MCP server, and uses skills
+for the rest: disk images, BASIC, static analysis with DXA and Ghidra, a project
+knowledge database, the ACME assembler, unpacking, release comparison and
+functional-equivalence tests.
 
-From the project you want to set up:
+Architecture in one line: one MCP process owns one VICE instance and is
+VICE-only; a Host Runtime on the graphical host owns VICE and the tools that
+come with it (c1541, petcat); skill scripts call the Host Runtime for those,
+run ACME, DXA and Ghidra themselves, and keep project knowledge local in
+`.c64-re-tools/knowledge.db`.
+The design is in [`docs/redesign/`](docs/redesign/README.md), and
+[`docs/plan.md`](docs/plan.md) tracks the implementation.
 
-```sh
-npx @henols/c64-re-tools
+## Install
+
+You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files. ACME, DXA and Ghidra are needed only for the skills that use them.
+
+Start the Host Runtime and leave it running:
+
+```
+npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
+```
+
+Install into your project and start the agent:
+
+```
+cd my-c64-project
+npx -y @henols/c64-re-tools@latest install --target claude
+claude
 ```
 
-That will:
+`npx -y @henols/c64-re-tools@latest status` shows what works.
 
-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`
+Until 2.0.0 is released, `@latest` is the old 1.1.0. Use the prerelease instead. For the prerelease, a dev container and debugging, see [docs/debug-install.md](docs/debug-install.md).
 
-Then restart Claude Code in that project.
+### Settings
+
+| Variable | Read by | Meaning |
+| --- | --- | --- |
+| `C64RT_VICE` | host | Full path of `x64sc` when it is not on `PATH`. |
+| `C64RT_C1541`, `C64RT_PETCAT` | host | Full path of the tool when it is not on `PATH`. |
+| `C64RT_ACME`, `C64RT_DXA` | skills, CLI | Full path of the tool when it is not on `PATH`. |
+| `C64RT_GHIDRA` | skills, CLI | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
+| `C64RT_HOST` | MCP, skills, CLI | `host:port` of the Host Runtime when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at 6464. |
+| `C64RT_VIDEO` | MCP | `pal` (default) or `ntsc`, fixed for the life of the MCP process. |
+| `C64RT_TRACE` | host, MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debug-install.md](docs/debug-install.md). Nothing of the trace reaches the agent. |
+
+Ghidra runs with its own settings directory for each request. The toolkit
+brings its own NMOS 6510 language (all 256 opcodes); your Ghidra installation
+and settings stay unchanged.
+
+## Use it with an agent
+
+## Use it with an agent
+
+1. Install for your harness: `--target claude`, `codex`, `pi`, `opencode`, `gemini`, `copilot`, `cursor` or `windsurf`. Without `--target`, `install` installs for all of them.
+2. Start the Host Runtime and leave it running.
+3. Start the harness in the project, for example `claude` or `codex`, or open the project in Cursor or Windsurf. The harness starts the MCP server and finds the skills by itself.
+4. Ask for the result you want, in plain words. The agent picks the skills and the `c64_*` tools.
+
+Examples:
+
+```
+Reverse engineer original/game.d64. Find how it starts, unpack it if it is packed,
+and name the main routines in project knowledge.
 
-### Options
+Find the routine that draws the score, and explain how it works.
 
-| Option | Effect |
+Write a program in ACME that scrolls a text at the bottom of the screen.
+Build it, run it in the emulator, and write a test for it.
+
+Show me the emulator window.
+```
+
+The agent keeps what it learns about the program in `.c64-re-tools/knowledge.db`. Commit that file with the project.
+
+## Skills
+
+| Skill | Use |
 | --- | --- |
-| `[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. |
+| c64-reverse-engineering | Coordinates an investigation and picks the specialist for the next unknown. |
+| c64-emulator | Runs and observes the program in VICE through the MCP tools. |
+| c64-static-analysis | A fast first pass with DXA and a deeper pass with Ghidra into knowledge, with seeds from knowledge and decompilation. |
+| c64-knowledge | Reads and writes symbols, regions, comments and references, with history. |
+| c64-disk | Directory, BAM, entries, sector chains and extraction of disk images. |
+| c64-basic | BASIC V2 listings and the SYS/USR handoff to machine code. |
+| c64-unpacker | Packing evidence, and capture of the unpacked program from the emulator. |
+| c64-memory-map | Platform meaning of addresses and register values. |
+| c64-provenance | Byte comparison of releases. |
+| c64-assembler | ACME builds with diagnostics and symbols. |
+| c64-testing | Original-against-rebuild scenarios with PASS, FAIL or INCONCLUSIVE. |
+
+## Examples
+
+Reverse engineering, from an unknown disk to a verified rebuild (the commands
+that the skills run for the agent; `<skills>` is the installed skills
+directory):
+
+```
+node <skills>/c64-disk/scripts/disk.ts directory original/game.d64
+node <skills>/c64-disk/scripts/disk.ts read original/game.d64 GAME --out extracted/game.prg
+node <skills>/c64-basic/scripts/basic.ts extracted/game.prg                  # the SYS address, e.g. $080d
+node <skills>/c64-unpacker/scripts/unpack.ts inspect extracted/game.prg
+node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --analyzer dxa --listing analysis/game.lst
+node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --entry '$080d'
+node <skills>/c64-knowledge/scripts/knowledge.ts rename '$080d' main --kind routine --reason 'entry from BASIC'
+node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --entry '$080d' --decompile '$080d'
+node <skills>/c64-assembler/scripts/assemble.ts --source-root src --entry game.a --out build/game.prg > build/game.json
+node <skills>/c64-testing/scripts/test.ts tests/counts.json                   # PASS, FAIL or INCONCLUSIVE
+```
 
-Re-running is safe: existing skills and an existing `vice` entry are kept unless
-you pass `--force`.
+Development: build with the c64-assembler skill, then load and debug with the
+MCP tools (`c64_program_load`, `c64_breakpoint`, `c64_run_until`,
+`c64_memory_read`, `c64_screen`), and test with the c64-testing skill.
 
-## What gets installed
+## Developing
 
-- **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.
+To work on the toolkit itself, Node 24 or newer and pnpm are required; install pnpm yourself (for example
+`corepack enable pnpm`). `packageManager` in `package.json` pins its version.
 
-## Requirements
+```
+pnpm install --frozen-lockfile
+pnpm typecheck     # tsc checks everything; it emits nothing
+pnpm test          # node --test on src/**/*.test.ts and test/**/*.test.ts
+```
+
+Unit tests sit beside their source as `src/**/*.test.ts`; `test/` holds
+integration and end-to-end tests. Node runs the TypeScript directly (type
+stripping), so relative imports name the `.ts` file. Skill scripts import
+`src/` as `#src/...` (the `imports` map in `package.json`); an installed skill
+gets the `src/` modules it reaches and its own `package.json` with that map.
+
+Tests that need real tools are opt-in. Without them they are reported as
+skipped, never as passed:
+
+```
+C64RT_LIVE_VICE=/usr/bin/x64sc C64RT_GHIDRA=/opt/ghidra pnpm test
+```
 
-- **This installer** runs on Node ≥ 18.
-- **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.
+ACME, DXA, c1541 and petcat tests run when the tools are on `PATH`.
 
-## Alternative: Claude Code plugin
+To release, push a tag. See [docs/releasing.md](docs/releasing.md).
 
-If you use Claude Code, you can instead install everything as a plugin:
+## Layout
 
 ```
-/plugin marketplace add henols/c64-re-tools
-/plugin install c64-re-tools@c64-re-tools
+src/             # mcp, host, host-client, native, knowledge, cli; unit tests beside the source
+skills/          # the skills: SKILL.md, scripts (TypeScript) and references
+distribution/    # the AP SDK plugin definition: skills with the src/ modules they reach
+test/            # fixtures, integration and end-to-end tests
+docs/redesign/   # the design
 ```
 
 ## License
 
-MIT © Henrik Olsson
+MIT. See [`LICENSE`](./LICENSE).

package/distribution/package.ts

@@ -0,0 +1,36 @@
+// The npm package and the VICE MCP declaration that starts it. This module
+// only reads package.json, so a caller that needs the declaration does not
+// build the plugin.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The npm dist-tag that a version is published under: a prerelease
+ * (2.0.0-rc.1) goes to "next", a release to "latest".
+ */
+export function channelOf(version: string): "latest" | "next" {
+  return version.includes("-") ? "next" : "latest";
+}
+
+/** The name, version and dist-tag of this npm package, from its package.json. */
+export const PACKAGE = (() => {
+  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
+  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
+})();
+
+/**
+ * The agent starts the MCP server through npx with the newest version of the
+ * channel it was installed from, so it updates itself and an install from a
+ * prerelease does not start a release; nothing is linked or installed globally.
+ * The entry point is TypeScript, run by tsx: Node does not strip types under
+ * node_modules.
+ */
+export function mcpServerFor(platform: NodeJS.Platform): { command: string; args: string[] } {
+  const npx = ["-y", `--package=${PACKAGE.name}@${PACKAGE.tag}`, "c64-re-tools-mcp"];
+  // On native Windows npx is a .cmd shim, which a harness starts only through cmd /c.
+  return platform === "win32" ? { command: "cmd", args: ["/c", "npx", ...npx] } : { command: "npx", args: npx };
+}
+
+/** The declaration for the machine where install runs: the plugin is evaluated there. */
+export const MCP_SERVER = mcpServerFor(process.platform);

package/distribution/plugin.ts

@@ -0,0 +1,120 @@
+// The portable c64-re-tools plugin for @jalco/ap-sdk: the skills
+// with their TypeScript scripts, the src/ modules those scripts reach, their
+// references, and the VICE MCP declaration. AP SDK maps it to each harness's
+// native layout; nothing at run time depends on it.
+//
+// Nothing is built: an installed skill holds the same .ts files as this
+// repository, and Node runs them by type stripping. Skill scripts import
+// src/ through the "#src/*" subpath import; each installed skill gets a
+// package.json that maps it to its own copy of those modules.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { definePlugin, defineSkill, type Skill } from "@jalco/ap-sdk";
+
+import { MCP_SERVER, PACKAGE } from "./package.ts";
+
+const root = resolve(import.meta.dirname, "..");
+const SOURCE = join(root, "src");
+const SCRIPT_REFERENCE = /scripts\/([a-z][a-z0-9-]*)\.ts/g;
+/**
+ * The modules a file reaches: static and dynamic imports, re-exports, and
+ * new URL("...", import.meta.url) for a module that is spawned or an asset
+ * directory. Only relative and #src specifiers; packages are node: built-ins.
+ */
+const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\bnew URL\(\s*)(["'])((?:\.\.?\/|#src\/)[^"']*)\1/g;
+
+/**
+ * The package.json of an installed skill: ES modules, #src/* resolved inside
+ * the skill, and the version of c64-re-tools that the copy comes from.
+ */
+export const SKILL_PACKAGE = `${JSON.stringify({ type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
+
+/** The scripts that a SKILL.md runs, by file name. */
+export function scriptsOf(skillMarkdown: string): string[] {
+  return [...new Set([...skillMarkdown.matchAll(SCRIPT_REFERENCE)].map((match) => match[1]!))].sort();
+}
+
+function filesBelow(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { recursive: true, encoding: "utf8" })
+    .map((path) => join(directory, path))
+    .filter((path) => statSync(path).isFile())
+    .sort();
+}
+
+const inside = (directory: string, path: string) => path === directory || path.startsWith(directory + sep);
+
+/**
+ * Every file that the given scripts reach, transitively: the scripts, their
+ * sibling modules, and the src/ modules and asset directories below them.
+ * A reach out of the skill directory and src/ is an error.
+ */
+export function closureOf(skillDirectory: string, scripts: readonly string[]): string[] {
+  const found = new Set<string>();
+  const pending = [...scripts];
+  while (pending.length > 0) {
+    const file = pending.pop()!;
+    if (found.has(file)) continue;
+    if (!inside(SOURCE, file) && !inside(skillDirectory, file)) throw new Error(`${relative(root, file)} is outside the skill and src/`);
+    if (!existsSync(file)) throw new Error(`${relative(root, file)} does not exist`);
+    if (statSync(file).isDirectory()) {
+      pending.push(...filesBelow(file));
+      continue;
+    }
+    found.add(file);
+    if (!file.endsWith(".ts")) continue;
+    for (const match of readFileSync(file, "utf8").matchAll(SPECIFIER)) {
+      const specifier = match[2]!;
+      pending.push(specifier.startsWith("#src/") ? join(SOURCE, specifier.slice("#src/".length)) : resolve(dirname(file), specifier));
+    }
+  }
+  return [...found].sort();
+}
+
+/** One skill: SKILL.md frontmatter and body, scripts (executable), the src/ modules they reach, and references. */
+function loadSkill(directory: string): Skill {
+  const text = readFileSync(join(directory, "SKILL.md"), "utf8");
+  const frontmatter = /^---\n([\s\S]*?)\n---\n/.exec(text);
+  if (frontmatter === null) throw new Error(`${directory}/SKILL.md has no frontmatter`);
+  const field = (name: string) => {
+    const value = new RegExp(`^${name}: (.+)$`, "m").exec(frontmatter[1]!)?.[1];
+    if (value === undefined) throw new Error(`${directory}/SKILL.md has no ${name}`);
+    return value;
+  };
+  const scripts = scriptsOf(text).map((script) => join(directory, "scripts", `${script}.ts`));
+  const code = closureOf(directory, scripts).map((path) => ({
+    path: (inside(SOURCE, path) ? relative(root, path) : relative(directory, path)).split("\\").join("/"),
+    content: readFileSync(path, "utf8"),
+    ...(scripts.includes(path) ? { executable: true } : {}),
+  }));
+  const references = filesBelow(join(directory, "references")).map((path) => ({ path: relative(directory, path).split("\\").join("/"), content: readFileSync(path, "utf8") }));
+  const resources = [...code, ...references, ...(scripts.length > 0 ? [{ path: "package.json", content: SKILL_PACKAGE }] : [])];
+  return defineSkill({
+    name: field("name"),
+    description: field("description"),
+    instructions: text.slice(frontmatter[0].length).replace(/^\n+/, ""),
+    ...(resources.length > 0 ? { resources } : {}),
+  });
+}
+
+function c64Plugin() {
+  const skills = readdirSync(join(root, "skills"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => loadSkill(join(root, "skills", name)));
+  return definePlugin({
+    id: "c64-re-tools",
+    version: PACKAGE.version,
+    description: "Commodore 64 reverse engineering and development: a live VICE emulator, static analysis, disk and BASIC tools, project knowledge, building and testing.",
+    author: { name: "Henrik Olsson" },
+    homepage: "https://github.com/henols/c64-re-tools",
+    license: "MIT",
+    skills,
+    mcpServers: { "c64-re-tools": MCP_SERVER },
+  });
+}
+
+export default c64Plugin();

package/package.json

@@ -1,55 +1,49 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "1.1.0",
-  "description": "Installer that adds the C64 reverse-engineering skills and the VICE emulator MCP server (@henols/vice-mcp) to a project.",
+  "version": "2.0.0-rc.3",
+  "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
+  "license": "MIT",
+  "author": "Henrik Olsson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/henols/c64-re-tools.git"
+  },
   "type": "module",
+  "packageManager": "pnpm@12.9.1+sha512.06b055fff5cd20dc12781de173ced3310ce0951bf2ec620211a16045d5444d5c93a663210764ef29a653a610459ba0368f0e74f84d80c54723cf95aae7bc0d6d",
+  "imports": {
+    "#src/*": "./src/*"
+  },
   "bin": {
-    "c64-re-tools": "bin/cli.mjs"
+    "c64-re-tools": "src/cli/main.ts",
+    "c64-re-tools-mcp": "src/mcp/main.ts",
+    "c64-re-tools-host": "src/host/main.ts"
   },
   "files": [
-    "bin/",
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*.testkit.ts",
     "skills/",
-    "README.md",
-    "THIRD-PARTY-NOTICES.md"
+    "distribution/package.ts",
+    "distribution/plugin.ts",
+    "LICENSE",
+    "README.md"
   ],
   "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "author": {
-    "name": "Henrik Olsson",
-    "url": "https://github.com/henols"
+    "node": ">=24.0.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/henols/c64-re-tools.git",
-    "directory": "installer"
+  "scripts": {
+    "host": "node src/host/main.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\" \"test/**/*.test.ts\""
   },
-  "homepage": "https://github.com/henols/c64-re-tools#readme",
-  "bugs": {
-    "url": "https://github.com/henols/c64-re-tools/issues"
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
   },
-  "keywords": [
-    "c64",
-    "commodore-64",
-    "vice",
-    "6502",
-    "6510",
-    "acme",
-    "reverse-engineering",
-    "mcp",
-    "claude",
-    "installer"
-  ],
   "dependencies": {
-    "@henols/vice-mcp": "1.1.0"
-  },
-  "scripts": {
-    "sync-skills": "node scripts/sync-skills.mjs",
-    "prepack": "node scripts/sync-skills.mjs",
-    "test": "node --test '*.test.mjs'"
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "zod": "4.6.5",
+    "@jalco/ap-sdk": "0.4.1",
+    "tsx": "4.23.15"
   }
 }

package/skills/c64-assembler/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: c64-assembler
+description: Use this skill to assemble C64 6510 source code with the ACME assembler and write the program (PRG) into the project. It reports source errors with file and line, and the symbols with their addresses or values. Use it to build a rebuilt or new program. Do not use it to run the program. Give the PRG to the c64-emulator skill for that.
+---
+
+# c64-assembler
+
+## Purpose
+
+Assemble C64 source code with ACME. Write the program into the project. Report diagnostics and symbols.
+
+This skill does not run the program and does not change project knowledge.
+
+## Inputs
+
+- The source root: the project directory that holds all source files of the program.
+- The entry source: the main file, relative to the source root.
+- The output path: where to write the PRG, relative to the project directory.
+- Optional include directories, symbol definitions and a start address.
+
+## Tools / execution path
+
+The script runs ACME on this machine. It copies the source root to a temporary directory, assembles it there and writes the program into the project. The host runtime is not necessary.
+
+```
+node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/game.prg
+```
+
+| Option | Meaning |
+|---|---|
+| `--include lib` | An include directory, relative to the source root. Use it again for more directories. |
+| `--define DEBUG=1` | An assembler symbol: an integer, also as `$` hex, or `true` or `false`. Use it again for more symbols. |
+| `--set-pc '$0801'` | The start address when the source does not set one. |
+
+The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
+
+The script prints one JSON object. The target CPU is the 6510 and the output is always a C64 PRG.
+
+## Workflow
+
+1. Find the source root and the entry source. The entry source sets its own start address with `* = $0801` or similar.
+2. Run the script.
+3. If `assembled` is `true`, the PRG is at `output`. `loadRange` tells where it loads. `symbols` gives each symbol as an `address` or a `value`.
+4. If `assembled` is `false`, read `diagnostics`. Each one has a severity, a file, a line and a message. Correct the source and run the script again.
+5. To run the program, give the PRG path to the c64-emulator skill.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not store:
+- diagnostics
+- build output
+
+A symbol from the rebuilt source can give the address of a routine in the rebuild. Use it to compare runs with the c64-testing skill.
+
+## Result
+
+The PRG in the project at the output path, with its load range and symbols. Or the source diagnostics when the assembly failed.
+
+The exit status is 0 for a PRG. The exit status is 1 for `assembled: false` and for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `assembled: false`: the source has errors. This is a normal result. Correct the source.
+- `installation-incomplete`: ACME is not installed on this machine. Tell the user the message.
+- `invalid-input`: an option or a path is wrong. Read the message and correct the call.
+
+## Handoffs
+
+- Run or debug the program → c64-emulator
+- Compare the rebuild with the original → c64-testing

package/skills/c64-assembler/scripts/assemble.ts

@@ -0,0 +1,103 @@
+// The c64-assembler script: assembles project source with ACME, which it runs
+// itself, and writes the program into the project.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { readProjectTree } from "#src/host-client/transfer.ts";
+import { assemble } from "#src/native/acme.ts";
+import { localToolContext } from "#src/native/local.ts";
+import type { AcmeParams } from "#src/native/types.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+
+const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [options]
+
+  --source-root <dir>      project directory to assemble from; all of it is sent
+  --entry <file>           the main source file, relative to the source root
+  --out <file.prg>         where to write the program, relative to the project
+  --include <dir>          include directory relative to the source root (repeatable)
+  --define NAME=VALUE      assembler symbol: an integer ($hex allowed) or true/false (repeatable)
+  --set-pc <address>       start address when the source sets none, for example '$0801'
+
+The result is one JSON object. Addresses are $ and four hex digits.`;
+
+function parseDefine(text: string): [string, number | boolean] {
+  const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.+)$/.exec(text);
+  if (match === null) throw new UsageError(`--define needs NAME=VALUE, not ${text}`);
+  const value = match[2]!;
+  if (value === "true" || value === "false") return [match[1]!, value === "true"];
+  if (/^\$[0-9a-fA-F]+$/.test(value)) return [match[1]!, Number.parseInt(value.slice(1), 16)];
+  if (/^-?\d+$/.test(value)) return [match[1]!, Number(value)];
+  throw new UsageError(`--define ${match[1]} needs an integer or true/false, not ${value}`);
+}
+
+async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    options: {
+      "source-root": { type: "string" },
+      entry: { type: "string" },
+      out: { type: "string" },
+      include: { type: "string", multiple: true },
+      define: { type: "string", multiple: true },
+      "set-pc": { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help) throw new UsageError("");
+  const sourceRoot = values["source-root"];
+  const entry = values.entry;
+  const out = values.out;
+  if (sourceRoot === undefined || entry === undefined || out === undefined) throw new UsageError("--source-root, --entry and --out are necessary");
+  let outPath: string;
+  try {
+    outPath = resolveProjectPath(out);
+  } catch {
+    throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${out}`);
+  }
+  const defines = Object.fromEntries((values.define ?? []).map(parseDefine));
+  let setPc: number | undefined;
+  if (values["set-pc"] !== undefined) {
+    try {
+      setPc = parseC64Address(values["set-pc"]);
+    } catch {
+      throw new UsageError(`--set-pc must be $ followed by four hex digits, not ${values["set-pc"]}`);
+    }
+  }
+  const tree = readProjectTree(sourceRoot);
+  if (!tree.files.some((file) => file.path === entry)) throw new UsageError(`--entry ${entry} is not a file in ${sourceRoot}`);
+  const params: AcmeParams = { files: tree.files, entrySource: entry, includeDirs: values.include ?? [], defines, ...(setPc === undefined ? {} : { setPc }) };
+
+  const { result, attachments } = await assemble(params, tree.contents, localToolContext());
+  if (!result.assembled) return { output: { assembled: false, diagnostics: result.diagnostics }, failed: true };
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, attachments![0]!);
+  const range = result.loadRange!;
+  return {
+    output: {
+      assembled: true,
+      output: out,
+      loadRange: { start: formatC64Address(range.start), end: formatC64Address(range.end), bytes: range.bytes },
+      symbols: result.symbols!.map((symbol) =>
+        symbol.kind === "address"
+          ? { name: symbol.name, kind: "address", address: formatC64Address(symbol.address), used: symbol.used }
+          : { name: symbol.name, kind: "constant", value: symbol.value, used: symbol.used },
+      ),
+      diagnostics: result.diagnostics,
+    },
+    failed: false,
+  };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);