@henols/c64-re-tools 2.0.1 → 2.1.0-rc.2

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

@@ -2,119 +2,145 @@
 // Host Runtime and extracts files into the project. T64 tape files and CRT
 // cartridge files are read locally: 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 { isRefusal, Refusal } from "#src/errors.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 "./lib/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
+import { readProjectFile, writeReported } from "#src/host-client/transfer.ts";
+import { OPTIONS, runScript, type Call, type SubjectSpec } from "#src/script.ts";
+import { parseCrt, parseT64, tapeFile } from "./lib/containers.ts";
 
-<image> is a .d64, .d71, .d81 or .g64 file, relative to the project folder.
-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 IMAGE: SubjectSpec = { name: "<image>", help: "a .d64, .d71, .d81 or .g64 disk image, relative to the project folder" };
+const NAME: SubjectSpec = { name: "<name>", help: "the file name as the directory shows it. Write a byte that has no character as {$xx}, for example {$c1}" };
 
-const ACTIONS = ["directory", "bam", "entry", "chain", "read", "crt"] as const;
-type Action = (typeof ACTIONS)[number];
+type Kind = "disk" | "t64" | "crt";
+const kindOf = (image: string): Kind => (image.toLowerCase().endsWith(".t64") ? "t64" : image.toLowerCase().endsWith(".crt") ? "crt" : "disk");
 
-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 folder that stays inside it, not ${values.out}`);
-    }
+/** Runs `body` and names the file in a refusal of its content. */
+function about<T>(image: string, body: () => T): T {
+  try {
+    return body();
+  } catch (error) {
+    if (isRefusal(error) && error.code === "invalid-input") throw new Refusal(error.code, `${image}: ${error.message}`);
+    throw error;
   }
+}
 
-  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 };
-  }
+/** A file that the image does not hold. */
+const noFile = (image: string, name: string) => new Refusal("not-found", `${image} has no file ${name}. Give the name as directory shows it.`);
+
+/** directory, bam, entry and chain of a disk image through c1541. */
+async function inspect(call: Call, action: "directory" | "bam" | "entry" | "chain"): Promise<unknown> {
+  const image = call.subject(0);
+  const name = call.subjects[1];
+  const result = await inspectDisk({ image, action, ...(name === undefined ? {} : { name }) });
+  if ("found" in result && !result.found) throw noFile(image, name!);
   const { action: _action, ...output } = result;
-  return { output, failed: false };
+  return output;
 }
 
-/** A tape or cartridge file, read here. */
-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 };
+/** The directory of a T64 tape file. */
+function tapeDirectory(image: string) {
+  const tape = about(image, () => parseT64(readProjectFile(image).bytes));
+  return {
+    name: tape.name,
+    entries: tape.entries.map((entry) => ({ name: entry.name, start: formatC64Address(entry.start), end: formatC64Address(entry.end), bytes: entry.bytes, ...(entry.fixedSize ? { fixedSize: true } : {}) })),
+  };
 }
 
-await runScript(
-  async (argv) => {
-    const { output, failed } = await run(argv);
-    if (failed) process.exitCode = 1;
-    return output;
-  },
-  { usage: USAGE },
-);
+/** A CRT cartridge file: its header and CHIP packets, each with the PRG file name that crt writes. */
+function cartridge(image: string) {
+  const crt = about(image, () => parseCrt(readProjectFile(image).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` }));
+  return { crt, header: { name: crt.name, type: crt.type, typeName: crt.typeName, exrom: crt.exrom, game: crt.game, ...(crt.mode === undefined ? {} : { mode: crt.mode }) }, chips };
+}
+
+/** A command that takes only a disk image. */
+const diskOnly = (call: Call, action: string) => {
+  if (kindOf(call.subject(0)) !== "disk") throw new Refusal("invalid-input", `${action} needs a .d64, .d71, .d81 or .g64 disk image, not ${call.subject(0)}`);
+};
+
+await runScript({
+  name: "disk",
+  summary: "Inspects a disk image with c1541 and extracts files into the project. T64 tape files and CRT cartridge files are read here. A CRT can have hardware type 0 (normal 8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) or 32 (EasyFlash).",
+  commands: [
+    {
+      name: "directory",
+      summary: "The disk name, the id, the free blocks and the files. It also reads a .t64 tape file and a .crt cartridge file.",
+      subjects: [{ ...IMAGE, help: "a disk image, a .t64 tape file or a .crt cartridge file, relative to the project folder" }],
+      run: async (call) => {
+        const image = call.subject(0);
+        const kind = kindOf(image);
+        if (kind === "t64") return tapeDirectory(image);
+        if (kind === "crt") {
+          const { header, chips } = cartridge(image);
+          return { ...header, chips: chips.map(({ file: _file, ...chip }) => chip) };
+        }
+        return inspect(call, "directory");
+      },
+    },
+    {
+      name: "bam",
+      summary: "The free and used sectors of each track, and the used sectors that no file holds.",
+      subjects: [IMAGE],
+      run: (call) => {
+        diskOnly(call, "bam");
+        return inspect(call, "bam");
+      },
+    },
+    {
+      name: "entry",
+      summary: "The directory entry of one file.",
+      subjects: [IMAGE, NAME],
+      run: (call) => {
+        diskOnly(call, "entry");
+        return inspect(call, "entry");
+      },
+    },
+    {
+      name: "chain",
+      summary: "The track and the sector of each block of one file.",
+      subjects: [IMAGE, NAME],
+      run: (call) => {
+        diskOnly(call, "chain");
+        return inspect(call, "chain");
+      },
+    },
+    {
+      name: "read",
+      summary: "Writes the bytes of one file into the project. It also reads a .t64 tape file.",
+      subjects: [{ ...IMAGE, help: "a disk image or a .t64 tape file, relative to the project folder" }, NAME],
+      options: { out: { ...OPTIONS.out, value: "<file>", help: "the file to write, relative to the project folder", required: true } },
+      run: async (call) => {
+        const [image, name] = [call.subject(0), call.subject(1)];
+        const out = call.string("out")!;
+        const kind = kindOf(image);
+        if (kind === "crt") throw new Refusal("invalid-input", `read takes a disk image or a .t64 tape file. Give crt for ${image}`);
+        if (kind === "t64") {
+          const { bytes } = readProjectFile(image);
+          const tape = about(image, () => parseT64(bytes));
+          const entry = tape.entries.find((candidate) => candidate.name.toLowerCase() === name.toLowerCase());
+          if (entry === undefined) throw noFile(image, name);
+          return { name: entry.name, ...writeReported(out, tapeFile(bytes, entry), { what: "--out" }) };
+        }
+        const result = await inspectDisk({ image, action: "read", name });
+        if (result.action !== "read" || !result.found) throw noFile(image, name);
+        return { name: result.name, ...writeReported(out, result.data!, { what: "--out" }) };
+      },
+    },
+    {
+      name: "crt",
+      summary: "Writes each CHIP packet of a cartridge as a PRG, and crt.json with the header and the packets.",
+      subjects: [{ name: "<file.crt>", help: "a .crt cartridge file, relative to the project folder" }],
+      options: { out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the files, relative to the project folder", required: true } },
+      run: (call) => {
+        const image = call.subject(0);
+        if (kindOf(image) !== "crt") throw new Refusal("invalid-input", `crt needs a .crt file, not ${image}`);
+        const out = call.string("out")!;
+        const { crt, header, chips } = cartridge(image);
+        const files = crt.chips.map((chip, index) => writeReported(`${out}/${chips[index]!.file}`, Buffer.concat([Buffer.from([chip.address & 0xff, chip.address >> 8]), chip.data]), { what: "--out" }));
+        files.push(writeReported(`${out}/crt.json`, `${JSON.stringify({ ...header, chips }, null, 2)}\n`, { what: "--out" }));
+        return { ...header, chips, files };
+      },
+    },
+  ],
+});

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

@@ -4,9 +4,7 @@
 // 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 {}
+import { Refusal } from "#src/errors.ts";
 
 /** The CRT hardware types this toolkit reads, by type number. */
 export const CRT_TYPES: Record<number, string> = { 0: "normal", 5: "Ocean", 19: "Magic Desk", 32: "EasyFlash" };
@@ -36,32 +34,32 @@ 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");
+  if (buffer.length < 0x40 || buffer.toString("latin1", 0, 16) !== SIGNATURE) throw new Refusal("invalid-input", "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(", ")}`);
+    throw new Refusal("invalid-input", `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}`);
+    if (buffer.toString("latin1", offset, offset + 4) !== "CHIP") throw new Refusal("invalid-input", `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 (packetLength < 0x10 || offset + packetLength > buffer.length) throw new Refusal("invalid-input", `the CHIP packet at offset ${offset} runs past the end of the file`);
+    if (bank > 255) throw new Refusal("invalid-input", `the CHIP packet at offset ${offset} has bank ${bank}; banks go up to 255`);
+    if (size > packetLength - 0x10 || address + size > 0x10000) throw new Refusal("invalid-input", `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");
+  if (chips.length === 0) throw new Refusal("invalid-input", "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;
@@ -87,7 +85,7 @@ export interface Tape {
 
 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");
+  if (buffer.length < 0x40 || !buffer.toString("latin1", 0, 32).startsWith("C64")) throw new Refusal("invalid-input", "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 }> = [];
@@ -109,7 +107,7 @@ export function parseT64(bytes: Uint8Array): Tape {
   // 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`);
+    if (entry.offset >= buffer.length) throw new Refusal("invalid-input", `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);

package/skills/c64-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c64-docs
-description: Use this skill to write the documentation of a C64 program. The documentation explains the flows, state machines, tables, data formats and graphics, with links to the source lines and to the assets. A script generates the reference pages from the knowledge and the source. You write the other pages by the method of this skill. A second script adds the links to each name and address and checks every link. Use it after the source is identical, or to keep the documentation correct after a change to the knowledge.
+description: Use this skill to write the documentation of a C64 program. The documentation explains the flows, state machines, tables, data formats and graphics, with links to the source lines and to the assets. The script generates the reference pages from the knowledge and the source. You write the other pages by the method of this skill. A second command of the script adds the links to each name and address and checks every link. Use it after the source is identical, or to keep the documentation correct after a change to the knowledge.
 ---
 
 # c64-docs
@@ -9,10 +9,10 @@ description: Use this skill to write the documentation of a C64 program. The doc
 
 Write documentation that tells how a program works, and that points to the code. The documentation is Markdown in the project. The entry page is `README.md` in the project folder. The other pages and the reference are in `docs/`. The documentation has two parts:
 
-- **The reference.** `generate.ts` generates it from the knowledge, the source map of c64-source and the image. It has a page for each module. The page gives the routines, their callers and callees, the data and a call graph. It also has pages for the names, the variables, the tables, the memory map and the graphics. Do not edit these pages. The next run writes over them.
+- **The reference.** `docs.ts generate` generates it from the knowledge, the source map of c64-source and the image. It has a page for each module. The page gives the routines, their callers and callees, the data and a call graph. It also has pages for the names, the variables, the tables, the memory map and the graphics. Do not edit these pages. The next run writes over them.
 - **The pages that you write.** They tell how the program works. They give the flows, the state machines, the data formats and the task of each part. Use the page types in `references/page-types.md` and the rules in `references/style.md`.
 
-`link.ts` connects the two parts. In each page that you write, a name in backticks gets a link to its line in the source. The address after the name gets a link to the entry of the name in the reference. When the source changes, `link.ts` moves the links to the new lines.
+`docs.ts link` connects the two parts. In each page that you write, a name in backticks gets a link to its line in the source. The address after the name gets a link to the entry of the name in the reference. When the source changes, `docs.ts link` moves the links to the new lines.
 
 This skill does not change the knowledge.
 
@@ -24,44 +24,62 @@ This skill does not change the knowledge.
 
 ## Tools / execution path
 
-The scripts run on this machine. They do not use the emulator or the host runtime.
+The script runs on this machine. It does not use the emulator or the host runtime.
 
 ```
-node <skill>/scripts/generate.ts --source src --out docs/reference
-node <skill>/scripts/link.ts README.md docs --source src
-node <skill>/scripts/link.ts README.md docs --source src --check
+node <skill>/scripts/docs.ts generate src --out docs/reference
+node <skill>/scripts/docs.ts link README.md docs --source src
+node <skill>/scripts/docs.ts link README.md docs --source src --check
 ```
 
 | Option | Meaning |
 |---|---|
-| `--source src` | The source directory of c64-source. Both scripts read `src/source-map.json`. |
-| `--out docs/reference` | The directory of the reference. `generate.ts` writes only there. It refuses to start when the directory holds a page that it did not write. |
-| `README.md docs` | The pages of the documentation: `.md` files and directories. `link.ts` reads each file and every `.md` file below each directory. It changes only the pages that you wrote. It checks the pages of the reference. |
-| `--reference <dir>` | The directory of the reference for `link.ts`. The default is the `reference` directory of the first directory that has one, for example `docs/reference`. |
-| `--check` | `link.ts` writes nothing. It fails when a link is not up to date or a page has a problem. |
+| `src` | `docs.ts generate`: the source directory of c64-source. The command reads `src/source-map.json`. |
+| `--source src` | `docs.ts link`: the source directory of c64-source. The command reads `src/source-map.json`. |
+| `--out docs/reference` | The directory of the reference. `docs.ts generate` writes only there. It refuses to start when the directory holds a page that it did not write. |
+| `README.md docs` | The pages of the documentation: `.md` files and directories. `docs.ts link` reads each file and every `.md` file below each directory. It changes only the pages that you wrote. It checks the pages of the reference. |
+| `--reference <dir>` | The directory of the reference for `docs.ts link`. The default is the `reference` directory of the first directory that has one, for example `docs/reference`. |
+| `--check` | `docs.ts link` writes nothing. `result` is `FAIL` when a link is not up to date or a page has a problem. |
+| `--max-listed 20` | List at most this number of items in each list. The default is 50. |
+
+### Calling the script
+
+- Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
+- `<script>.ts --help` lists the commands. `<script>.ts <command> --help` gives the subjects and the options of one command. The help is JSON: `{"text": "..."}`.
+- An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
+- A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
+- Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
+- An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
+- The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
 
 ### Project folder
 
 - Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
-- Give `--project <folder>` to each script when the working directory is not in the project.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
+- Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
 ## Workflow
 
 1. Read the knowledge with the c64-knowledge skill. The documentation can only be as good as the knowledge. Each routine needs a name and a comment. Each table needs a region and a name. Each file of the source needs a module with a title. Record what is missing with c64-knowledge.
 2. Generate the source with c64-source. Make sure that `check.identical` is `true`. The script also writes `source-map.json`.
-3. Run `generate.ts`. Read `index.md` of the reference. A module with no routines, or a routine with no comment, shows what the knowledge does not have yet.
+3. Run `docs.ts generate`. Read `index.md` of the reference. A module with no routines, or a routine with no comment, shows what the knowledge does not have yet.
 4. Make the plan of the pages. Start from the modules and the call graphs. Find the main loop, the interrupt chain, the dispatch tables, the state machines and the data formats. Each subsystem gets one page in `docs/`. The entry page `README.md` in the project folder lists the pages. Use the page types in `references/page-types.md`.
 5. Write each page. Read the code and the knowledge for each fact. Run the program with c64-testing or c64-emulator when a fact needs a run. Write each name with its address, for example `` `draw_room` `$09BC` ``. Mark each fact with its evidence. Several subagents can write the pages at the same time, one page each. Give each subagent `references/page-types.md` and `references/style.md`.
 6. Record each new fact in the knowledge first: a name, a comment, a region or a module. Then the source and the reference show it too. A fact only in a page is lost at the next change of the knowledge.
-7. Run `link.ts`. Read `problems` and correct each one. Then run `link.ts --check`. Make sure that `problems.count` is 0 and that `notUpToDate.links` is 0.
-8. When the project folder is in a workspace with other projects, find `README.md` at the root of the workspace. This page lists each program of the workspace. Add one row for the program, with a link to `<project>/README.md` and one sentence. If the page does not exist, make it. Use the workspace index in `references/page-types.md`. `link.ts` does not read this page, because the page is not in the project folder.
+7. Run `docs.ts link`. Read `problems` and correct each one. Then run `docs.ts link --check`. Make sure that `result` is `PASS`.
+8. When the project folder is in a workspace with other projects, find `README.md` at the root of the workspace. This page lists each program of the workspace. Add one row for the program, with a link to `<project>/README.md` and one sentence. If the page does not exist, make it. Use the workspace index in `references/page-types.md`. `docs.ts link` does not read this page, because the page is not in the project folder.
 9. After each change to the knowledge, do steps 2, 3 and 7 again. The links then go to the new lines.
 
 ## The links
 
-`link.ts` changes these forms in the pages that you write. It does not change a code block, a mermaid diagram or an HTML comment. The examples are for a page in `docs/`. In `README.md`, the links start with `src/` and `docs/reference/`.
+`docs.ts link` changes these forms in the pages that you write. It does not change a code block, a mermaid diagram or an HTML comment. The examples are for a page in `docs/`. In `README.md`, the links start with `src/` and `docs/reference/`.
 
-| You write | `link.ts` writes |
+| You write | `docs.ts link` writes |
 |---|---|
 | `` `draw_room` `$09BC` `` | `` [`draw_room`](../src/room_draw.asm#L6) [`$09BC`](reference/modules/room_draw.md#draw_room) `` |
 | `` `draw_room` (`$09BC`) `` | the same links, in the brackets |
@@ -71,8 +89,8 @@ node <skill>/scripts/link.ts README.md docs --source src --check
 
 - A name is a name of the knowledge or of the source. A word in backticks that is no name stays as it is.
 - In a list such as `` `a`/`b` `$1000`/`$1010` ``, each name gets its link. The addresses stay as they are.
-- `link.ts` writes a link again when its line moves. A link that you made to another target stays as you wrote it.
-- `link.ts` checks every link and image: the file must exist, a `#anchor` must exist in the page, and a `#L` line must exist in the file.
+- `docs.ts link` writes a link again when its line moves. A link that you made to another target stays as you wrote it.
+- `docs.ts link` checks every link and image: the file must exist, a `#anchor` must exist in the page, and a `#L` line must exist in the file.
 
 ## The reference
 
@@ -105,25 +123,26 @@ Do not store:
 
 ## Result
 
-`generate.ts` gives one JSON object:
+`docs.ts generate`:
 
 - `out`, `index` and `revision`.
 - `pages`, `entries`, `tables`, `images` and `edges`: the counts of the reference.
+- `files`: the pages that it wrote, each with `out`, `bytes` and `sha256`.
 - `program`: `the knowledge`, or a note when the knowledge has no program. Without the program, the tables are not decoded and the graphics page has no images.
 
-`link.ts` gives one JSON object:
+`docs.ts link`:
 
+- `result`: `PASS` when no page has a problem. `FAIL` when a page has a problem, or with `--check` when a link is not up to date.
 - `pages`: the count of the pages that it read.
-- `linked`: the count of the links that it wrote, and the pages that it changed. With `--check`, `notUpToDate` gives the links that are not up to date.
-- `problems`: `count`, `byKind` and the first 50 problems. Each problem has `at` (the page and the line), `kind` and `message`.
-
-The exit status is 0 when there is no problem. The exit status is 1 when there is a problem, or with `--check` when a link is not up to date. The exit status is 2 for a wrong argument.
+- `reference`: the directory of the reference, or a note when there is no reference.
+- `linked`: the count of the links that it wrote (`links`), and the pages that it changed. With `--check`, `notUpToDate` gives the links that are not up to date.
+- `problems`: `byKind` and the list of problems. Each problem has `at` (the page and the line), `kind` and `message`.
 
 ## Failure and conflicts
 
 - `not-found` for `source-map.json`: generate the source with c64-source. Then run the script again.
-- `invalid-input` that names an old revision: the knowledge changed after the source. Generate the source again, then run `generate.ts`.
-- `invalid-input` that names a page in the reference directory: the page is not a page of `generate.ts`. Move the page out of the directory. Do not give `--out` a directory with pages that you wrote.
+- `invalid-input` that names an old revision: the knowledge changed after the source. Generate the source again, then run `docs.ts generate`.
+- `invalid-input` that names a page in the reference directory: the page is not a page of `docs.ts generate`. Move the page out of the directory. Do not give `--out` a directory with pages that you wrote.
 - `unknown-name`: the page uses a name that is not in the knowledge. Record the name with c64-knowledge, or correct the page.
 - `wrong-address`: the address after the name is not the address of the name, and it is not a place inside it. The message gives the routine that holds the address. Correct the name or the address. For a value, write `` `scroll_moves` = `$10` ``.
 - `missing-file`, `missing-anchor` or `missing-line`: a link goes to nothing. Correct the link. An image of an asset must exist in the project.

package/skills/c64-docs/references/style.md

@@ -1,14 +1,14 @@
 # Style of the pages
 
-These rules apply to each page that you write. `link.ts` checks the rules that a script can check.
+These rules apply to each page that you write. `docs.ts link` checks the rules that a script can check.
 
 ## Names and addresses
 
-- Write each routine, table and variable with its name and its address: `` `draw_room` `$09BC` ``. `link.ts` gives the name a link to its line, and the address a link to its entry in the reference.
+- Write each routine, table and variable with its name and its address: `` `draw_room` `$09BC` ``. `docs.ts link` gives the name a link to its line, and the address a link to its entry in the reference.
 - Use the name of the knowledge. Do not make a name that is only in the page. When a part has no good name, record a name with c64-knowledge first.
 - For a place inside a routine, write the name of the routine and the address of the place: `` `draw_room` `$0A04` ``. The address gets a link to its line.
 - For a byte inside a table or a variable, write the name with an offset: `` `room_script_vars+3` `$4E9A` ``.
-- For a value, write an equals sign: `` `scroll_moves` = `$10` ``. Without the sign, `link.ts` reads `$10` as an address.
+- For a value, write an equals sign: `` `scroll_moves` = `$10` ``. Without the sign, `docs.ts link` reads `$10` as an address.
 - Write addresses with `$` and hex digits in upper case: `$09BC`. Write values in hex with `$`, or in decimal without `$`.
 - Write a range with a hyphen: `` `$4E97-$4E9B` ``.
 - Write the name and the address in backticks. A name without backticks gets no link.
@@ -27,7 +27,7 @@ These rules apply to each page that you write. `link.ts` checks the rules that a
 - Use mermaid for the diagrams: `flowchart` for calls and data flow, `stateDiagram-v2` for state machines. Write the name and the address in each node: `"draw_room $09BC"`.
 - A diagram gets no links. Give the links in a table or a list under the diagram.
 - Keep a diagram small: at most about 20 nodes. Make two diagrams before one diagram that a reader cannot read.
-- Embed an image only from the project. It can be an image of the reference (`reference/images/`) or a PNG that a skill made. It can also be an asset that a script of the project made from a format of the program, for example `../assets/rooms/room00.png`. `link.ts` checks that each image exists.
+- Embed an image only from the project. It can be an image of the reference (`reference/images/`) or a PNG that a skill made. It can also be an asset that a script of the project made from a format of the program, for example `../assets/rooms/room00.png`. `docs.ts link` checks that each image exists.
 - Give each image one line of text that tells what it shows.
 
 ## Text
@@ -39,5 +39,5 @@ These rules apply to each page that you write. `link.ts` checks the rules that a
 
 ## Generated pages
 
-- Do not edit a page in the reference. Change the knowledge, generate the source, and run `generate.ts` again.
-- Do not put a page that you write in the reference directory. `generate.ts` refuses to write when one is there.
+- Do not edit a page in the reference. Change the knowledge, generate the source, and run `docs.ts generate` again.
+- Do not put a page that you write in the reference directory. `docs.ts generate` refuses to write when one is there.