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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.1.0-rc.2",
+  "version": "2.1.1",
   "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

@@ -100,6 +100,7 @@ With `--compare`, `compare` gives `identical` and `segments`: one check for each
 - `FAIL` with `assembled: true`: the build is not identical to the program in the knowledge. Read `compare.segments`.
 - `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 option or a path is wrong. Read the message and correct the call.
+- `not-found`: the source root has no main source file with that name, or no folder with files for an `--include`. Give a path relative to the source root.
 
 ## Handoffs
 

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

@@ -1,6 +1,8 @@
 // The c64-assembler script: assembles project source with ACME, which it runs
 // itself, and writes the program into the project.
 
+import { posix } from "node:path";
+
 import { formatC64Address } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
 import { readProjectTree, writeReported } from "#src/host-client/transfer.ts";
@@ -62,6 +64,14 @@ await runScript({
         const setPc = call.address("set-pc");
         const tree = readProjectTree(sourceRoot);
         if (!tree.files.some((file) => file.path === entry)) throw new Refusal("not-found", `${entry} is not a file in ${sourceRoot}. Give the main source file relative to the source root.`);
+        // ACME sees only the files of the source root: an include folder holds some of them. A path out of the root is refused later.
+        for (const folder of call.strings("include")) {
+          const inside = posix.normalize(folder.replaceAll("\\", "/")).replace(/\/+$/, "");
+          if (inside === "." || inside === ".." || inside.startsWith("../") || posix.isAbsolute(inside)) continue;
+          if (!tree.files.some((file) => file.path.startsWith(`${inside}/`))) {
+            throw new Refusal("not-found", `There is no include folder ${folder} with files in the source root ${sourceRoot}. Give --include a folder relative to the source root.`);
+          }
+        }
         const params: AcmeParams = { files: tree.files, entrySource: entry, includeDirs: call.strings("include"), defines: Object.fromEntries(call.strings("define").map(parseDefine)), ...(setPc === undefined ? {} : { setPc }) };
 
         const { result, attachments } = await assemble(params, tree.contents, localToolContext());

package/skills/c64-disk/SKILL.md

@@ -97,9 +97,9 @@ The directory, the BAM, an entry or a sector chain as JSON.
 ## Failure and conflicts
 
 - `not-found`: the image file is missing, or the image has no file with that name. 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.
+- `media-error`: the image, the T64 file or the CRT file has a defect, or its content is not of its type. A CRT with a hardware type that the script does not read also gives `media-error`. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the file.
 - `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.
+- `invalid-input`: an argument or a path is wrong. A file with an extension that the command does not take is also wrong. The message gives each type that the command takes. Read the message and correct the call.
 
 A file that is not `closed` was not written fully. Its data can be incomplete.
 

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

@@ -4,7 +4,7 @@
 
 import { formatC64Address } from "#src/c64.ts";
 import { isRefusal, Refusal } from "#src/errors.ts";
-import { inspectDisk } from "#src/host-client/tools.ts";
+import { DISK_IMAGE_TYPES, inspectDisk } from "#src/host-client/tools.ts";
 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";
@@ -13,14 +13,30 @@ const IMAGE: SubjectSpec = { name: "<image>", help: "a .d64, .d71, .d81 or .g64
 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}" };
 
 type Kind = "disk" | "t64" | "crt";
-const kindOf = (image: string): Kind => (image.toLowerCase().endsWith(".t64") ? "t64" : image.toLowerCase().endsWith(".crt") ? "crt" : "disk");
+/** The kind of a file by its extension; undefined for a file that no command takes. */
+function kindOf(image: string): Kind | undefined {
+  const extension = image.toLowerCase().split(".").at(-1) ?? "";
+  if (extension === "t64" || extension === "crt") return extension;
+  return (DISK_IMAGE_TYPES as readonly string[]).includes(extension) ? "disk" : undefined;
+}
+
+const KIND_TEXT: Record<Kind, string> = { disk: "a .d64, .d71, .d81 or .g64 disk image", t64: "a .t64 tape file", crt: "a .crt cartridge file" };
+
+/** The kind of the image of a command; refuses a file of a kind that the command does not take, and names every kind that it takes. */
+function kindFor(command: string, image: string, takes: readonly Kind[]): Kind {
+  const kind = kindOf(image);
+  if (kind !== undefined && takes.includes(kind)) return kind;
+  const kinds = takes.map((item) => KIND_TEXT[item]);
+  const list = kinds.length === 1 ? kinds[0]! : `${kinds.slice(0, -1).join(", ")} or ${kinds.at(-1)}`;
+  throw new Refusal("invalid-input", `${image} is not a file that ${command} takes. Give ${list}.`);
+}
 
 /** 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}`);
+    if (isRefusal(error) && error.code === "media-error") throw new Refusal(error.code, `${image}: ${error.message}`);
     throw error;
   }
 }
@@ -55,9 +71,7 @@ function cartridge(image: string) {
 }
 
 /** 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)}`);
-};
+const diskOnly = (call: Call, action: string) => kindFor(action, call.subject(0), ["disk"]);
 
 await runScript({
   name: "disk",
@@ -69,7 +83,7 @@ await runScript({
       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);
+        const kind = kindFor("directory", image, ["disk", "t64", "crt"]);
         if (kind === "t64") return tapeDirectory(image);
         if (kind === "crt") {
           const { header, chips } = cartridge(image);
@@ -113,8 +127,8 @@ await runScript({
       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 (kindOf(image) === "crt") throw new Refusal("invalid-input", `read takes a disk image or a .t64 tape file. Use the command crt for the cartridge file ${image}.`);
+        const kind = kindFor("read", image, ["disk", "t64"]);
         if (kind === "t64") {
           const { bytes } = readProjectFile(image);
           const tape = about(image, () => parseT64(bytes));
@@ -134,7 +148,7 @@ await runScript({
       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}`);
+        kindFor("crt", image, ["crt"]);
         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" }));

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

@@ -34,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 Refusal("invalid-input", "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("media-error", "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 Refusal("invalid-input", `the CRT has hardware type ${type}; this toolkit reads types ${Object.entries(CRT_TYPES).map(([number, name]) => `${number} (${name})`).join(", ")}`);
+    throw new Refusal("media-error", `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 Refusal("invalid-input", `the CRT has no CHIP packet at offset ${offset}`);
+    if (buffer.toString("latin1", offset, offset + 4) !== "CHIP") throw new Refusal("media-error", `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 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 (packetLength < 0x10 || offset + packetLength > buffer.length) throw new Refusal("media-error", `the CHIP packet at offset ${offset} runs past the end of the file`);
+    if (bank > 255) throw new Refusal("media-error", `the CHIP packet at offset ${offset} has bank ${bank}; banks go up to 255`);
+    if (size > packetLength - 0x10 || address + size > 0x10000) throw new Refusal("media-error", `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 Refusal("invalid-input", "the CRT has no CHIP packet with data");
+  if (chips.length === 0) throw new Refusal("media-error", "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;
@@ -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("invalid-input", "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("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 }> = [];
@@ -107,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 Refusal("invalid-input", `the T64 entry ${entry.name} starts past the end of the file`);
+    if (entry.offset >= buffer.length) throw new Refusal("media-error", `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/scripts/lib/links.ts

@@ -2,8 +2,8 @@
 // its line in the source; the address after it links to the entry of the name
 // in the reference, or, for an address inside the routine or the data of the
 // name ("draw_room $0AAF", a place in draw_room), to the line of that address. A link that points into the source or the reference is
-// managed: link.ts writes it again when a line moves. Other links stay as the
-// person wrote them; link.ts only checks that their targets exist.
+// managed: docs.ts link writes it again when a line moves. Other links stay as the
+// person wrote them; docs.ts link only checks that their targets exist.
 
 import { posix } from "node:path";
 
@@ -24,7 +24,7 @@ export interface LinkContext {
   lineOf: (address: number) => string | undefined;
   /** The name of the routine or data that holds an address, for a message. */
   placeOf: (address: number) => string | undefined;
-  /** True for a project path that link.ts manages: a file of the source or a page of the reference. */
+  /** True for a project path that docs.ts link manages: a file of the source or a page of the reference. */
   managed: (path: string) => boolean;
 }
 

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

@@ -12,7 +12,7 @@ import type { CommentRow, ModuleRow, ReferenceRow, RegionRow, SymbolRow } from "
 import type { RegionType } from "#src/knowledge/schema.ts";
 import type { SourceMap } from "./source-map.ts";
 
-/** The first line of every generated page. A page without it is a page of a person, and generate.ts never writes over it. */
+/** The first line of every generated page. A page without it is a page of a person, and docs.ts generate never writes over it. */
 export const GENERATED_MARK = "<!-- Generated by c64-docs";
 
 export interface ReferenceInput {
@@ -183,7 +183,7 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
   }
   const titleOf = (file: string) => input.modules.find((module) => module.file === file)?.title;
 
-  const header = `${GENERATED_MARK} from knowledge revision ${input.revision} and ${map.pathOf("source-map.json")}. Do not edit: change the knowledge, generate the source again, then run generate.ts. -->`;
+  const header = `${GENERATED_MARK} from knowledge revision ${input.revision} and ${map.pathOf("source-map.json")}. Do not edit: change the knowledge, generate the source again, then run docs.ts generate. -->`;
   const files: ReferenceFile[] = [];
   const write = (path: string, lines: string[]) => files.push({ path, bytes: Buffer.from(`${[header, ...lines].join("\n").replace(/\n{3,}/g, "\n\n")}\n`, "utf8") });
 

package/skills/c64-emulator/SKILL.md

@@ -80,7 +80,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.
+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_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:
 
@@ -137,7 +137,13 @@ An error is `{"error": {"code": "...", "message": "..."}}`. The message tells wh
 - `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.
-- `c64_run_until` with `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address.
+- `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address. The CPU stays stopped, as on a real C64. Each run gives `jam` again. Step, next, until-return and resume refuse with `operation-failed`. Only `c64_reset`, a snapshot restore or `c64_autostart` starts the CPU again.
+- After a JAM, VICE records no CPU history until the next reset. If the CPU ran again after a snapshot restore, `c64_cpu_history` refuses with `operation-failed`. `c64_run_until` then gives `historyMissing` in place of `history`. Use `c64_reset`, or use `c64_trace`.
+- `invalid-input`: the message names the field and the rule. Change the call to obey the rule.
+- `not-found`: a file, a snapshot, a baseline or a point that the call names does not exist.
+- `unsupported-in-space`: the action works only in space `c64`.
+- `limit-exceeded`: the call goes past a limit of the session, for example the number of snapshots. The message names the limit.
+- `operation-failed`: the emulator did not do the operation. The message tells why.
 
 If the runtime evidence does not agree with the current knowledge, do not change the knowledge. Report the conflict and hand it to c64-knowledge.
 

package/skills/c64-knowledge/SKILL.md

@@ -139,6 +139,7 @@ The knowledge holds the program, so a project needs no image or coverage files.
 - `image` writes only the bytes that changed. The same image again writes nothing. A new image replaces the program of the space. The history keeps the old bytes.
 - `coverage` joins the maps. It keeps each address that a run executed, read or wrote. It also keeps each address that one run wrote and executed: self-modified code. `coverage` puts each map into the space of `--space`. You can add the same map to each space. A map that the space has is not added again.
 - The capture and the maps are not necessary after the import. Keep them in `.c64-re-tools/local/`.
+- A `revert` also gives back the coverage maps of that revision. A `revert` to a revision before an import removes the map and its ranges. Then you can import the map again, and `--evidence coverage:<map>` refuses it until you do.
 
 For more than a few writes, use `apply -` and give the writes on standard input as one JSON list. Each write has `op` and the arguments of the command with the same name, for example:
 
@@ -213,6 +214,7 @@ Give one selector:
 | `--value <symbol>` | The symbol plus the offset | `lda bar_colours-1,x` |
 | `--expr <text>` | ACME expression text with names and numbers | `lda #(sprite_bank + 5*64) / 64` |
 
+- The address is the start of an instruction in a code region. The script decodes the instructions from the start of the region, as `listing` does. It refuses an address in no code region and an operand byte of an instruction. Classify the code first.
 - `--offset` adds a whole number to the symbol. Write a negative offset as `--offset=-1`.
 - A name is a symbol of the knowledge or a platform name of the c64-memory-map skill.
 - `--expr` takes `$`, `%` and decimal numbers, names, brackets, the operators `+ - * / % << >> >>> & | XOR`, and `<`, `>`, `-` and `!` before an operand.
@@ -277,7 +279,7 @@ The script records the origin `llm`. Use `--by user` only when the user decides
 
 ## Result
 
-For a read: the current or historical knowledge in compact JSON.
+For a read: the current or historical knowledge in compact JSON. Each list of a list command has `count` and `listed`. `--max-listed` limits `listed`. The default is 50. When the list is longer, `rest` tells how to get the other items. For `revisions`, give `--before` with the oldest revision in `listed`.
 
 For a write: the new revision and the current value after the write. If the write replaces a symbol, a region or an operand expression of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change. For `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.
 

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

@@ -17,11 +17,12 @@ import { operandText } from "#src/knowledge/expression.ts";
 import { historyAt, historyNamed, historyOfMacro, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import { joinBatches, type Batch, type JoinChoice, type JoinClash } from "#src/knowledge/join.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
-import { addCoverage, coverageRuns, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
+import { addCoverage, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
 import {
   analyzerNamesAt,
   at,
   commentsAt,
+  coverageRuns,
   currentRevision,
   listAnalyzerNames,
   listComments,
@@ -83,7 +84,7 @@ import {
 } from "#src/knowledge/write.ts";
 import { platformNames } from "#src/platform.ts";
 import { isInside, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRelative, projectRoot, resolveProjectPath } from "#src/project.ts";
-import { OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec, type SubjectSpec } from "#src/script.ts";
+import { listed, OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec, type SubjectSpec } from "#src/script.ts";
 import { listing, listingText, type ListingSource } from "./lib/listing.ts";
 
 function oneOf<T extends string>(values: readonly T[], value: string | undefined, what: string): T {
@@ -226,13 +227,17 @@ function listingSource(db: DatabaseSync | undefined, space: string): ListingSour
   };
 }
 
-/** --origin for reads: one origin, semantic (user and llm), analyzer (dxa and ghidra), or a comma list. */
+/** Every value of --origin, for the message of a wrong one. */
+const ORIGIN_VALUES = `one of ${ORIGINS.join(", ")}, semantic or analyzer, or a comma list of them. semantic is ${SEMANTIC_ORIGINS.join(" and ")}. analyzer is ${ANALYZERS.slice(0, -1).join(", ")} and ${ANALYZERS.at(-1)}`;
+
+/** --origin for reads: one origin, semantic (user and llm), analyzer (dxa, ghidra and heuristic), or a comma list. */
 function originFilter(value: string): Origin[] {
   const origins = new Set<Origin>();
   for (const part of value.split(",")) {
     if (part === "semantic") for (const origin of SEMANTIC_ORIGINS) origins.add(origin);
     else if (part === "analyzer") for (const origin of ANALYZERS) origins.add(origin);
-    else origins.add(oneOf(ORIGINS, part, "--origin"));
+    else if ((ORIGINS as readonly string[]).includes(part)) origins.add(part as Origin);
+    else throw new UsageError(`--origin cannot be ${JSON.stringify(part)}. Give ${ORIGIN_VALUES}`);
   }
   return [...origins];
 }
@@ -371,6 +376,20 @@ const WRITE: Record<string, OptionSpec> = {
   "expect-revision": OPTIONS["expect-revision"],
 };
 
+/** A list command: --max-listed limits each list of its result. */
+const LIST = { "max-listed": OPTIONS["max-listed"] };
+/** Where to get the rest of a list that a --range limits. */
+const RANGE_REST = "a larger --max-listed, a smaller --range, or knowledge.ts export --out <file> for all current knowledge";
+const MORE = "a larger --max-listed";
+
+/** A list in a result: its count and its first --max-listed items, with rest when it is cut. */
+function list<T, U>(call: Call, items: readonly T[], show: (item: T) => U, rest: string) {
+  return listed(items, call.count("max-listed")!, show, rest);
+}
+
+/** All rows: the lists count every row, and --max-listed limits only what the result shows. */
+const ALL = Number.MAX_SAFE_INTEGER;
+
 /** The rows from --range, or every address. */
 const rangeOf = (call: Call) => call.range("range") ?? { start: 0x0000, end: 0xffff };
 const originsOf = (call: Call) => {
@@ -459,50 +478,50 @@ const READ_COMMANDS: CommandSpec[] = [
       name: "search",
       summary: "Symbol names, analyzer names and comment texts that hold the text.",
       subjects: [{ name: "<text>", help: "the text to find" }],
-      options: { origin: OPTIONS.origin, limit: { kind: "count", value: "<n>", min: 1, max: 10_000, default: 50, help: "at most n rows of each kind (default 50)" } },
+      options: { origin: OPTIONS.origin, ...LIST },
     },
     (db, call) => {
-      const found = search(db, call.subject(0), call.count("limit")!, originsOf(call), call.space);
-      return { symbols: found.symbols.map(symbol), analyzerNames: found.analyzerNames.map(symbol), comments: found.comments.map(comment) };
+      const found = search(db, call.subject(0), ALL, originsOf(call), call.space);
+      const rest = "a larger --max-listed, or a longer <text>";
+      return { symbols: list(call, found.symbols, symbol, rest), analyzerNames: list(call, found.analyzerNames, symbol, rest), comments: list(call, found.comments, comment, rest) };
     },
   ),
   readCommand(
-    { name: "symbols", summary: "The symbols, or with --analyzer the second names that DXA, Ghidra and the idioms gave.", options: { ...FILTER, kind: SYMBOL_KIND, analyzer: { kind: "flag", help: "the analyzer names in place of the symbols" } } },
+    { name: "symbols", summary: "The symbols, or with --analyzer the second names that DXA, Ghidra and the idioms gave.", options: { ...FILTER, kind: SYMBOL_KIND, analyzer: { kind: "flag", help: "the analyzer names in place of the symbols" }, ...LIST } },
     (db, call) => {
       const kind = call.string("kind") as (typeof SYMBOL_KINDS)[number] | undefined;
-      if (call.flag("analyzer")) return { analyzerNames: listAnalyzerNames(db, rangeOf(call), kind, originsOf(call), call.space).map(symbol) };
-      return { symbols: listSymbols(db, rangeOf(call), kind, originsOf(call), call.space).map(symbol) };
+      if (call.flag("analyzer")) return { analyzerNames: list(call, listAnalyzerNames(db, rangeOf(call), kind, originsOf(call), call.space), symbol, RANGE_REST) };
+      return { symbols: list(call, listSymbols(db, rangeOf(call), kind, originsOf(call), call.space), symbol, RANGE_REST) };
     },
   ),
-  readCommand({ name: "regions", summary: "The regions: code, data, tables and the other types.", options: { ...FILTER, type: { kind: "choice", value: "<type>", choices: REGION_TYPES, help: `one of ${REGION_TYPES.join(", ")}` } } }, (db, call) => ({
-    regions: listRegions(db, rangeOf(call), call.string("type") as (typeof REGION_TYPES)[number] | undefined, originsOf(call), call.space).map(region),
+  readCommand({ name: "regions", summary: "The regions: code, data, tables and the other types.", options: { ...FILTER, type: { kind: "choice", value: "<type>", choices: REGION_TYPES, help: `one of ${REGION_TYPES.join(", ")}` }, ...LIST } }, (db, call) => ({
+    regions: list(call, listRegions(db, rangeOf(call), call.string("type") as (typeof REGION_TYPES)[number] | undefined, originsOf(call), call.space), region, RANGE_REST),
   })),
-  readCommand({ name: "comments", summary: "The comments.", options: FILTER }, (db, call) => ({ comments: listComments(db, rangeOf(call), originsOf(call), call.space).map(comment) })),
-  readCommand({ name: "references", summary: "The references: calls, jumps, reads, writes and pointers.", options: { ...FILTER, kind: REFERENCE_KIND } }, (db, call) => ({
-    references: listReferences(db, rangeOf(call), call.string("kind") as (typeof REFERENCE_KINDS)[number] | undefined, originsOf(call), call.space).map(reference),
+  readCommand({ name: "comments", summary: "The comments.", options: { ...FILTER, ...LIST } }, (db, call) => ({ comments: list(call, listComments(db, rangeOf(call), originsOf(call), call.space), comment, RANGE_REST) })),
+  readCommand({ name: "references", summary: "The references: calls, jumps, reads, writes and pointers.", options: { ...FILTER, kind: REFERENCE_KIND, ...LIST } }, (db, call) => ({
+    references: list(call, listReferences(db, rangeOf(call), call.string("kind") as (typeof REFERENCE_KINDS)[number] | undefined, originsOf(call), call.space), reference, RANGE_REST),
   })),
-  readCommand({ name: "suppressions", summary: "The places that removals keep free of analyzer facts, with the reason of each.", options: { range: OPTIONS.range } }, (db, call) => {
+  readCommand({ name: "suppressions", summary: "The places that removals keep free of analyzer facts, with the reason of each.", options: { range: OPTIONS.range, ...LIST } }, (db, call) => {
     const rows = listSuppressions(db, rangeOf(call), call.space);
-    const reasons = reasonsOf(db, rows);
-    return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
+    const reasons = reasonsOf(db, rows.slice(0, call.count("max-listed")!));
+    return { suppressions: list(call, rows, (row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) }), RANGE_REST) };
   }),
-  readCommand({ name: "modules", summary: "Where the files of the generated source start.", options: FILTER }, (db, call) => ({ modules: listModules(db, rangeOf(call), originsOf(call), call.space).map(module) })),
-  readCommand({ name: "operands", summary: "The operand expressions of instructions.", options: FILTER }, (db, call) => ({ operands: listOperands(db, rangeOf(call), originsOf(call), call.space).map(operand) })),
-  readCommand({ name: "patches", summary: "The code that a switch puts in.", options: { ...FILTER, switch: { kind: "text", value: "<switch>", help: "only the patches of this switch" } } }, (db, call) => ({
-    patches: listPatches(db, rangeOf(call), call.string("switch"), originsOf(call), call.space).map(patch),
+  readCommand({ name: "modules", summary: "Where the files of the generated source start.", options: { ...FILTER, ...LIST } }, (db, call) => ({ modules: list(call, listModules(db, rangeOf(call), originsOf(call), call.space), module, RANGE_REST) })),
+  readCommand({ name: "operands", summary: "The operand expressions of instructions.", options: { ...FILTER, ...LIST } }, (db, call) => ({ operands: list(call, listOperands(db, rangeOf(call), originsOf(call), call.space), operand, RANGE_REST) })),
+  readCommand({ name: "patches", summary: "The code that a switch puts in.", options: { ...FILTER, switch: { kind: "text", value: "<switch>", help: "only the patches of this switch" }, ...LIST } }, (db, call) => ({
+    patches: list(call, listPatches(db, rangeOf(call), call.string("switch"), originsOf(call), call.space), patch, RANGE_REST),
   })),
-  readCommand({ name: "switches", summary: "Each switch with the ranges of its patches." }, (db, call) => {
+  readCommand({ name: "switches", summary: "Each switch with the ranges of its patches.", options: LIST }, (db, call) => {
     const switches = new Map<string, PatchRow[]>();
     for (const row of listPatches(db, undefined, undefined, undefined, call.space)) switches.set(row.switch, [...(switches.get(row.switch) ?? []), row]);
-    return {
-      switches: [...switches].sort(([a], [b]) => (a < b ? -1 : 1)).map(([name, rows]) => ({ name, define: `--define ${name}=1`, patches: rows.map((row) => ({ start: formatC64Address(row.start), end: formatC64Address(row.end) })) })),
-    };
+    const show = ([name, rows]: [string, PatchRow[]]) => ({ name, define: `--define ${name}=1`, patches: rows.map((row) => ({ start: formatC64Address(row.start), end: formatC64Address(row.end) })) });
+    return { switches: list(call, [...switches].sort(([a], [b]) => (a < b ? -1 : 1)), show, MORE) };
   }),
-  readCommand({ name: "macros", summary: "The macros of the generated source.", options: { origin: OPTIONS.origin } }, (db, call) => ({ macros: listMacros(db, originsOf(call), call.space).map(macro) })),
-  readCommand({ name: "uses", summary: "The instructions written as a macro.", options: { ...FILTER, macro: { kind: "text", value: "<name>", help: "only the uses of this macro" } } }, (db, call) => ({
-    uses: listMacroUses(db, rangeOf(call), call.string("macro"), originsOf(call), call.space).map(macroUse),
+  readCommand({ name: "macros", summary: "The macros of the generated source.", options: { origin: OPTIONS.origin, ...LIST } }, (db, call) => ({ macros: list(call, listMacros(db, originsOf(call), call.space), macro, MORE) })),
+  readCommand({ name: "uses", summary: "The instructions written as a macro.", options: { ...FILTER, macro: { kind: "text", value: "<name>", help: "only the uses of this macro" }, ...LIST } }, (db, call) => ({
+    uses: list(call, listMacroUses(db, rangeOf(call), call.string("macro"), originsOf(call), call.space), macroUse, RANGE_REST),
   })),
-  readCommand({ name: "spaces", summary: "The address spaces that hold knowledge." }, (db) => ({ spaces: listSpaces(db) })),
+  readCommand({ name: "spaces", summary: "The address spaces that hold knowledge.", options: LIST }, (db, call) => ({ spaces: list(call, listSpaces(db), (space) => space, MORE) })),
   readCommand({ name: "program", summary: "The program in the knowledge: its segments and entry, and the coverage maps that coverage imported, with the ranges." }, (db, call) => {
     const image = programImage(db, call.space);
     const ranges = db === undefined ? [] : (db.prepare("SELECT kind, count(*) AS count FROM current_coverage WHERE space = ? GROUP BY kind ORDER BY kind").all(call.space) as Array<{ kind: string; count: number }>);
@@ -526,7 +545,7 @@ const READ_COMMANDS: CommandSpec[] = [
       name: "history",
       summary: "The rows at an address, of a name or of a macro, through all revisions, each with the reason and the evidence of its revision.",
       subjects: [{ ...ADDRESS, optional: true }],
-      options: { name: { kind: "text", value: "<name>", help: "the history of a name in place of an address" }, macro: { kind: "text", value: "<name>", help: "the history of a macro in place of an address" } },
+      options: { name: { kind: "text", value: "<name>", help: "the history of a name in place of an address" }, macro: { kind: "text", value: "<name>", help: "the history of a macro in place of an address" }, ...LIST },
       notes: "Give exactly one of <address>, --name and --macro.",
     },
     (db, call) => {
@@ -534,23 +553,20 @@ const READ_COMMANDS: CommandSpec[] = [
       const macroName = call.string("macro");
       if ([call.subjects.length > 0, name !== undefined, macroName !== undefined].filter(Boolean).length !== 1) throw new UsageError("history needs exactly one of <address>, --name and --macro");
       const entries = macroName !== undefined ? historyOfMacro(db, macroName, call.space) : name !== undefined ? historyNamed(db, name, call.space) : historyAt(db, call.parseAddress(call.subject(0), "<address>"), call.space);
-      return { history: entries.map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })) };
+      return { history: list(call, entries, (entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) }), MORE) };
     },
   ),
   readCommand(
-    { name: "revisions", summary: "The revisions, newest first.", options: { limit: { kind: "count", value: "<n>", min: 1, max: 100_000, help: "at most n revisions" }, before: { kind: "text", value: "<revision>", help: "only the revisions before this one" } } },
+    { name: "revisions", summary: "The revisions, newest first.", options: { before: { kind: "text", value: "<revision>", help: "only the revisions before this one" }, ...LIST } },
     (db, call) => {
-      const options: { limit?: number; before?: string } = {};
-      const limit = call.count("limit");
-      if (limit !== undefined) options.limit = limit;
       const before = call.string("before");
-      if (before !== undefined) options.before = before;
-      return { revisions: revisions(db, options) };
+      const rows = revisions(db, before === undefined ? { limit: ALL } : { limit: ALL, before });
+      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] }, (db, call) => {
+  readCommand({ name: "revision", summary: "The rows that one revision added and closed.", subjects: [REVISION], options: LIST }, (db, call) => {
     const changes = revision(db, call.subject(0));
-    return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
+    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) => {
     const range = rangeOf(call);
@@ -579,14 +595,14 @@ 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" } },
+      options: { out: { ...OPTIONS.out, 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>");
       const lines = listing(listingSource(db, call.space), start, end);
       const out = call.string("out");
       if (out !== undefined) return { lines: lines.length, ...writeReported(out, listingText(lines), { what: "--out" }) };
-      return { lines: lines.map((row) => ({ ...row, address: formatC64Address(row.address) })) };
+      return { lines: list(call, lines, (row) => ({ ...row, address: formatC64Address(row.address) }), "a larger --max-listed, a smaller <range>, or --out <file> for all lines") };
     },
   ),
 ];
@@ -821,7 +837,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
       };
     },
   ),
-  writeCommand({ name: "revert", summary: "Undoes one revision with a new revision.", subjects: [REVISION] }, (call) => {
+  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 });

package/skills/c64-memory-map/SKILL.md

@@ -31,7 +31,7 @@ node <skill>/scripts/memory-map.ts export --out src/hw.asm
 |---|---|
 | `at <address> ...` | For each address: `kind` (`platform` or `application`), the area, the name and the meaning. |
 | `decode <register> <value>` | The meaning of the value. Use `--bank` with the value of `$DD00` to get the addresses for `$D018`. The decoders are for `$01`, `$D010`, `$D011`, `$D015` to `$D01F`, `$D016`, `$D018`, `$DC0D`, `$DD00` and `$DD0D`. |
-| `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | All entries of that group. |
+| `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | The entries of that group as a list: `count` and `listed`. `--max-listed` limits `listed`. The default is 50. |
 | `export --out <file>` | Writes all platform names to a project file as an ACME include: one line for each name, with its meaning as a comment. A zero-page name is `NAME = $xx`. Other names are `NAME = $xxxx`. |
 
 Write a value for `decode` and `--bank` as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.

package/skills/c64-memory-map/scripts/memory-map.ts

@@ -6,7 +6,7 @@ import { formatC64Address, formatC64Byte } from "#src/c64.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
 import { decode, IO, lookup, platformNames, ROM, SYSTEM, type Entry } from "#src/platform.ts";
-import { OPTIONS, runScript, UsageError } from "#src/script.ts";
+import { listed, OPTIONS, runScript, UsageError } from "#src/script.ts";
 
 const show = (entry: Entry) => ({ start: formatC64Address(entry.start), ...(entry.end !== entry.start ? { end: formatC64Address(entry.end) } : {}), name: entry.name, meaning: entry.meaning });
 
@@ -61,10 +61,11 @@ await runScript({
       name: "list",
       summary: "The registers of a chip, the KERNAL jump table, or the system areas.",
       subjects: [{ name: "<list>", help: `one of ${Object.keys(LISTS).join(", ")}` }],
+      options: { "max-listed": OPTIONS["max-listed"] },
       run: (call) => {
         const list = LISTS[call.subject(0)];
         if (list === undefined) throw new UsageError(`<list> must be one of ${Object.keys(LISTS).join(", ")}, not ${call.subject(0)}`);
-        return { entries: list().map(show) };
+        return { entries: listed(list(), call.count("max-listed")!, show, "a larger --max-listed, or memory-map.ts export --out <file> for every platform name") };
       },
     },
     {

package/skills/c64-provenance/SKILL.md

@@ -38,7 +38,7 @@ node <skill>/scripts/provenance.ts leftovers --out .c64-re-tools/local/leftovers
 
 | Option | Meaning |
 |---|---|
-| `--shift 2:-256` | Move release 2 (the first release is 1) by -256 bytes. Use it again for more releases. |
+| `--shift 2:-256` | Move release 2 (the first release is 1) by -256 bytes. Use it again for more releases. Give one shift for each release. |
 | `--range '$0900-$09ff'` | Compare only the addresses in this range. |
 | `--frames 600` | Run each release for this many frames, and give each listed difference its runtime evidence. |
 | `--steps .c64-re-tools/local/start-game.json` | With `--frames`: a JSON list of action steps to run before the frames, for example a key to start the game. The steps are the steps of a c64-unpacker steps file. |
@@ -96,7 +96,7 @@ Use `separate` when you have only one release. It reads the program, its stages
 - `ranges`: the program in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. The last stage is the program. An earlier stage is a depacker, an intro or a loader. Only a capture of c64-unpacker `capture` has stages. For a program from `loads` or a PRG, `noStages` tells this.
 - `access`: from the coverage of the knowledge: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs. A `read` byte right after executed code, or at a return address, can be a dummy read of the 6502 that the program does not use.
 - `codeRegions.total`: the number of code regions in the knowledge.
-- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
+- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. A region also reaches the code after it when its last instruction is not RTS, RTI, JMP, BRK or JAM: the CPU continues there. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
 - `outside`: RAM outside the program that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write. A `generated` range can have gaps of two bytes or less: these are operand bytes.
 
 Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed` (default 50). `--out` writes all of them and the result shows the file as `{out, bytes, sha256}`. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
@@ -112,7 +112,7 @@ Use `leftovers` to find what the program holds in addition to its working code.
 | `fill` | One byte that repeats, at least 16 times, or a pattern of two to four bytes that repeats, at least 32 bytes in total. `pattern` is the repeated bytes. |
 | `residue` | Bytes that no run touched and that are no text, BASIC, fill or code region. `bytes` shows the first 16 bytes. |
 | `copies` | Bytes that are the same as earlier bytes of the program, at least 32 bytes. `copyOf` is the address of the earlier bytes. |
-| `deadCode` | Code regions of the knowledge that no call or jump reaches from the entry, and that no run executed. |
+| `deadCode` | Code regions of the knowledge that the entry does not reach, as in `codeRegions.unreachable` of `separate`, and that no run executed. |
 
 Text from another computer can show the tools of the developer:
 
@@ -162,7 +162,8 @@ To save a routine:
    - `--name` is the name of the routine and of its file. When you do not give it, the script uses the user or LLM name at the start.
    - `--title` is the title of the routine. When you do not give it, the script uses the module title.
    - A routine has at least 16 bytes. Its last instruction must end in the range.
-3. Read `leftOut`. It lists the rows that the file does not keep, and why. For example, the file does not keep an operand expression that uses a name outside the routine.
+3. The result shows the routine file as `{out, bytes, sha256}`. `out` is relative to the project folder.
+4. Read `leftOut`. It lists the rows that the file does not keep, and why. For example, the file does not keep an operand expression that uses a name outside the routine.
 
 To find the routines in a program: