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

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

@@ -0,0 +1,110 @@
+// 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";
+import { compareBuild } from "./compare.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'
+  --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.`;
+
+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" },
+      compare: { 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!;
+  const compared = values.compare === undefined ? undefined : compareBuild(attachments![0]!, values.compare);
+  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,
+      ...(compared === undefined ? {} : { compare: compared }),
+    },
+    // A build that differs from its reference is a failed check.
+    failed: compared !== undefined && !compared.identical,
+  };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);

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

@@ -0,0 +1,66 @@
+---
+name: c64-basic
+description: Use this skill to decode a C64 BASIC V2 program (PRG) into a readable listing. It also finds where the BASIC gives control to machine code with SYS or USR. Use it on the start file of a game or of a demo. Do not use it on machine code or to run the program. Give the handoff address to the c64-static-analysis or c64-emulator skill.
+---
+
+# c64-basic
+
+## Purpose
+
+Decode a C64 BASIC V2 program. Find the handoff from BASIC to machine code.
+
+This skill does not run the program and does not change project knowledge.
+
+## Inputs
+
+- The program: a PRG file, relative to the project directory.
+
+## Tools / execution path
+
+The script sends the program to the host runtime. The host decodes it with petcat and finds the handoffs.
+
+```
+node <skill>/scripts/basic.ts extracted/game.prg
+```
+
+The script prints one JSON object. Addresses are `$` and four hex digits.
+
+## Workflow
+
+1. Run the script on the program.
+2. Read `listing`. Each line starts with its BASIC line number. Keywords show in lower case. Control characters in strings show in braces, for example `{clr}`.
+3. Read `handoffs`. Each handoff has a `kind` (`sys` or `usr`) and the BASIC `line`.
+   - A `sys` handoff with an `address`: BASIC calls the machine code at that address. The script calculates a SYS argument with numbers, π, `+`, `-`, `*`, `/` and brackets. For example, `SYS π*656` calls `$080c`.
+   - A handoff with `computed: true`: the address comes from a calculation at run time, for example with `PEEK`. A `sys` handoff gives its argument in `expression`. Use the c64-emulator skill to find the address.
+4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls. Some programs have no end marker (two zero bytes) after the last line. The machine code starts directly after the last line. Then `basicEnd` is the first byte of that machine code.
+
+The address ranges are for a load to the load address of the file. A load without `,1` puts a BASIC program at `$0801`. Most loaders have `$0801` as their load address.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not store:
+- the listing.
+
+The entry point of the machine code can be durable knowledge. The c64-reverse-engineering skill decides that and records it with the c64-knowledge skill.
+
+## Result
+
+The listing and the handoff addresses. Or `decoded: false` with a reason when the file is not a BASIC program.
+
+The exit status is 0 for a listing. The exit status is 1 for `decoded: false` and for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `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. A memory dump also gives `decoded: false`: its first two bytes are not a load address, and its bytes go past `$ffff`.
+- 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`, or `machine-unavailable` with 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
+
+- Machine code at the handoff address → c64-static-analysis
+- Run the program to the handoff → c64-emulator
+- Record the entry point → c64-knowledge

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

@@ -0,0 +1,46 @@
+// The c64-basic script: decodes a project C64 BASIC V2 program with petcat
+// through the Host Runtime and reports its machine-code handoffs.
+
+import { statSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+import { formatC64Address } from "#src/c64.ts";
+import { decodeBasic } from "#src/host-client/tools.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+
+const USAGE = `basic.ts <program>
+
+<program> is a PRG file relative to the project directory. The result is one
+JSON object. Addresses are $ and four hex digits.`;
+
+async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { help: { type: "boolean" } } });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 1) throw new UsageError("give one program");
+  const program = positionals[0]!;
+  const result = await decodeBasic({ program });
+  if (!result.decoded) return { output: { decoded: false, reason: result.reason }, failed: true };
+  const size = statSync(resolveProjectPath(program)).size - 2;
+  const end = result.loadAddress + size - 1;
+  return {
+    output: {
+      decoded: true,
+      loadRange: { start: formatC64Address(result.loadAddress), end: formatC64Address(end) },
+      // From here to the end of the load range, the file holds no BASIC (often machine code).
+      basicEnd: result.basicEnd <= end ? formatC64Address(result.basicEnd) : null,
+      listing: result.listing,
+      handoffs: result.handoffs.map((handoff) => ("address" in handoff ? { ...handoff, address: formatC64Address(handoff.address) } : handoff)),
+    },
+    failed: false,
+  };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);

package/skills/c64-disk/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: c64-disk
+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, 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.
+
+## Inputs
+
+- 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 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>]
+```
+
+| Need | Command |
+|---|---|
+| The disk name, the free blocks and the files | `directory original/game.d64` |
+| The free and used sectors of each track, and the used sectors that no file uses | `bam original/game.d64` |
+| 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.
+
+File names show the characters that the C64 shows in a directory list. A byte that has no character shows as `{$xx}`, for example `{$c1}`. Write the name in the same form. The letter case of a name is not important. Put the name in single quotes in a shell, for example `'GAME {$c1}'`.
+
+## Workflow
+
+1. Run `directory`. Find the file in `entries`. Each entry has a `name`, a `type`, a size in `blocks` and the `closed` and `locked` flags.
+2. Run `read` with an output path to extract the file. A PRG file keeps its 2-byte load address at the start.
+3. Run `entry` or `chain` only when the disk structure is important, for example for a loader that reads sectors directly.
+4. Run `bam` only to find used sectors that no file uses. `unreferenced` lists them. The list does not include the header, the directory and the BAM blocks. These sectors can hold data that a loader reads directly.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not store:
+- the directory list
+- sector chains.
+
+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.
+
+The exit status is 0 for a result with the file. The exit status is 1 for `found: false` and for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `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`, or `machine-unavailable` with 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.
+
+## Handoffs
+
+- BASIC program → c64-basic
+- Packed program → c64-unpacker
+- 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

@@ -0,0 +1,120 @@
+// The c64-disk script: inspects a project disk image with c1541 through the
+// 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>]
+
+  directory <image>                 disk name, id, free blocks and the files
+  bam <image>                       free and used sectors of each track, and the
+                                    used sectors that no file holds
+  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", "crt"] as const;
+type Action = (typeof ACTIONS)[number];
+
+async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
+  if (values.help) throw new UsageError("");
+  const [action, image, name, ...extra] = positionals;
+  if (!ACTIONS.includes(action as Action)) throw new UsageError(`the action must be one of ${ACTIONS.join(", ")}`);
+  if (image === undefined) throw new UsageError("the disk image is necessary");
+  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" || 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 {
+      outPath = resolveProjectPath(values.out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+    }
+  }
+
+  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 });
+    writeFileSync(outPath!, result.data!);
+    return { output: { found: true, name: result.name, bytes: result.bytes, output: values.out }, failed: false };
+  }
+  const { action: _action, ...output } = result;
+  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));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);