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

package/README.md

@@ -17,73 +17,40 @@ run ACME, DXA and Ghidra themselves, and keep project knowledge local in
 The design is in [`docs/redesign/`](docs/redesign/README.md), and
 [`docs/plan.md`](docs/plan.md) tracks the implementation.
 
-## Install and start
+## Install
 
-Requirements:
+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: [docs/install-tools.md](docs/install-tools.md) has the steps for each system.
 
-- Node.js 24 or newer with npx.
-- On the machine with VICE: VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files.
-- Where the agent runs: ACME, DXA and Ghidra, for the skills that use them.
-
-Everything runs through npx. Nothing is installed globally.
-
-### Release or prerelease
-
-| Channel | Version |
-| --- | --- |
-| `latest` | The current release. |
-| `next` | The current prerelease, for example `2.0.0-rc.1`. |
-
-Until 2.0.0 is released, `latest` is the old 1.1.0. Use `next` until then. In the commands below, replace `<channel>` with `latest` or `next`. Use the same channel on both machines.
-
-### On one machine
-
-Start the Host Runtime in its own terminal. Ctrl+C stops it and every emulator:
+Start the Host Runtime and leave it running:
 
 ```
-npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host
+npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
 ```
 
-Install into the project, check it, and start the agent:
+Install into your project and start the agent:
 
 ```
 cd my-c64-project
-npx -y @henols/c64-re-tools@<channel> install --target claude
-npx -y @henols/c64-re-tools@<channel> status
+npx -y @henols/c64-re-tools@latest install --target claude
 claude
 ```
 
-### In a dev container
-
-On the host, start the Host Runtime on the container bridge with a shared secret:
-
-```
-export C64RT_HOST_TOKEN=$(openssl rand -hex 16)
-npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host --listen 172.17.0.1
-```
-
-In the container, set the same `C64RT_HOST_TOKEN`, then:
+`npx -y @henols/c64-re-tools@latest status` shows what works.
 
-```
-npx -y @henols/c64-re-tools@<channel> install --target claude
-npx -y @henols/c64-re-tools@<channel> status
-claude
-```
+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).
 
-The container reaches the host as `host.docker.internal`. `status` must show the Host Runtime as reachable.
+### Dev container
 
-### Update and remove
+The agent runs in the container, VICE and the Host Runtime on the host. In `.devcontainer/devcontainer.json`:
 
+```json
+"features": {
+  "https://github.com/henols/c64-re-tools/releases/latest/download/devcontainer-feature-c64-re-tools.tgz": { "target": "claude" }
+},
+"runArgs": ["--add-host=host.docker.internal:host-gateway"]
 ```
-npx -y @henols/c64-re-tools@<channel> update      # the newest skills into the project
-npx -y @henols/c64-re-tools@<channel> uninstall
-```
-
-Restart the Host Runtime after a new release. `--global` installs into your home directory.
 
-### Debugging
-
-See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
+The Feature installs ACME, dxa, Java 21 and Ghidra, puts the toolkit into the project when the container is created, and updates it at each start. `target` is a harness or a comma list. `channel` is `latest` (default) or `next`. Debian and Ubuntu images only. `runArgs` is for Docker on Linux. Start the Host Runtime on the host as above.
 
 ### Settings
 
@@ -94,9 +61,8 @@ See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
 | `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_HOST_TOKEN` | host, MCP, skills, CLI | The shared secret for a Host Runtime that listens beyond loopback. |
 | `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/debugging.md](docs/debugging.md). Nothing of the trace reaches the agent. |
+| `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
@@ -138,6 +104,7 @@ The agent keeps what it learns about the program in `.c64-re-tools/knowledge.db`
 | 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-source | ACME source from the image and the knowledge, checked byte by byte, and a loader for the entry state. |
 | c64-assembler | ACME builds with diagnostics and symbols. |
 | c64-testing | Original-against-rebuild scenarios with PASS, FAIL or INCONCLUSIVE. |
 
@@ -190,14 +157,7 @@ C64RT_LIVE_VICE=/usr/bin/x64sc C64RT_GHIDRA=/opt/ghidra pnpm test
 
 ACME, DXA, c1541 and petcat tests run when the tools are on `PATH`.
 
-To release, push a tag on a commit of `main`. The tag gives the version:
-
-```
-git tag v2.0.0-rc.2 && git push origin v2.0.0-rc.2   # a prerelease, to npm next
-git tag v2.0.0      && git push origin v2.0.0        # a release, to npm latest
-```
-
-CI checks and tests the tagged commit, publishes it to npm and makes a GitHub Release. The repository keeps the version `0.0.0-development`.
+To release, push a tag. See [docs/releasing.md](docs/releasing.md).
 
 ## Layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.4",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-assembler/SKILL.md

@@ -31,6 +31,7 @@ node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/ga
 | `--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. |
+| `--compare unpacked/image.json` | Check the program byte by byte against a reference. The reference is the `image.json` of the c64-unpacker skill, a PRG, or 64 KiB of memory. |
 
 The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
 
@@ -59,12 +60,14 @@ A symbol from the rebuilt source can give the address of a routine in the rebuil
 
 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.
+With `--compare`, `compare` gives `identical` and one check for each segment of the reference. A check is `identical`, `different` with the first different address, or `not covered` when the program does not hold the segment.
+
+The exit status is 0 for a PRG. The exit status is 1 for `assembled: false`, for a `--compare` that is not identical, 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.
+- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an option or a path is wrong. Read the message and correct the call.
 
 ## Handoffs

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

@@ -12,6 +12,7 @@ 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";
+import { compareBuild } from "./compare.ts";
 
 const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [options]
 
@@ -21,6 +22,8 @@ const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [
   --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'
+  --compare <file>         check the program byte by byte against an image.json of the
+                           c64-unpacker skill (each segment), a PRG, or 64 KiB of memory
 
 The result is one JSON object. Addresses are $ and four hex digits.`;
 
@@ -45,6 +48,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
       include: { type: "string", multiple: true },
       define: { type: "string", multiple: true },
       "set-pc": { type: "string" },
+      compare: { type: "string" },
       help: { type: "boolean" },
     },
   });
@@ -77,6 +81,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   mkdirSync(dirname(outPath), { recursive: true });
   writeFileSync(outPath, attachments![0]!);
   const range = result.loadRange!;
+  const compared = values.compare === undefined ? undefined : compareBuild(attachments![0]!, values.compare);
   return {
     output: {
       assembled: true,
@@ -88,8 +93,10 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
           : { name: symbol.name, kind: "constant", value: symbol.value, used: symbol.used },
       ),
       diagnostics: result.diagnostics,
+      ...(compared === undefined ? {} : { compare: compared }),
     },
-    failed: false,
+    // A build that differs from its reference is a failed check.
+    failed: compared !== undefined && !compared.identical,
   };
 }
 

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

@@ -0,0 +1,84 @@
+// The byte check of a build (D47): the assembled program against the image
+// of the unpacker (image.json with image.bin), a reference PRG, or 64 KiB of
+// memory, segment by segment.
+
+import { posix } from "node:path";
+
+import { formatC64Address, prgRange } from "#src/c64.ts";
+import { readProjectFile } from "#src/host-client/transfer.ts";
+import { UsageError } from "#src/script.ts";
+
+export interface SegmentCheck {
+  start: string;
+  end: string;
+  result: "identical" | "different" | "not covered";
+  /** Bytes of the segment that the build does not hold. */
+  uncovered?: number;
+  differences?: number;
+  firstDifference?: { address: string; built: number; reference: number };
+}
+
+const FULL = 0x10000;
+
+/** The reference as memory and the ranges to check in it. */
+function reference(path: string, built: { start: number; end: number }): { memory: (address: number) => number | undefined; segments: Array<{ start: number; end: number }> } {
+  const { bytes } = readProjectFile(path);
+  if (path.endsWith(".json")) {
+    let manifest: { image?: unknown; segments?: unknown };
+    try {
+      manifest = JSON.parse(bytes.toString("utf8")) as typeof manifest;
+    } catch (error) {
+      throw new UsageError(`--compare ${path} is not JSON: ${(error as Error).message}`);
+    }
+    const segments = manifest.segments;
+    if (typeof manifest.image !== "string" || !Array.isArray(segments) || segments.length === 0) throw new UsageError(`--compare ${path} is not an image.json: it needs image and segments`);
+    const image = readProjectFile(posix.join(posix.dirname(path), manifest.image)).bytes;
+    if (image.length !== FULL) throw new UsageError(`the image of ${path} has ${image.length} bytes, not 65536`);
+    return {
+      memory: (address) => image[address],
+      segments: segments.map((segment: { start?: unknown; end?: unknown }) => {
+        const parse = (value: unknown) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : NaN);
+        const range = { start: parse(segment.start), end: parse(segment.end) };
+        if (!(range.start <= range.end)) throw new UsageError(`--compare ${path}: a segment needs start and end as $ addresses`);
+        return range;
+      }),
+    };
+  }
+  if (bytes.length === FULL && !path.endsWith(".prg")) return { memory: (address) => bytes[address], segments: [built] };
+  let range: ReturnType<typeof prgRange>;
+  try {
+    range = prgRange(bytes);
+  } catch (error) {
+    throw new UsageError(`--compare ${path}: ${(error as Error).message}`);
+  }
+  return { memory: (address) => (address >= range.start && address <= range.end ? range.body[address - range.start] : undefined), segments: [{ start: range.start, end: range.end }] };
+}
+
+/** Compares the assembled PRG with the reference, segment by segment. */
+export function compareBuild(prg: Uint8Array, path: string): { against: string; identical: boolean; segments: SegmentCheck[] } {
+  const built = prgRange(prg);
+  const { memory, segments } = reference(path, built);
+  const checks = segments.map((segment): SegmentCheck => {
+    const from = Math.max(segment.start, built.start);
+    const to = Math.min(segment.end, built.end);
+    const shown = { start: formatC64Address(segment.start), end: formatC64Address(segment.end) };
+    if (from > to) return { ...shown, result: "not covered", uncovered: segment.end - segment.start + 1 };
+    let differences = 0;
+    let first: SegmentCheck["firstDifference"];
+    for (let address = from; address <= to; address++) {
+      const builtByte = built.body[address - built.start]!;
+      const referenceByte = memory(address);
+      if (referenceByte === undefined || builtByte === referenceByte) continue;
+      differences++;
+      first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
+    }
+    const uncovered = segment.end - segment.start + 1 - (to - from + 1);
+    return {
+      ...shown,
+      result: differences > 0 ? "different" : uncovered > 0 ? "not covered" : "identical",
+      ...(uncovered > 0 ? { uncovered } : {}),
+      ...(differences > 0 ? { differences, firstDifference: first! } : {}),
+    };
+  });
+  return { against: path, identical: checks.every((check) => check.result === "identical"), segments: checks };
+}

package/skills/c64-basic/SKILL.md

@@ -56,8 +56,7 @@ The exit status is 0 for a listing. The exit status is 1 for `decoded: false` an
 
 - `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill.
 - An empty `handoffs` list: the BASIC does not start machine code with SYS or USR. Do not make up a handoff. Look for a POKE into a vector or a LOAD of another file in the listing.
-- `installation-incomplete`: petcat is not on the host. Tell the user the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `not-found` or `invalid-input`: the path or an argument is wrong. Read the message and correct the call.
 
 ## Handoffs

package/skills/c64-disk/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: c64-disk
-description: Use this skill to examine a C64 disk image (D64, D71, D81 or G64) and to extract files from it into the project. It shows the directory, the BAM, the directory entry of a file and the sector chain of a file. Do not use it to run a program or to decode BASIC. Give an extracted file to the c64-basic, c64-unpacker or c64-static-analysis skill.
+description: Use this skill to examine a C64 disk image (D64, D71, D81 or G64), a T64 tape file or a CRT cartridge file. It extracts files into the project. It shows the directory, the BAM, the directory entry of a file and the sector chain of a file. It writes each bank of a cartridge as a PRG. Do not use it to run a program or to decode BASIC. Give an extracted file to the c64-basic, c64-unpacker or c64-static-analysis skill.
 ---
 
 # c64-disk
 
 ## Purpose
 
-Examine a C64 disk image. Extract a file from the image into the project.
+Examine a C64 disk image, a T64 tape file or a CRT cartridge file. Extract a file from it into the project.
 
 This skill does not change the disk image and does not change project knowledge.
 
@@ -16,10 +16,11 @@ This skill does not change the disk image and does not change project knowledge.
 - The disk image: a `.d64`, `.d71`, `.d81` or `.g64` file, relative to the project directory.
 - For one file: the file name as the directory shows it.
 - To extract a file: the output path, relative to the project directory.
+- A T64 tape file or a CRT cartridge file, relative to the project directory.
 
 ## Tools / execution path
 
-The script sends the image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project.
+The script sends a disk image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project. It reads T64 and CRT files itself.
 
 ```
 node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
@@ -32,6 +33,10 @@ node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
 | The type, size and first block of one file | `entry original/game.d64 GAME` |
 | The track and sector of each block of one file | `chain original/game.d64 GAME` |
 | Extract one file | `read original/game.d64 GAME --out extracted/game.prg` |
+| The files of a tape | `directory original/game.t64` |
+| Extract one file of a tape | `read original/game.t64 GAME --out extracted/game.prg` |
+| The banks of a cartridge | `directory original/game.crt` |
+| Write each bank of a cartridge as a PRG | `crt original/game.crt --out cart` |
 
 The script prints one JSON object.
 
@@ -55,6 +60,15 @@ Do not store:
 
 A downstream skill records the meaning of the extracted content.
 
+## Tapes and cartridges
+
+The script reads T64 and CRT files itself. The host runtime is not necessary for them.
+
+- T64: `directory` and `read`. Many T64 files have a wrong end address. Then the entry has `fixedSize: true`, and the size comes from the position of the next file.
+- CRT: `directory` and `crt`. The script reads hardware types 0 (normal 8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) and 32 (EasyFlash). It refuses other types by name. `crt` writes `crt.json` and one PRG for each CHIP packet, for example `bank3-8000.prg`.
+- A cartridge bank uses the same addresses as other banks. Analyze each bank PRG with c64-static-analysis and `--space bank3`, and record its knowledge in space `bank3`.
+- TAP: a TAP file holds tape signals, and turbo loaders have their own formats. The script does not read it. Start it with the c64-emulator skill, or capture its parts with `loads` of the c64-unpacker skill.
+
 ## Result
 
 The directory, the BAM, an entry or a sector chain as JSON. Or the extracted file in the project at the output path.
@@ -65,8 +79,7 @@ The exit status is 0 for a result with the file. The exit status is 1 for `found
 
 - `found: false`: the image has no file with that name. This is a normal result. Read the directory again and compare the names.
 - `media-error`: the image has a defect or is not a disk image. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the image.
-- `installation-incomplete`: c1541 is not on the host. Tell the user the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an argument or a path is wrong. Read the message and correct the call.
 
 A file that is not `closed` was not written fully. Its data can be incomplete.
@@ -75,5 +88,6 @@ A file that is not `closed` was not written fully. Its data can be incomplete.
 
 - BASIC program → c64-basic
 - Packed program → c64-unpacker
-- Machine code → c64-static-analysis
+- Machine code, also a cartridge bank → c64-static-analysis
+- A TAP file → c64-unpacker
 - Run the program → c64-emulator

package/skills/c64-disk/scripts/containers.ts

@@ -0,0 +1,124 @@
+// Cartridge and tape containers that c64-disk reads locally (D54): no host
+// tool reads them. A CRT file holds CHIP packets, each a bank of ROM at a
+// load address; a T64 file holds a directory of PRG files. TAP files hold
+// raw pulses and go through the emulator only.
+
+import { formatC64Address, petsciiNameToText } from "#src/c64.ts";
+
+/** A refusal of a container file: the caller turns it into a usage error. */
+export class ContainerError extends Error {}
+
+/** The CRT hardware types this toolkit reads, by type number (D54). */
+export const CRT_TYPES: Record<number, string> = { 0: "normal", 5: "Ocean", 19: "Magic Desk", 32: "EasyFlash" };
+
+export interface CrtChip {
+  bank: number;
+  address: number;
+  size: number;
+  /** 0 ROM, 1 RAM, 2 flash. */
+  chipType: number;
+  data: Uint8Array;
+}
+
+export interface Crt {
+  name: string;
+  type: number;
+  typeName: string;
+  /** The EXROM and GAME lines at start: 0 is active. */
+  exrom: number;
+  game: number;
+  /** For type 0: 8K, 16K or Ultimax by the EXROM and GAME lines. */
+  mode?: "8k" | "16k" | "ultimax";
+  chips: CrtChip[];
+}
+
+const SIGNATURE = "C64 CARTRIDGE   ";
+
+export function parseCrt(bytes: Uint8Array): Crt {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.length < 0x40 || buffer.toString("latin1", 0, 16) !== SIGNATURE) throw new ContainerError("the file is not a CRT: it does not start with C64 CARTRIDGE");
+  const headerLength = buffer.readUInt32BE(0x10);
+  const type = buffer.readUInt16BE(0x16);
+  const exrom = buffer[0x18]!;
+  const game = buffer[0x19]!;
+  const typeName = CRT_TYPES[type];
+  if (typeName === undefined) {
+    throw new ContainerError(`the CRT has hardware type ${type}; this toolkit reads types ${Object.entries(CRT_TYPES).map(([number, name]) => `${number} (${name})`).join(", ")}`);
+  }
+  const name = buffer.toString("latin1", 0x20, 0x40).replace(/\0+$/, "");
+  const chips: CrtChip[] = [];
+  let offset = Math.max(headerLength, 0x40);
+  while (offset + 0x10 <= buffer.length) {
+    if (buffer.toString("latin1", offset, offset + 4) !== "CHIP") throw new ContainerError(`the CRT has no CHIP packet at offset ${offset}`);
+    const packetLength = buffer.readUInt32BE(offset + 4);
+    const chipType = buffer.readUInt16BE(offset + 8);
+    const bank = buffer.readUInt16BE(offset + 10);
+    const address = buffer.readUInt16BE(offset + 12);
+    const size = buffer.readUInt16BE(offset + 14);
+    if (packetLength < 0x10 || offset + packetLength > buffer.length) throw new ContainerError(`the CHIP packet at offset ${offset} runs past the end of the file`);
+    if (bank > 255) throw new ContainerError(`the CHIP packet at offset ${offset} has bank ${bank}; banks go up to 255`);
+    if (size > packetLength - 0x10 || address + size > 0x10000) throw new ContainerError(`the CHIP packet at offset ${offset} has a wrong size ${size} at ${formatC64Address(address)}`);
+    if (size > 0) chips.push({ bank, address, size, chipType, data: buffer.subarray(offset + 0x10, offset + 0x10 + size) });
+    offset += packetLength;
+  }
+  if (chips.length === 0) throw new ContainerError("the CRT has no CHIP packet with data");
+  const crt: Crt = { name, type, typeName, exrom, game, chips };
+  if (type === 0) crt.mode = exrom === 0 && game === 1 ? "8k" : exrom === 0 && game === 0 ? "16k" : "ultimax";
+  return crt;
+}
+
+export interface TapeEntry {
+  name: string;
+  nameBytes: number[];
+  /** The C64 file type byte of the entry. */
+  fileType: number;
+  start: number;
+  end: number;
+  bytes: number;
+  offset: number;
+  /** True when the end address in the directory was wrong and the size comes from the file layout. */
+  fixedSize?: boolean;
+}
+
+export interface Tape {
+  name: string;
+  entries: TapeEntry[];
+}
+
+export function parseT64(bytes: Uint8Array): Tape {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.length < 0x40 || !buffer.toString("latin1", 0, 32).startsWith("C64")) throw new ContainerError("the file is not a T64: it does not start with C64");
+  const maxEntries = buffer.readUInt16LE(0x22);
+  const name = buffer.toString("latin1", 0x28, 0x40).replace(/[\0 ]+$/, "");
+  const raw: Array<Omit<TapeEntry, "bytes" | "end"> & { end: number }> = [];
+  for (let index = 0; index < maxEntries; index++) {
+    const at = 0x40 + index * 0x20;
+    if (at + 0x20 > buffer.length) break;
+    if (buffer[at] !== 1) continue;
+    const nameField = [...buffer.subarray(at + 0x10, at + 0x20)];
+    while (nameField.length > 0 && (nameField.at(-1) === 0x20 || nameField.at(-1) === 0xa0 || nameField.at(-1) === 0x00)) nameField.pop();
+    raw.push({
+      name: petsciiNameToText(Uint8Array.from(nameField)),
+      nameBytes: nameField,
+      fileType: buffer[at + 1]!,
+      start: buffer.readUInt16LE(at + 2),
+      end: buffer.readUInt16LE(at + 4),
+      offset: buffer.readUInt32LE(at + 8),
+    });
+  }
+  // Many T64 files have a wrong end address: the next file or the end of the file bounds each one.
+  const offsets = [...raw.map((entry) => entry.offset), buffer.length].sort((a, b) => a - b);
+  const entries = raw.map((entry): TapeEntry => {
+    if (entry.offset >= buffer.length) throw new ContainerError(`the T64 entry ${entry.name} starts past the end of the file`);
+    const available = offsets.find((offset) => offset > entry.offset)! - entry.offset;
+    const stated = entry.end - entry.start;
+    const bytes = stated > 0 && stated <= available ? stated : Math.min(available, 0x10000 - entry.start);
+    return { ...entry, end: entry.start + bytes - 1, bytes, ...(bytes === stated ? {} : { fixedSize: true }) };
+  });
+  return { name, entries };
+}
+
+/** The PRG of a tape entry: its start address, then its bytes. */
+export function tapeFile(bytes: Uint8Array, entry: TapeEntry): Buffer {
+  return Buffer.concat([Buffer.from([entry.start & 0xff, entry.start >> 8]), Buffer.from(bytes.subarray(entry.offset, entry.offset + entry.bytes))]);
+}

package/skills/c64-disk/scripts/disk.ts

@@ -1,13 +1,17 @@
 // The c64-disk script: inspects a project disk image with c1541 through the
-// Host Runtime and extracts files into the project.
+// Host Runtime and extracts files into the project. T64 tape files and CRT
+// cartridge files are read locally (D54): no host tool reads them.
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parseArgs } from "node:util";
 
+import { formatC64Address } from "#src/c64.ts";
 import { inspectDisk } from "#src/host-client/tools.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
+import { ContainerError, parseCrt, parseT64, tapeFile } from "./containers.ts";
 
 const USAGE = `disk.ts <action> <image> [name] [--out <file>]
 
@@ -16,12 +20,16 @@ const USAGE = `disk.ts <action> <image> [name] [--out <file>]
   entry <image> <name>              the directory entry of one file
   chain <image> <name>              the track and sector of each block of one file
   read <image> <name> --out <file>  write the bytes of one file into the project
+  crt <file.crt> --out <dir>        write each CHIP packet of a cartridge as a PRG
 
 <image> is a .d64, .d71, .d81 or .g64 file, relative to the project directory.
+directory and read also take a .t64 tape file, and directory a .crt cartridge
+file; the script reads those itself. A CRT can have hardware type 0 (normal
+8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) or 32 (EasyFlash).
 <name> is the file name as the directory shows it. Write a byte that has no
 character as {$xx}, for example {$c1}. The result is one JSON object.`;
 
-const ACTIONS = ["directory", "bam", "entry", "chain", "read"] as const;
+const ACTIONS = ["directory", "bam", "entry", "chain", "read", "crt"] as const;
 type Action = (typeof ACTIONS)[number];
 
 async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
@@ -33,8 +41,8 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   const named = action === "entry" || action === "chain" || action === "read";
   if (named && name === undefined) throw new UsageError(`${action} needs a file name`);
   if ((!named && name !== undefined) || extra.length > 0) throw new UsageError("too many arguments");
-  if (action === "read" && values.out === undefined) throw new UsageError("read needs --out <file>");
-  if (action !== "read" && values.out !== undefined) throw new UsageError("only read takes --out");
+  if ((action === "read" || action === "crt") && values.out === undefined) throw new UsageError(`${action} needs --out`);
+  if (action !== "read" && action !== "crt" && values.out !== undefined) throw new UsageError("only read and crt take --out");
   let outPath: string | undefined;
   if (values.out !== undefined) {
     try {
@@ -44,7 +52,17 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     }
   }
 
-  const result = await inspectDisk({ image, action: action as Action, ...(name === undefined ? {} : { name }) });
+  const kind = image.toLowerCase().endsWith(".t64") ? "t64" : image.toLowerCase().endsWith(".crt") ? "crt" : "disk";
+  if (action === "crt" && kind !== "crt") throw new UsageError("crt needs a .crt file");
+  if (kind !== "disk") {
+    try {
+      return local(kind, action as Action, image, name, values.out);
+    } catch (error) {
+      if (error instanceof ContainerError) throw new UsageError(`${image}: ${error.message}`);
+      throw error;
+    }
+  }
+  const result = await inspectDisk({ image, action: action as Exclude<Action, "crt">, ...(name === undefined ? {} : { name }) });
   if ("found" in result && !result.found) return { output: { found: false }, failed: true };
   if (result.action === "read" && result.found) {
     mkdirSync(dirname(outPath!), { recursive: true });
@@ -55,6 +73,42 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   return { output, failed: false };
 }
 
+/** A tape or cartridge file, read here (D54). */
+function local(kind: "t64" | "crt", action: Action, image: string, name: string | undefined, out: string | undefined): { output: unknown; failed: boolean } {
+  const { bytes } = readProjectFile(image);
+  if (kind === "t64") {
+    if (action !== "directory" && action !== "read") throw new UsageError(`a T64 file has only directory and read, not ${action}`);
+    const tape = parseT64(bytes);
+    const shown = (entry: (typeof tape.entries)[number]) => ({
+      name: entry.name,
+      start: formatC64Address(entry.start),
+      end: formatC64Address(entry.end),
+      bytes: entry.bytes,
+      ...(entry.fixedSize ? { fixedSize: true } : {}),
+    });
+    if (action === "directory") return { output: { name: tape.name, entries: tape.entries.map(shown) }, failed: false };
+    const entry = tape.entries.find((candidate) => candidate.name.toLowerCase() === name!.toLowerCase());
+    if (entry === undefined) return { output: { found: false }, failed: true };
+    const file = tapeFile(bytes, entry);
+    writeProjectFile(out!, file, { what: "--out" });
+    return { output: { found: true, name: entry.name, bytes: file.length, output: out }, failed: false };
+  }
+  if (action !== "directory" && action !== "crt") throw new UsageError(`a CRT file has only directory and crt, not ${action}`);
+  const crt = parseCrt(bytes);
+  const chips = crt.chips.map((chip) => ({
+    bank: chip.bank,
+    address: formatC64Address(chip.address),
+    size: chip.size,
+    space: `bank${chip.bank}`,
+    file: `bank${chip.bank}-${chip.address.toString(16).padStart(4, "0")}.prg`,
+  }));
+  const output = { name: crt.name, type: crt.type, typeName: crt.typeName, exrom: crt.exrom, game: crt.game, ...(crt.mode === undefined ? {} : { mode: crt.mode }), chips };
+  if (action === "directory") return { output: { ...output, chips: chips.map(({ file: _file, ...chip }) => chip) }, failed: false };
+  crt.chips.forEach((chip, index) => writeProjectFile(`${out}/${chips[index]!.file}`, Buffer.concat([Buffer.from([chip.address & 0xff, chip.address >> 8]), chip.data]), { what: "--out" }));
+  writeProjectFile(`${out}/crt.json`, Buffer.from(`${JSON.stringify(output, null, 2)}\n`), { what: "--out" });
+  return { output: { ...output, out }, failed: false };
+}
+
 await runScript(
   async () => {
     const { output, failed } = await run(process.argv.slice(2));