@henols/c64-re-tools 2.1.1 → 2.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "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,9 +31,11 @@ node <skill>/scripts/assembler.ts build src main.a --out build/game.prg
 | `--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` | Check the program byte by byte against the program in the knowledge, each segment. Put it in with `image` of the c64-knowledge skill. `--space drive8` or `--space bank0` compares with the program of that space. |
+| `--compare` | Check the program byte by byte against the program in the knowledge, each segment. Put it in with `image` of the c64-knowledge skill. `--space drive8` or `--space bank0` compares with the program of that space. The script refuses `--space` without `--compare`. |
 | `--plain` | Write only the bytes of the program, without the 2-byte load address of a PRG. `loadRange` still tells where the bytes go. |
 | `--all-symbols` | List all symbols. Without it, the list does not include the constants that the source does not use. `unusedConstants` gives their count. |
+| `--max-listed 200` | Show at most 200 symbols in the result. The default is 50. `symbols.count` gives the count of all symbols. |
+| `--out-symbols build/game.json` | Write all symbols to this file as `{"symbols": [...]}`. Give this file to the c64-testing skill as the symbols of the rebuild. |
 
 The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
 
@@ -46,6 +48,7 @@ The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--p
 - 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 script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - 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.
@@ -64,7 +67,7 @@ The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--p
 
 1. Find the source root and the entry source. The entry source sets its own start address with `* = $0801` or similar.
 2. Run the script.
-3. If `result` is `PASS`, the PRG is at `out`. `loadRange` tells where it loads. `symbols` gives each symbol:
+3. If `result` is `PASS`, the PRG is at `out`. `loadRange` tells where it loads. `symbols` is a list with `count` and `listed`. Each item in `listed` is one symbol:
    - Kind `address` has a value in `loadRange`. It gives the `address`.
    - Kind `constant` has a value outside `loadRange`. It gives the `value` as `$` and four or more hex digits. A label in a `!pseudopc` block can be a constant, because its value is the run address, not the load address.
    - `used` is `false` when the source does not use the symbol.
@@ -92,7 +95,7 @@ A symbol from the rebuilt source can give the address of a routine in the rebuil
 - `FAIL` with `assembled: false`: the source has errors. `diagnostics` gives them.
 - `FAIL` with `assembled: true`: `--compare` found differences. The PRG is at `out`.
 
-With `--compare`, `compare` gives `identical` and `segments`: one check for each segment of the program in the knowledge. The `result` of a check is `identical`, `different` with `firstDifference`, or `not covered` when the build does not hold the segment.
+With `--compare`, `compare` gives `identical` and `segments`: one check for each segment of the program in the knowledge. The `result` of a check is `identical`, `different` with `firstDifference`, or `not covered` when the build does not hold the segment. `firstDifference` gives the `address`, and the byte of the build (`built`) and of the knowledge (`reference`), each as `$` and two hex digits.
 
 ## Failure and conflicts
 

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

@@ -11,8 +11,8 @@ import { knowledgeNames } from "#src/knowledge/names.ts";
 import { requireProgram, type ProgramImage } from "#src/knowledge/program.ts";
 import { assemble } from "#src/native/acme.ts";
 import { localToolContext } from "#src/native/local.ts";
-import type { AcmeParams } from "#src/native/types.ts";
-import { OPTIONS, runScript, UsageError } from "#src/script.ts";
+import type { AcmeParams, AssembledSymbol } from "#src/native/types.ts";
+import { listed as listedItems, OPTIONS, runScript, UsageError } from "#src/script.ts";
 import { compareBuild } from "./lib/compare.ts";
 
 function parseDefine(text: string): [string, number | boolean] {
@@ -25,6 +25,13 @@ function parseDefine(text: string): [string, number | boolean] {
   throw new UsageError(`--define ${match[1]} needs an integer or true/false, not ${value}`);
 }
 
+/** A symbol of the build: an address as $ and four hex digits, a constant as $ and at least four hex digits. */
+function showSymbol(symbol: AssembledSymbol) {
+  return symbol.kind === "address"
+    ? { name: symbol.name, kind: "address", address: formatC64Address(symbol.address), used: symbol.used }
+    : { name: symbol.name, kind: "constant", value: `$${symbol.value.toString(16).padStart(4, "0")}`, used: symbol.used };
+}
+
 await runScript({
   name: "assembler",
   summary: "Assembles project source with ACME and writes the program into the project.",
@@ -38,14 +45,16 @@ await runScript({
         { name: "<entry>", help: "the main source file, relative to the source root" },
       ],
       options: {
-        out: { ...OPTIONS.out, value: "<file.prg>", help: "where to write the program, relative to the project folder", required: true },
+        out: { ...OPTIONS.out, output: "file", value: "<file.prg>", help: "where to write the program, relative to the project folder", required: true },
         include: { kind: "text", value: "<dir>", multiple: true, help: "an include folder, relative to the source root" },
         define: { kind: "text", value: "NAME=VALUE", multiple: true, help: "an assembler symbol: an integer ($hex allowed) or true/false" },
         "set-pc": { kind: "address", value: "<address>", help: "the start address when the source sets none, for example '$0801'" },
         compare: { kind: "flag", help: "check the program byte by byte against the program in the knowledge, each segment" },
-        space: { ...OPTIONS.space, help: "with --compare: the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255" },
+        space: { kind: "space", value: "<space>", help: "with --compare: the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255" },
         plain: { kind: "flag", help: "write the bytes only, without the 2-byte load address of a PRG" },
         "all-symbols": { kind: "flag", help: "list also the constants that the source does not use" },
+        "max-listed": { ...OPTIONS["max-listed"], help: "list at most n symbols (default 50). The count is always given" },
+        "out-symbols": { kind: "path", output: "file", value: "<file.json>", help: "write all symbols to this project file as {\"symbols\": [...]}: the names of the rebuild for c64-testing" },
       },
       notes: "Symbol values are $ and at least four hex digits. Put the program into the knowledge with knowledge.ts image of the c64-knowledge skill before --compare.",
       run: async (call) => {
@@ -53,6 +62,7 @@ await runScript({
         const out = call.string("out")!;
         // Read the program before ACME runs, so a project without it stops at once.
         let program: ProgramImage | undefined;
+        if (call.string("space") !== undefined && !call.flag("compare")) throw new UsageError("--space works only with --compare: it names the knowledge space of the program to compare with");
         if (call.flag("compare")) {
           const db = openForRead();
           try {
@@ -82,7 +92,8 @@ await runScript({
         const compared = program === undefined ? undefined : compareBuild(attachments![0]!, program);
         // An include file of platform names gives many constants that the program does not use.
         const all = call.flag("all-symbols");
-        const listed = result.symbols!.filter((symbol) => all || symbol.kind === "address" || symbol.used);
+        const shown = result.symbols!.filter((symbol) => all || symbol.kind === "address" || symbol.used);
+        const symbolsPath = call.string("out-symbols");
         return {
           // A build that differs from its reference is a failed check.
           result: compared !== undefined && !compared.identical ? "FAIL" : "PASS",
@@ -90,12 +101,9 @@ await runScript({
           ...written,
           ...(plain ? { plain: true } : {}),
           loadRange: { start: formatC64Address(range.start), end: formatC64Address(range.end), bytes: range.bytes },
-          symbols: listed.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.toString(16).padStart(4, "0")}`, used: symbol.used },
-          ),
-          ...(all ? {} : { unusedConstants: result.symbols!.length - listed.length }),
+          symbols: listedItems(shown, call.count("max-listed")!, showSymbol, "a larger --max-listed, or --out-symbols <file.json> for all symbols"),
+          ...(symbolsPath === undefined ? {} : { symbolsFile: writeReported(symbolsPath, `${JSON.stringify({ symbols: shown.map(showSymbol) }, null, 1)}\n`, { what: "--out-symbols" }) }),
+          ...(all ? {} : { unusedConstants: result.symbols!.length - shown.length }),
           diagnostics: result.diagnostics,
           ...(compared === undefined ? {} : { compare: compared }),
         };

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

@@ -1,7 +1,7 @@
 // The byte check of a build: the assembled program against the program
 // in the knowledge, segment by segment.
 
-import { formatC64Address, prgRange } from "#src/c64.ts";
+import { formatC64Address, formatC64Byte, prgRange } from "#src/c64.ts";
 
 export interface SegmentCheck {
   start: string;
@@ -10,7 +10,8 @@ export interface SegmentCheck {
   /** Bytes of the segment that the build does not hold. */
   uncovered?: number;
   differences?: number;
-  firstDifference?: { address: string; built: number; reference: number };
+  /** The first address that differs, with its byte in the build and in the knowledge, each as $ and two hex digits. */
+  firstDifference?: { address: string; built: string; reference: string };
 }
 
 /** The program that the build is checked against: its segments and its bytes in them. */
@@ -34,7 +35,7 @@ export function compareBuild(prg: Uint8Array, program: Reference): { identical:
       const referenceByte = program.byteAt(address);
       if (builtByte === referenceByte) continue;
       differences++;
-      first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
+      first ??= { address: formatC64Address(address), built: formatC64Byte(builtByte), reference: formatC64Byte(referenceByte) };
     }
     const uncovered = segment.end - segment.start + 1 - (to - from + 1);
     return {

package/skills/c64-basic/SKILL.md

@@ -30,6 +30,7 @@ node <skill>/scripts/basic.ts list extracted/game.prg
 - 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 script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - 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.

package/skills/c64-disk/SKILL.md

@@ -47,6 +47,7 @@ File names show the characters that the C64 shows in a directory list. A byte th
 - 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 script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - 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.

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

@@ -123,7 +123,7 @@ await runScript({
       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 } },
+      options: { out: { ...OPTIONS.out, output: "file", 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")!;
@@ -145,7 +145,7 @@ await runScript({
       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 } },
+      options: { out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "the folder for the files, relative to the project folder", required: true } },
       run: (call) => {
         const image = call.subject(0);
         kindFor("crt", image, ["crt"]);

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

@@ -5,6 +5,7 @@
 
 import { formatC64Address, petsciiNameToText } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
+import { hasSignature } from "#src/media.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" };
@@ -30,11 +31,10 @@ export interface Crt {
   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 Refusal("media-error", "the file is not a CRT: it does not start with C64 CARTRIDGE");
+  if (!hasSignature("crt", buffer)) throw new Refusal("media-error", "the file is not a CRT: it does not start with C64 CARTRIDGE");
+  if (buffer.length < 0x40) throw new Refusal("media-error", `the CRT header is shorter than 64 bytes: the file has only ${buffer.length} bytes`);
   const headerLength = buffer.readUInt32BE(0x10);
   const type = buffer.readUInt16BE(0x16);
   const exrom = buffer[0x18]!;
@@ -85,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 Refusal("media-error", "the file is not a T64: it does not start with C64");
+  if (buffer.length < 0x40 || !hasSignature("t64", buffer)) throw new Refusal("media-error", "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 }> = [];

package/skills/c64-docs/SKILL.md

@@ -49,6 +49,7 @@ node <skill>/scripts/docs.ts link README.md docs --source src --check
 - 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 script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - 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.
@@ -144,7 +145,7 @@ Do not store:
 - `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` ``.
+- `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` ``. The script does not link such a mention until it is correct.
 - `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.
 - `stale-reference`: the source or the reference is older than the knowledge. Do steps 2 and 3 of the workflow again.
 - `conflict`: the knowledge has conflicts from a git merge. Run `knowledge.ts merge` of c64-knowledge.

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

@@ -297,7 +297,7 @@ await runScript({
       summary: "Writes the reference pages: a page for each module, and pages for the names, the variables, the tables, the memory map and the graphics.",
       subjects: [{ name: "<source-dir>", help: SOURCE.help }],
       options: {
-        out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the reference pages, relative to the project folder, for example docs/reference. generate writes only there and refuses a page in it that it did not write", required: true },
+        out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "the folder for the reference pages, relative to the project folder, for example docs/reference. generate writes only there and refuses a page in it that it did not write", required: true },
         "max-listed": OPTIONS["max-listed"],
       },
       notes: "When the knowledge has the program of the source (knowledge.ts image of the c64-knowledge skill), the reference decodes the tables and shows the graphics.",

package/skills/c64-docs/scripts/lib/links.ts

@@ -102,6 +102,8 @@ export function linkPage(text: string, context: LinkContext): { text: string; ch
         const expected = `$${(address + delta).toString(16).toUpperCase().padStart(4, "0")}`;
         const holder = context.placeOf(given!);
         report("wrong-address", `\`${name}${offset ?? ""}\` is ${expected} in the knowledge, and the page gives ${addressText}${holder === undefined || holder === name ? "" : `, a place in \`${holder}\``}. Correct the name or the address.${digits!.length <= 2 ? ` For a value, write \`${name}\` = \`${addressText}\`.` : ""}`);
+        // A mention with a problem gets no link: the text stays as the person wrote it until it is correct.
+        return whole;
       }
       const shownName = `${TICK}${name}${offset ?? ""}${TICK}`;
       const code = context.codeOf(name);

package/skills/c64-emulator/SKILL.md

@@ -57,6 +57,7 @@ For a large result, give `out` with a path in the project. `c64_memory_read`, `c
 
 - Only the first byte of an instruction gets execute. Thus `read` without `out` gives a new range at each instruction of code. For code, use `summary`, or `read` with `out`.
 - A read on a byte right after executed code, or at a return address, can be a dummy read of the 6502. The CPU reads such a byte but does not use it.
+- VICE has a known flaw: it uses only one bit of `$01` to find RAM or ROM. At `$A000-$BFFF` it gives `rom` when bit 0 is set, also when bit 1 is clear and the CPU used the RAM there. Many games set `$01` to `$35`. Then code that runs at `$A000-$BFFF` shows as ROM. `emulatorFlaw` in the result tells when this can occur. Every access at `$D000-$DFFF` shows as I/O.
 
 `c64_profile` gives the routines that used the most cycles since the session started, the last `clear` or the last `c64_window`. Use action `clear` before the part of the program that you want to measure. The profiler gives the cycles to the routine that a JSR called last. Code that the CPU enters with JMP or a branch counts for that routine. After `c64_window` or a snapshot restore, the profiler of VICE keeps the routines that ran before the restore. Then `c64_profile` can give the cycles of the program to such a routine, for example `$fd50`. Do not trust the routine addresses of `c64_profile` after a restore.
 
@@ -80,7 +81,7 @@ Write operations need a stopped CPU. Stop the CPU with `c64_execution` action `p
 
 A cartridge from `c64_autostart` stays in the C64 through every reset, as on a real C64. `c64_status` gives `cartridge: true` while the C64 has it, and `cartridge: false` when it does not. `c64_autostart` of a file that is not a cartridge removes the cartridge first. `c64_autostart` also sets both joysticks to the center first. `joysticksCentred` gives the ports that it changed.
 
-Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped. `space` in the result is `drive8`. A breakpoint or a watchpoint in space `drive8` that stops `advance-frames` gives the same `pc` and `space`.
+Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped. `space` in the result is `drive8`. A breakpoint or a watchpoint in space `drive8` that stops `advance-frames` gives the same `pc` and `space`. `c64_status` also gives them. A memory target or a memory condition tests only space `c64`.
 
 `c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard matrix directly does not see them. Many games do this. No MCP tool presses a key of the keyboard matrix. For such a program:
 
@@ -134,6 +135,8 @@ An error is `{"error": {"code": "...", "message": "..."}}`. The message tells wh
 - `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
 - `machine-state-lost` with a different message: the connection to the host runtime was lost, and the machine state is gone. Do not continue with results from before. The next call starts a new machine when the host runtime runs. Load the program again, and set the breakpoints and the watchpoints again. If the next call gives `machine-unavailable` with a message that the host runtime does not run, obey the rule for that message.
 - `machine-unavailable` and the message names a pause or a dialog in the emulator window: this occurs only while the window is open. Do not send more operations. Tell the user to resume the emulator (Pause, Alt+P) or to close the dialog in the VICE window. Then do the operation again. The machine state does not change.
+- `machine-unavailable` and the message says that the emulator does not take commands now, with no window open: wait a few seconds. Then do the operation again one time. If you get the same error again, stop the task. Tell the user to restart the c64-re-tools MCP server, and wait for the user.
+- `media-error`: the file is not of the type that its extension names. Give a file of that type.
 - `machine-running`: stop the CPU first, then try again.
 - `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. Do not try to repair the installation.
 - `c64_run_until` with `stopReason` `timeout`: the target did not occur in the frame limit. This is evidence too. Report it.

package/skills/c64-knowledge/SKILL.md

@@ -27,7 +27,7 @@ One of these:
 node <skill>/scripts/knowledge.ts <command> [subjects] [options]
 ```
 
-A symbol is the name of an address from the user or the LLM. An analyzer name is a second name from DXA, Ghidra or an idiom, for example `FUN_17e2`. Each analyzer keeps its own name at an address. `at`, `search` and `export` show the analyzer names. The generated source uses only the symbols, unless c64-source gets `--analyzer-names`. To use an analyzer name in the source, `rename` the address with it.
+A symbol is the name of an address from the user or the LLM. An analyzer name is a second name from DXA, Ghidra or an idiom, for example `FUN_17e2`. Each analyzer keeps its own name at an address. `at`, `search` and `export` show the analyzer names. The generated source uses only the symbols, unless c64-source gets `--analyzer-names`. To use an analyzer name in the source, `rename` the address with it. A symbol name is a label for ACME: a letter or underscore, then letters, digits or underscores. The knowledge refuses the name of a 6502 instruction, for example `lda`, in upper or lower case.
 
 | Need | Command |
 |---|---|
@@ -42,6 +42,7 @@ A symbol is the name of an address from the user or the LLM. An analyzer name is
 | What the knowledge holds of the program | `program` |
 | The code of a range with names, comments, access and references | `listing '$0400-$04ff'` |
 | Name the symbol at an address | `rename '$2100' update_player --kind routine` |
+| The rows that one revision added and closed, also memory, entry and coverage rows | `revision 20261015T2145` |
 | Remove a symbol | `remove-symbol '$2100'` |
 | Classify memory | `classify '$3000-$303f' sprite` |
 | Classify a table of records | `classify '$3000-$303b' bytes --element 6` |
@@ -62,12 +63,12 @@ A symbol is the name of an address from the user or the LLM. An analyzer name is
 | Files of generated source | `modules` |
 | The address spaces that hold knowledge | `spaces` |
 | History | `history '$2100'`, `history --name update_player`, `history --macro inc16`, `revisions`, `revision 20261015T2145` |
-| Go back to an earlier state | `revert 20261015T2145` |
+| Go back to an earlier state | `revert 20261015T2145` for all spaces, or `revert 20261015T2145 --space bank3` for one space |
 | Decide the conflicts after a git merge | `merge --reason 'merge of two computers'` |
 
 A revision has an id such as `20261015T214501.123-k3f9qz`. The id starts with the date and time. A command takes the full id, or a start of the id that only one revision has. The revision `0` is the knowledge before the first revision.
 
-Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
+Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. `revert` is different: without `--space`, it reverts all spaces. With `--space`, it reverts only that space. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
 
 Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write`, `reference` and `pointer`. Only an operand expression writes a `pointer` reference.
 
@@ -94,6 +95,7 @@ Region types:
 - 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 script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - 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.
@@ -127,12 +129,16 @@ Write:
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
 
+A write can give the same fact that an analyzer gave. Then the fact gets the origin of the write, and `previous` in the result shows the row of the analyzer. The next analysis does not remove the fact. This is true for a symbol, a region, a comment and a reference. A `--by user` write over the same fact of `llm` also changes the origin to `user`. A `--by llm` write over the same fact of `user` changes nothing.
+
+A comment and a module are at the start of an instruction. In a code region, the script refuses an address that is an operand byte of an instruction. The error gives the start of that instruction. In data, each address is correct.
+
 ## The program and the coverage
 
 The knowledge holds the program, so a project needs no image or coverage files. The other skills read them from the knowledge and take no path to them.
 
 1. Capture a packed program with the c64-unpacker skill into `.c64-re-tools/local/`. Then put it in with `image .c64-re-tools/local/capture/image.json`. The script reads `image.bin`, `entry_state.json` and the stages next to it.
-2. For a program without a packer, drive code or a cartridge bank, put the PRG in with `image <file.prg>`. Give `--space drive8` or `--space bank0` for drive code or a bank.
+2. For a program without a packer, drive code or a cartridge bank, put the PRG in with `image <file.prg>`. Give `--space drive8` or `--space bank0` for drive code or a bank. A PRG has the extension `.prg` or no extension. The script refuses a file with another extension.
 3. Write each coverage map of a run into `.c64-re-tools/local/`. Then add it with `coverage <map.bin> ...`.
 4. Read what the knowledge holds with `program`: the segments, the entry, and the coverage maps that it has.
 
@@ -172,7 +178,7 @@ The ops and their fields:
 | `unmacro` | `name` |
 | `use` | `start`, `end`, `macro`, `args` (a list or a comma list) |
 
-A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. The script checks an `operand`, `patch` or `use` write against the program of the knowledge in the space of `--space`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
+Each write can also have `space`. A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. The script checks an `operand`, `patch` or `use` write against the program of the knowledge in the space of `--space`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
 
 The c64-provenance skill writes a batch with `match --out`. The batch holds the names of library routines at their addresses in this program. Read the `batch.leftOut` of its result first. Then apply the batch with the command in its `apply`.
 
@@ -233,7 +239,7 @@ A patch is ACME code that replaces a range of the program when the build defines
 - The code must fit in the range. NOP ($EA) fills the bytes after the code. `--nop` gives a range of NOP only.
 - `--code` gives the code as text. `--code-file` reads the code from a project file. The code can use the labels and the macros of the source, and local labels with a dot, for example `.skip`.
 - The braces in the code must be pairs, because the source puts the code inside `{ }`.
-- A patch cannot overlap another patch or a macro use.
+- A patch cannot overlap another patch or a macro use. A patch with the same start and the same switch replaces the patch. A patch of another switch at the same start gives the error `conflict`.
 - Each byte of the range must be in the program of the knowledge.
 - A `patch` write without `--comment` keeps the comment that the patch has.
 

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

@@ -151,9 +151,18 @@ function suppression(row: SuppressionRow) {
   return { ...spaceOf(row), suppresses: row.entity, ...place, origin: row.origin, revision: row.revision };
 }
 
+/** A row of the program in a revision: memory bytes, the entry, or a coverage range. */
+function programRow(entry: Extract<HistoryEntry, { entity: "memory" | "entry" | "coverage" }>) {
+  if (entry.entity === "memory") return { ...spaceOf(entry.row), start: formatC64Address(entry.row.address), end: formatC64Address(entry.row.address + entry.row.bytes - 1), bytes: entry.row.bytes, origin: entry.row.origin, revision: entry.row.revision };
+  if (entry.entity === "entry") return { ...spaceOf(entry.row), address: formatC64Address(entry.row.address), state: entry.row.state, stages: entry.row.stages, origin: entry.row.origin, revision: entry.row.revision };
+  return { ...spaceOf(entry.row), kind: entry.row.kind, start: formatC64Address(entry.row.start), end: formatC64Address(entry.row.end), origin: entry.row.origin, revision: entry.row.revision };
+}
+
 function historyEntry(entry: HistoryEntry) {
   const shown =
-    entry.entity === "symbol" || entry.entity === "analyzer-name"
+    entry.entity === "memory" || entry.entity === "entry" || entry.entity === "coverage"
+      ? programRow(entry)
+      : entry.entity === "symbol" || entry.entity === "analyzer-name"
       ? symbol(entry.row)
       : entry.entity === "region"
         ? region(entry.row)
@@ -319,6 +328,9 @@ function shownPrevious(row: NonNullable<BatchStep["previous"]>) {
   if ("switch" in row) return patch(row);
   if ("body" in row) return macro(row);
   if ("macro" in row) return macroUse(row);
+  if ("placement" in row) return comment(row);
+  if ("from" in row) return reference(row);
+  if ("file" in row) return module(row);
   return symbol(row);
 }
 
@@ -420,7 +432,8 @@ function writeCommand(spec: Omit<CommandSpec, "run">, prepare: (call: Call) => W
   return {
     ...spec,
     notes: [spec.notes, "A write is one revision. It makes .c64-re-tools/knowledge/ when it is not there."].filter((note) => note !== undefined).join("\n"),
-    options: { ...spec.options, ...WRITE },
+    // A command can give a WRITE option its own help or default, for example --space of revert.
+    options: Object.fromEntries(Object.entries({ ...spec.options, ...WRITE }).map(([name, option]) => [name, spec.options?.[name] ?? option])),
     run: (call) => withWrite(prepare(call)),
   };
 }
@@ -564,11 +577,11 @@ const READ_COMMANDS: CommandSpec[] = [
       return { revisions: list(call, rows, (row) => row, "a larger --max-listed, or --before <revision> with the oldest revision in listed") };
     },
   ),
-  readCommand({ name: "revision", summary: "The rows that one revision added and closed.", subjects: [REVISION], options: LIST }, (db, call) => {
+  readCommand({ name: "revision", summary: "The rows that one revision added and closed: knowledge rows, and memory, entry and coverage rows of the program.", subjects: [REVISION], options: LIST }, (db, call) => {
     const changes = revision(db, call.subject(0));
     return { revision: changes.revision, added: list(call, changes.added, historyEntry, MORE), closed: list(call, changes.closed, historyEntry, MORE) };
   }),
-  readCommand({ name: "export", summary: "All current knowledge to a project file as JSON.", options: { ...FILTER, out: { ...OPTIONS.out, value: "<file>", help: "the JSON file, relative to the project folder", required: true } } }, (db, call) => {
+  readCommand({ name: "export", summary: "All current knowledge to a project file as JSON.", options: { ...FILTER, out: { ...OPTIONS.out, output: "file", value: "<file>", help: "the JSON file, relative to the project folder", required: true } } }, (db, call) => {
     const range = rangeOf(call);
     const origins = originsOf(call);
     const space = call.space;
@@ -595,7 +608,7 @@ const READ_COMMANDS: CommandSpec[] = [
       name: "listing",
       summary: "The program as ACME lines with names, operand expressions, comments, the access of each line in the coverage (x executed, r read, w written) and the references in and out.",
       subjects: [RANGE],
-      options: { out: { ...OPTIONS.out, value: "<file>", help: "write the listing as text to this file in place of the lines in the result" }, ...LIST },
+      options: { out: { ...OPTIONS.out, output: "file", value: "<file>", help: "write the listing as text to this file in place of the lines in the result" }, ...LIST },
     },
     (db, call) => {
       const { start, end } = call.parseRange(call.subject(0), "<range>");
@@ -649,10 +662,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
     (call) => {
       const context = contextOf(call);
       const request = { space: call.space, address: call.parseAddress(call.subject(0), "<address>"), placement: oneOf(COMMENT_PLACEMENTS, call.subject(1), "<placement>"), text: call.rest(2).join(" ") };
-      return (db) => {
-        const result = setComment(db, context, request);
-        return { revision: result.revision, comment: comment(result.current) };
-      };
+      return (db) => shown(setComment(db, context, request), "comment", comment);
     },
   ),
   writeCommand({ name: "uncomment", summary: "Removes a comment.", subjects: [ADDRESS, { name: "<placement>", help: `one of ${COMMENT_PLACEMENTS.join(", ")}` }] }, (call) => {
@@ -671,10 +681,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
         const context = contextOf(call);
         const request = { space: call.space, from: call.parseAddress(call.subject(0), "<from>"), to: call.parseAddress(call.subject(1), "<to>"), kind: oneOf(REFERENCE_KINDS, call.subject(2), "<kind>") };
         return name === "reference"
-          ? (db) => {
-              const result = addReference(db, context, request);
-              return { revision: result.revision, reference: reference(result.current) };
-            }
+          ? (db) => shown(addReference(db, context, request), "reference", reference)
           : (db) => ({ revision: removeReference(db, context, request).revision });
       },
     ),
@@ -685,10 +692,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
       const context = contextOf(call);
       const title = call.string("title");
       const request = { space: call.space, start: call.parseAddress(call.subject(0), "<start>"), file: call.subject(1), ...(title === undefined ? {} : { title }) };
-      return (db) => {
-        const result = setModule(db, context, request);
-        return { revision: result.revision, module: module(result.current) };
-      };
+      return (db) => shown(setModule(db, context, request), "module", module);
     },
   ),
   writeCommand({ name: "unmodule", summary: "Removes the module that starts at an address.", subjects: [START] }, (call) => {
@@ -837,11 +841,23 @@ const WRITE_COMMANDS: CommandSpec[] = [
       };
     },
   ),
-  writeCommand({ name: "revert", summary: "Makes the knowledge the same as at one revision. The revert is a new revision: the history stays complete.", subjects: [REVISION] }, (call) => {
-    const context = contextOf(call);
-    const request = { revision: call.subject(0) };
-    return (db) => ({ revision: revert(db, context, request).revision });
-  }),
+  writeCommand(
+    {
+      name: "revert",
+      summary: "Makes the knowledge the same as at one revision: all spaces, or with --space only that space. The revert is a new revision: the history stays complete.",
+      subjects: [REVISION],
+      options: { space: { kind: "space", value: "<space>", help: "revert only this space: c64, drive8, or bank0 to bank255. The other spaces do not change. Without --space, every space reverts" } },
+    },
+    (call) => {
+      const context = contextOf(call);
+      const space = call.string("space");
+      const request = { revision: call.subject(0), ...(space === undefined ? {} : { space }) };
+      return (db) => {
+        const result = revert(db, context, request);
+        return { revision: result.revision, restores: result.current.restoredRevision, ...(space === undefined ? { spaces: "all" } : { space }) };
+      };
+    },
+  ),
   writeCommand({ name: "merge", summary: "Decides the conflicts that a git merge of two computers' work left: of the rows of one conflict, the newest stays. One revision for all." }, (call) => {
     const context = contextOf(call);
     const platform = new Map(platformNames().map((entry) => [entry.name, entry.address]));
@@ -885,7 +901,7 @@ const JOIN: CommandSpec = {
   name: "join",
   summary: "Joins the batches of agents that worked in parallel into one batch for apply. It writes no knowledge.",
   subjects: [{ name: "<batch>", help: 'a batch: a list of writes, or {"owner": {"start": "$1000", "end": "$1fff"}, "ops": [...]}', list: true }],
-  options: { ...SPACE, out: { ...OPTIONS.out, value: "<file>", help: "the joined batch, relative to the project folder", required: true } },
+  options: { ...SPACE, out: { ...OPTIONS.out, output: "file", value: "<file>", help: "the joined batch, relative to the project folder", required: true } },
   notes: "At an address in the owner range of a batch, its name, comment, operand and module win, and its regions come last. One name or one module file at two addresses writes nothing.",
   run: (call) => {
     if (call.subjects.length < 2) throw new UsageError("join needs two or more batch files");
@@ -940,7 +956,7 @@ function batchOperation(call: Call, item: unknown, at: string): BatchOperation {
 function batchFields(fields: Record<string, unknown>, at: string, address: (text: string, what: string) => number): BatchOperation {
   const op = oneOf(Object.keys(BATCH_FIELDS) as Array<BatchOperation["op"]>, String(fields.op), `${at}: op`);
   const unknown = Object.keys(fields).filter((key) => key !== "op" && key !== "space" && !BATCH_FIELDS[op].includes(key));
-  if (unknown.length > 0) throw new Refusal("invalid-input", `${at}: ${op} takes ${BATCH_FIELDS[op].join(", ")}, not ${unknown.join(", ")}`);
+  if (unknown.length > 0) throw new Refusal("invalid-input", `${at}: ${op} takes ${[...BATCH_FIELDS[op], "space"].join(", ")}, not ${unknown.join(", ")}`);
   const text = (key: string) => {
     if (typeof fields[key] !== "string") throw new Refusal("invalid-input", `${at}: ${key} must be a string`);
     return fields[key] as string;
@@ -1006,7 +1022,7 @@ function batchFields(fields: Record<string, unknown>, at: string, address: (text
 
 await runScript({
   name: "knowledge",
-  summary: "Reads and writes the knowledge of the project: names, regions, comments, references, the program and its coverage, and the source knowledge. A read needs no knowledge folder. Every command takes --space: c64 (the default), drive8 for 1541 drive code, or bank0 to bank255 for cartridge banks.",
+  summary: "Reads and writes the knowledge of the project: names, regions, comments, references, the program and its coverage, and the source knowledge. A read needs no knowledge folder. Every command takes --space: c64 (the default), drive8 for 1541 drive code, or bank0 to bank255 for cartridge banks. revert without --space reverts all spaces.",
   names: knowledgeNames,
   commands: [...READ_COMMANDS, ...WRITE_COMMANDS, JOIN],
 });

package/skills/c64-knowledge/scripts/lib/listing.ts

@@ -4,7 +4,7 @@
 // reads files: knowledge.ts gives the lookups.
 
 import { COVERAGE, formatC64Address, formatC64Byte } from "#src/c64.ts";
-import { MODE_LENGTH, OPCODES, type Mode } from "#src/opcodes.ts";
+import { instructionWith, MODE_LENGTH, OPCODES, type Mode } from "#src/opcodes.ts";
 
 export interface ListingSource {
   /** The image byte at an address, or undefined outside the image. */
@@ -52,36 +52,13 @@ function accessOf(coverage: Uint8Array | undefined, start: number, length: numbe
   return text === "" ? "-" : text;
 }
 
-/** The operand of an instruction in ACME syntax, with the name of its target where one exists. */
+/** The operand value of an instruction as an expression: the name of its target where one exists, else the number. Empty for no operand. */
 function operandOf(mode: Mode, address: number, low: number, high: number, nameOf: ListingSource["nameOf"]): string {
-  const word = low | (high << 8);
   const named = (target: number, digits: 2 | 4) => nameOf(target) ?? (digits === 2 ? formatC64Byte(target) : formatC64Address(target));
-  switch (mode) {
-    case "imp":
-      return "";
-    case "imm":
-      return `#${formatC64Byte(low)}`;
-    case "zp":
-      return named(low, 2);
-    case "zpx":
-      return `${named(low, 2)},x`;
-    case "zpy":
-      return `${named(low, 2)},y`;
-    case "abs":
-      return named(word, 4);
-    case "abx":
-      return `${named(word, 4)},x`;
-    case "aby":
-      return `${named(word, 4)},y`;
-    case "ind":
-      return `(${named(word, 4)})`;
-    case "izx":
-      return `(${named(low, 2)},x)`;
-    case "izy":
-      return `(${named(low, 2)}),y`;
-    case "rel":
-      return named((address + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff, 4);
-  }
+  if (mode === "imp") return "";
+  if (mode === "imm") return formatC64Byte(low);
+  if (mode === "rel") return named((address + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff, 4);
+  return MODE_LENGTH[mode] === 3 ? named(low | (high << 8), 4) : named(low, 2);
 }
 
 /** The lines of start..end: instructions in code regions, decoded from the region start, and bytes elsewhere. */
@@ -91,7 +68,14 @@ export function listing(source: ListingSource, start: number, end: number): List
     const bytes = Array.from({ length }, (_, offset) => source.byteAt(address + offset)!.toString(16).padStart(2, "0")).join(" ");
     const label = source.nameOf(address);
     const second = source.secondNames(address).filter((name) => name !== label);
-    const { line: lineComments, side } = source.comments(address);
+    const { line: lineComments, side: own } = source.comments(address);
+    // A comment inside the line (knowledge of an older version) shows with its address, as in the source of c64-source.
+    const inner: string[] = [];
+    for (let offset = 1; offset < length; offset++) {
+      const found = source.comments(address + offset);
+      for (const text of [...found.line, ...(found.side === undefined ? [] : [found.side])]) inner.push(`${formatC64Address(address + offset)}: ${text}`);
+    }
+    const side = own === undefined && inner.length === 0 ? undefined : [...(own === undefined ? [] : [own]), ...inner].join(" ");
     const references = source.references(address);
     const access = accessOf(source.coverage, address, length);
     return {
@@ -123,8 +107,9 @@ export function listing(source: ListingSource, start: number, end: number): List
       const length = MODE_LENGTH[opcode.mode];
       const bytes = Array.from({ length: length - 1 }, (_, offset) => source.byteAt(address + 1 + offset));
       if (address + length - 1 <= region.end && bytes.every((value) => value !== undefined)) {
+        // The operand expression of the knowledge in the syntax of the addressing mode, as c64-source writes it.
         const operand = source.operand(address) ?? operandOf(opcode.mode, address, bytes[0] ?? 0, bytes[1] ?? 0, source.nameOf);
-        if (address >= start) lines.push(line(address, length, operand === "" ? opcode.mnemonic : `${opcode.mnemonic} ${operand}`));
+        if (address >= start) lines.push(line(address, length, instructionWith(byte, operand)));
         address += length;
         continue;
       }