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

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

@@ -0,0 +1,492 @@
+// The c64-knowledge script: reads and writes .c64-re-tools/knowledge.db in the
+// project directory (the working directory) and prints one compact JSON result.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { DatabaseSync } from "node:sqlite";
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
+import { historyAt, historyNamed, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
+import {
+  at,
+  currentRevision,
+  listComments,
+  listModules,
+  listSpaces,
+  listReferences,
+  listRegions,
+  listSuppressions,
+  listSymbols,
+  search,
+  type CommentRow,
+  type ModuleRow,
+  type ReferenceRow,
+  type RegionRow,
+  type SuppressionRow,
+  type SymbolRow,
+} from "#src/knowledge/read.ts";
+import {
+  COMMENT_PLACEMENTS,
+  DEFAULT_SPACE,
+  EVIDENCE_KINDS,
+  ORIGINS,
+  REFERENCE_KINDS,
+  REGION_TYPES,
+  SPACE,
+  SYMBOL_KINDS,
+  type CommentPlacement,
+  type Origin,
+  type ReferenceKind,
+  type RegionType,
+  type SymbolKind,
+} from "#src/knowledge/schema.ts";
+import {
+  addReference,
+  applyBatch,
+  classifyRegion,
+  removeComment,
+  removeModule,
+  removeReference,
+  removeSymbol,
+  renameSymbol,
+  revert,
+  setComment,
+  setModule,
+  unclassifyRegion,
+  type BatchOperation,
+  type Evidence,
+  type WriteContext,
+} from "#src/knowledge/write.ts";
+import { runScript, UsageError } from "#src/script.ts";
+
+const USAGE = `knowledge.ts <command> [arguments] [options]
+
+Read (no database needed):
+  at <address>                        everything known at one address
+  search <text>                       symbol names and comment texts
+  symbols [--start A --end A --kind K --origin O]
+  regions [--start A --end A --type T --origin O]
+  comments [--start A --end A --origin O]
+  references [--start A --end A --kind K --origin O]
+  suppressions [--start A --end A]   places that removals keep free of analyzer facts
+  modules [--start A --end A --origin O]   where the files of generated source start
+  spaces                              the address spaces that hold knowledge
+  history <address> | history --name <name>
+  revisions [--limit N --before N]
+  revision <id>
+  export --out <file> [--start A --end A --origin O]   all current knowledge to a project file
+
+Every command takes --space S: c64 (the default), drive8 for code in the 1541
+drive, or bank0 to bank255 for cartridge banks. A write in a batch can name its
+own space.
+
+Read option --origin O: user, llm, dxa, ghidra, heuristic, semantic (user and
+llm) or analyzer (dxa, ghidra and heuristic), or a comma list. search takes it too.
+
+Write (one revision each; creates the database when needed):
+  rename <address> <name> [--kind K]
+  remove-symbol <address>
+  classify <start> <end> <type> [--element N]
+  unclassify <start> <end>
+  comment <address> <line|side> <text>
+  uncomment <address> <line|side>
+  reference <from> <to> <kind>
+  unreference <from> <to> <kind>
+  module <start> <file.asm> [--title T]   a file of generated source starts here
+  unmodule <start>
+  revert <revision>
+  apply <file>             many writes from a JSON file ('-' reads standard input),
+                           all as one revision, or none when one is refused
+
+Write options:
+  --reason <text>          why, kept with the revision
+  --evidence <kind:ref>    what the change rests on: coverage:<file>, test:<file>,
+                           file:<file> or note:<text> (repeatable)
+  --expect-revision <N>    refuse the write if knowledge changed after revision N
+  --origin user|llm        who decided (default llm)
+
+Addresses are $ and four hex digits; quote them in a shell: '$2100'.`;
+
+function address(value: string | undefined, what = "address"): number {
+  if (value === undefined) throw new UsageError(`${what} is missing`);
+  try {
+    return parseC64Address(value);
+  } catch {
+    throw new UsageError(`${what} must be $ followed by four hex digits, for example '$2100', not ${value}`);
+  }
+}
+
+function oneOf<T extends string>(values: readonly T[], value: string | undefined, what: string): T {
+  if (value === undefined || !(values as readonly string[]).includes(value)) throw new UsageError(`${what} must be one of: ${values.join(", ")}`);
+  return value as T;
+}
+
+function integer(value: string | undefined, what: string): number {
+  if (value === undefined || !/^\d+$/.test(value)) throw new UsageError(`${what} must be a whole number`);
+  return Number(value);
+}
+
+// Output shapes: addresses as $xxxx, nothing internal.
+/** The space of a row, shown only when it is not the C64 (D53). */
+const spaceOf = (row: { space: string }) => (row.space === "c64" ? {} : { space: row.space });
+const symbol = (row: SymbolRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), name: row.name, kind: row.kind, origin: row.origin, revision: row.revision });
+const region = (row: RegionRow) => ({
+  ...spaceOf(row),
+  start: formatC64Address(row.start),
+  end: formatC64Address(row.end),
+  type: row.type,
+  ...(row.element === undefined ? {} : { element: row.element, count: (row.end - row.start + 1) / row.element }),
+  origin: row.origin,
+  revision: row.revision,
+});
+const comment = (row: CommentRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), placement: row.placement, text: row.text, origin: row.origin, revision: row.revision });
+const module = (row: ModuleRow) => ({ ...spaceOf(row), start: formatC64Address(row.start), file: row.file, ...(row.title === undefined ? {} : { title: row.title }), origin: row.origin, revision: row.revision });
+const reference = (row: ReferenceRow) => ({ ...spaceOf(row), from: formatC64Address(row.from), to: formatC64Address(row.to), kind: row.kind, origin: row.origin, revision: row.revision });
+function suppression(row: SuppressionRow) {
+  const place =
+    row.entity === "symbol"
+      ? { address: formatC64Address(row.start) }
+      : row.entity === "region"
+        ? { start: formatC64Address(row.start), end: formatC64Address(row.end) }
+        : { from: formatC64Address(row.start), to: formatC64Address(row.to!), kind: row.kind! };
+  return { ...spaceOf(row), suppresses: row.entity, ...place, origin: row.origin, revision: row.revision };
+}
+
+function historyEntry(entry: HistoryEntry) {
+  const shown =
+    entry.entity === "symbol"
+      ? symbol(entry.row)
+      : entry.entity === "region"
+        ? region(entry.row)
+        : entry.entity === "comment"
+          ? comment(entry.row)
+          : entry.entity === "reference"
+            ? reference(entry.row)
+            : entry.entity === "module"
+              ? module(entry.row)
+              : suppression(entry.row);
+  const { revision: _revision, ...row } = shown;
+  return { entity: entry.entity, ...row, fromRevision: entry.from, ...(entry.to === undefined ? {} : { toRevision: entry.to }) };
+}
+
+/** The reason of each revision that wrote one of the rows. */
+function reasonsOf(db: DatabaseSync | undefined, rows: SuppressionRow[]): Map<number, string> {
+  const reasons = new Map<number, string>();
+  const query = db?.prepare("SELECT description FROM revisions WHERE id = ?");
+  for (const { revision } of rows) {
+    if (query === undefined || reasons.has(revision)) continue;
+    const found = query.get(revision) as { description: string | null } | undefined;
+    if (found?.description != null) reasons.set(revision, found.description);
+  }
+  return reasons;
+}
+
+function run(argv: string[]): unknown {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      start: { type: "string" },
+      end: { type: "string" },
+      kind: { type: "string" },
+      type: { type: "string" },
+      name: { type: "string" },
+      limit: { type: "string" },
+      before: { type: "string" },
+      reason: { type: "string" },
+      "expect-revision": { type: "string" },
+      origin: { type: "string" },
+      element: { type: "string" },
+      evidence: { type: "string", multiple: true },
+      out: { type: "string" },
+      title: { type: "string" },
+      space: { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  const [command, ...args] = positionals;
+  if (values.help || command === undefined) throw new UsageError("");
+  const range = { start: values.start === undefined ? 0x0000 : address(values.start, "--start"), end: values.end === undefined ? 0xffff : address(values.end, "--end") };
+  if (values.space !== undefined && !SPACE.test(values.space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
+  const space = values.space ?? DEFAULT_SPACE;
+
+  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "spaces", "history", "revisions", "revision", "export"]);
+  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "revert", "apply"]);
+  // Refuse a mistyped command before anything opens, so no database appears by accident.
+  if (!read.has(command) && !write.has(command)) throw new UsageError(`unknown command: ${command}`);
+  if (read.has(command)) {
+    const origins = values.origin === undefined ? undefined : originFilter(values.origin);
+    if (command === "export" && values.out === undefined) throw new UsageError("export needs --out <file>");
+    const db = openForRead();
+    try {
+      switch (command) {
+        case "at": {
+          const known = at(db, address(args[0]), space);
+          return {
+            ...(space === DEFAULT_SPACE ? {} : { space }),
+            address: formatC64Address(known.address),
+            ...(known.symbol === undefined ? {} : { symbol: symbol(known.symbol) }),
+            ...(known.region === undefined ? {} : { region: region(known.region) }),
+            comments: known.comments.map(comment),
+            referencesFrom: known.referencesFrom.map(reference),
+            referencesTo: known.referencesTo.map(reference),
+            ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
+            revision: known.revision,
+          };
+        }
+        case "search": {
+          if (args[0] === undefined || args[0] === "") throw new UsageError("search needs text");
+          const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"), origins, space);
+          return { symbols: found.symbols.map(symbol), comments: found.comments.map(comment) };
+        }
+        case "symbols":
+          return { symbols: listSymbols(db, range, values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind"), origins, space).map(symbol) };
+        case "regions":
+          return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type"), origins, space).map(region) };
+        case "comments":
+          return { comments: listComments(db, range, origins, space).map(comment) };
+        case "references":
+          return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
+        case "export": {
+          const exported = {
+            revision: currentRevision(db),
+            ...(space === DEFAULT_SPACE ? {} : { space }),
+            symbols: listSymbols(db, range, undefined, origins, space).map(symbol),
+            regions: listRegions(db, range, undefined, origins, space).map(region),
+            comments: listComments(db, range, origins, space).map(comment),
+            references: listReferences(db, range, undefined, origins, space).map(reference),
+            suppressions: listSuppressions(db, range, space).map(suppression),
+            modules: listModules(db, range, origins, space).map(module),
+          };
+          const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
+          writeProjectFile(values.out!, bytes, { what: "--out" });
+          return {
+            out: values.out,
+            bytes: bytes.length,
+            counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length },
+            revision: exported.revision,
+          };
+        }
+        case "suppressions": {
+          const rows = listSuppressions(db, range, space);
+          const reasons = reasonsOf(db, rows);
+          return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
+        }
+        case "modules":
+          return { modules: listModules(db, range, origins, space).map(module) };
+        case "spaces":
+          return { spaces: listSpaces(db) };
+        case "history":
+          // Each row with the reason and the evidence of the revision that wrote it (F-26).
+          return {
+            history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
+          };
+        case "revisions": {
+          const options: { limit?: number; before?: number } = {};
+          if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
+          if (values.before !== undefined) options.before = integer(values.before, "--before");
+          return { revisions: revisions(db, options) };
+        }
+        default: {
+          const changes = revision(db, integer(args[0], "revision"));
+          return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
+        }
+      }
+    } finally {
+      db?.close();
+    }
+  }
+
+  const context: WriteContext = { origin: values.origin === undefined ? "llm" : oneOf(["user", "llm"] as const, values.origin, "--origin") };
+  if (values.reason !== undefined) context.description = values.reason;
+  if (values["expect-revision"] !== undefined) context.expectedRevision = integer(values["expect-revision"], "--expect-revision");
+  if (values.evidence !== undefined) context.evidence = values.evidence.map(evidenceOf);
+  // Every argument is checked before the database opens: a refused write creates no database.
+  if (values.title !== undefined && command !== "module") throw new UsageError("--title works only with module");
+  const operation = command === "apply" ? applyOperation(args, context, space) : writeOperation(command, args, values.kind, values.element, context, values.title, space);
+  return withWrite(operation);
+}
+
+/** --origin for reads: one origin, semantic (user and llm), analyzer (dxa and ghidra), or a comma list. */
+function originFilter(value: string): Origin[] {
+  const origins = new Set<Origin>();
+  for (const part of value.split(",")) {
+    if (part === "semantic") origins.add("user").add("llm");
+    else if (part === "analyzer") origins.add("dxa").add("ghidra").add("heuristic");
+    else origins.add(oneOf(ORIGINS, part, "--origin"));
+  }
+  return [...origins];
+}
+
+/** --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows. */
+function evidenceOf(value: string): Evidence {
+  const colon = value.indexOf(":");
+  const kind = oneOf(EVIDENCE_KINDS, colon < 0 ? value : value.slice(0, colon), "--evidence kind");
+  const ref = colon < 0 ? "" : value.slice(colon + 1);
+  if (ref === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
+  if (kind === "note") return { kind, ref };
+  return { kind, ref, sha256: createHash("sha256").update(readProjectFile(ref).bytes).digest("hex") };
+}
+
+/** apply <file>: the batch as BatchOperation values, checked before the database opens. */
+function applyOperation(args: string[], context: WriteContext, space: string): WriteOperation {
+  if (args.length !== 1) throw new UsageError("apply needs one file, or - for standard input");
+  const text = args[0] === "-" ? readFileSync(0, "utf8") : readProjectFile(args[0]!).bytes.toString("utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`the batch is not JSON: ${(error as Error).message}`);
+  }
+  if (!Array.isArray(parsed)) throw new UsageError("the batch is a JSON list of writes, for example [{\"op\": \"rename\", \"address\": \"$2100\", \"name\": \"update_player\"}]");
+  const operations = parsed.map((item, index) => batchOperation(item, `write ${index + 1}`, space));
+  return (db) => {
+    const applied = applyBatch(db, context, operations);
+    // replaced: each write that replaced a row of another origin, with that row as previous gives it for one write (b2/07).
+    const replaced = applied.steps.flatMap((step, index) =>
+      step.previous === undefined ? [] : [{ write: index + 1, op: operations[index]!.op, previous: Array.isArray(step.previous) ? step.previous.map(region) : symbol(step.previous) }],
+    );
+    return { revision: applied.revision, writes: applied.steps.length, replaced };
+  };
+}
+
+const BATCH_FIELDS: Record<BatchOperation["op"], string[]> = {
+  rename: ["address", "name", "kind"],
+  "remove-symbol": ["address"],
+  classify: ["start", "end", "type", "element"],
+  unclassify: ["start", "end"],
+  comment: ["address", "placement", "text"],
+  uncomment: ["address", "placement"],
+  reference: ["from", "to", "kind"],
+  unreference: ["from", "to", "kind"],
+  module: ["start", "file", "title"],
+  unmodule: ["start"],
+};
+
+/** One write of a batch. A write names its own space, or takes the one of --space. */
+function batchOperation(item: unknown, at: string, space: string): BatchOperation {
+  const operation = batchFields(item, at);
+  const own = (item as Record<string, unknown>).space;
+  if (own !== undefined && typeof own !== "string") throw new UsageError(`${at}: space must be a string`);
+  return { ...operation, space: own ?? space };
+}
+
+/** The fields of one write of a batch, with its addresses parsed. */
+function batchFields(item: unknown, at: string): BatchOperation {
+  if (typeof item !== "object" || item === null || Array.isArray(item)) throw new UsageError(`${at}: a write is an object with op`);
+  const fields = item as Record<string, unknown>;
+  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 UsageError(`${at}: ${op} takes ${BATCH_FIELDS[op].join(", ")}, not ${unknown.join(", ")}`);
+  const text = (key: string) => {
+    if (typeof fields[key] !== "string") throw new UsageError(`${at}: ${key} must be a string`);
+    return fields[key] as string;
+  };
+  const place = (key: string) => address(text(key), `${at}: ${key}`);
+  switch (op) {
+    case "rename":
+      return { op, address: place("address"), name: text("name"), ...(fields.kind === undefined ? {} : { kind: oneOf(SYMBOL_KINDS, text("kind"), `${at}: kind`) }) };
+    case "remove-symbol":
+      return { op, address: place("address") };
+    case "classify": {
+      if (fields.element !== undefined && typeof fields.element !== "number") throw new UsageError(`${at}: element must be a number`);
+      return { op, start: place("start"), end: place("end"), type: oneOf(REGION_TYPES, text("type"), `${at}: type`), ...(fields.element === undefined ? {} : { element: fields.element as number }) };
+    }
+    case "unclassify":
+      return { op, start: place("start"), end: place("end") };
+    case "comment":
+      return { op, address: place("address"), placement: oneOf(COMMENT_PLACEMENTS, text("placement"), `${at}: placement`), text: text("text") };
+    case "uncomment":
+      return { op, address: place("address"), placement: oneOf(COMMENT_PLACEMENTS, text("placement"), `${at}: placement`) };
+    case "module":
+      return { op, start: place("start"), file: text("file"), ...(fields.title === undefined ? {} : { title: text("title") }) };
+    case "unmodule":
+      return { op, start: place("start") };
+    default:
+      return { op, from: place("from"), to: place("to"), kind: oneOf(REFERENCE_KINDS, text("kind"), `${at}: kind`) };
+  }
+}
+
+type WriteOperation = (db: DatabaseSync) => unknown;
+
+function writeOperation(command: string, args: string[], kind: string | undefined, element: string | undefined, context: WriteContext, title: string | undefined, space: string): WriteOperation {
+  switch (command) {
+    case "rename": {
+      if (args[1] === undefined) throw new UsageError("name is missing");
+      const request: { space: string; address: number; name: string; kind?: SymbolKind } = { space, address: address(args[0]), name: args[1] };
+      if (kind !== undefined) request.kind = oneOf(SYMBOL_KINDS, kind, "--kind");
+      return (db) => {
+        const result = renameSymbol(db, context, request);
+        return { revision: result.revision, symbol: symbol(result.current), ...(result.previous === undefined ? {} : { previous: symbol(result.previous) }) };
+      };
+    }
+    case "remove-symbol": {
+      const request = { space, address: address(args[0]) };
+      return (db) => ({ revision: removeSymbol(db, context, request).revision });
+    }
+    case "classify": {
+      const request = {
+        space,
+        start: address(args[0], "start"),
+        end: address(args[1], "end"),
+        type: oneOf(REGION_TYPES, args[2], "type") as RegionType,
+        ...(element === undefined ? {} : { element: integer(element, "--element") }),
+      };
+      return (db) => {
+        const result = classifyRegion(db, context, request);
+        return { revision: result.revision, regions: result.current.map(region), ...(result.previous === undefined ? {} : { previous: result.previous.map(region) }) };
+      };
+    }
+    case "unclassify": {
+      const request = { space, start: address(args[0], "start"), end: address(args[1], "end") };
+      return (db) => ({ revision: unclassifyRegion(db, context, request).revision });
+    }
+    case "comment": {
+      if (args.length < 3) throw new UsageError("text is missing");
+      const request = { space, address: address(args[0]), placement: oneOf(COMMENT_PLACEMENTS, args[1], "placement") as CommentPlacement, text: args.slice(2).join(" ") };
+      return (db) => {
+        const result = setComment(db, context, request);
+        return { revision: result.revision, comment: comment(result.current) };
+      };
+    }
+    case "uncomment": {
+      const request = { space, address: address(args[0]), placement: oneOf(COMMENT_PLACEMENTS, args[1], "placement") };
+      return (db) => ({ revision: removeComment(db, context, request).revision });
+    }
+    case "reference": {
+      const request = { space, from: address(args[0], "from"), to: address(args[1], "to"), kind: oneOf(REFERENCE_KINDS, args[2], "kind") as ReferenceKind };
+      return (db) => {
+        const result = addReference(db, context, request);
+        return { revision: result.revision, reference: reference(result.current) };
+      };
+    }
+    case "unreference": {
+      const request = { space, from: address(args[0], "from"), to: address(args[1], "to"), kind: oneOf(REFERENCE_KINDS, args[2], "kind") };
+      return (db) => ({ revision: removeReference(db, context, request).revision });
+    }
+    case "module": {
+      if (args[1] === undefined) throw new UsageError("file is missing");
+      const request = { space, start: address(args[0], "start"), file: args[1], ...(title === undefined ? {} : { title }) };
+      return (db) => {
+        const result = setModule(db, context, request);
+        return { revision: result.revision, module: module(result.current) };
+      };
+    }
+    case "unmodule": {
+      const request = { space, start: address(args[0], "start") };
+      return (db) => ({ revision: removeModule(db, context, request).revision });
+    }
+    case "revert": {
+      const request = { revision: integer(args[0], "revision") };
+      return (db) => ({ revision: revert(db, context, request).revision });
+    }
+    default:
+      throw new UsageError(`unknown command: ${command}`);
+  }
+}
+
+await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });

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

@@ -0,0 +1,79 @@
+---
+name: c64-memory-map
+description: Use this skill to find what a C64 address means on the platform. Examples are a VIC-II, SID or CIA register, a KERNAL routine, a vector or a system variable. It also decodes the value of a hardware register, for example the memory configuration in $01 or the screen address in $D018. It tells you when an address has no platform meaning and belongs to the application.
+---
+
+# c64-memory-map
+
+## Purpose
+
+Give the C64 platform meaning of an address or of a register value.
+
+This skill does not read the emulator and does not change project knowledge.
+
+## Inputs
+
+- One or more addresses.
+- Or a register and a value to decode.
+
+## Tools / execution path
+
+The script looks up local reference data. It does not use the host runtime.
+
+```
+node <skill>/scripts/memmap.ts at '$d020' '$0314' '$ffd2'
+node <skill>/scripts/memmap.ts decode '$d018' '$15' --bank '$97'
+node <skill>/scripts/memmap.ts list vic
+node <skill>/scripts/memmap.ts export --out src/hw.asm
+```
+
+| Command | Result |
+|---|---|
+| `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`. |
+| `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | All entries of that group. |
+| `export --out <file>` | Writes all platform names to a project file as an ACME include: one `NAME = $xxxx` line for each name, with its meaning as a comment. |
+
+Write an address or a value as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
+
+The script prints one JSON object.
+
+## Workflow
+
+1. Run `at` for the addresses in the code or the question.
+2. Read `kind`:
+   - `platform`: the C64 gives the address a meaning. Read `name` and `meaning`.
+   - `application`: the address has no platform meaning. The program decides its use. Find its use with the c64-static-analysis or c64-emulator skill.
+3. For an I/O register, `mirrorOf` shows the register that a mirror address repeats. `visible` tells that an address in `$D000`-`$DFFF` is visible only when `$01` shows I/O at `$D000`. This area holds the chip registers, the color RAM and the cartridge I/O areas.
+4. For a byte in a multi-byte entry, for example the high byte of a vector, `entryStart` gives the first address of the entry.
+5. To understand a value in a register, run `decode`. For the memory configuration, decode the value of `$01`.
+6. For source that you write by hand, run `export` and include the file with `!source`. The c64-source skill uses the same names without the file.
+
+The decoders are for `$01`, `$D010`, `$D011`, `$D015` to `$D01F` (the sprite and interrupt bits), `$D016`, `$D018`, `$DC0D`, `$DD00` and `$DD0D`.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Platform facts are reference data. Do not store them as project knowledge.
+
+A conclusion about the application can be project knowledge. For example: "the program writes its own IRQ handler address to `$0314`". Record it with the c64-knowledge skill.
+
+## Result
+
+The platform meaning of each address, or the decoded meaning of a register value. For `export`: the file, the count of names and the bytes.
+
+The exit status is 0 for a result. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `kind: application`: this is not a failure. The address has no platform meaning.
+- `invalid-input`: the address, the register or the value is not correct, or no decoder exists for the register. Read the message.
+
+Some registers have a different meaning for a read and for a write, for example `$DC0D`. The decoded result shows both.
+
+## Handoffs
+
+- The value of an address at run time → c64-emulator
+- A conclusion about the application → c64-knowledge

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

@@ -0,0 +1,92 @@
+// The c64-memory-map script: the platform meaning of C64 addresses and of
+// values in platform registers. Local lookup only; nothing is stored. export
+// writes the platform names to a project file as an ACME include (D52).
+
+import { parseArgs } from "node:util";
+
+import { writeProjectFile } from "#src/host-client/transfer.ts";
+import { decode, IO, lookup, platformNames, ROM, SYSTEM, type Entry } from "#src/platform.ts";
+import { runScript, UsageError } from "#src/script.ts";
+
+const USAGE = `memmap.ts at <address> [<address> ...]
+memmap.ts decode <register> <value> [--bank <$dd00 value>]
+memmap.ts list <vic|sid|cia1|cia2|kernal|system>
+memmap.ts export --out <file>     the platform names as an ACME include (NAME = $xxxx)
+
+Addresses and values are $ and hex digits, decimal, or % and binary digits.
+The result is one JSON object.`;
+
+const hex = (value: number, digits = 4) => `$${value.toString(16).padStart(digits, "0")}`;
+
+function number(text: string, max: number, what: string): number {
+  let value = Number.NaN;
+  if (/^\$[0-9a-f]{1,4}$/i.test(text)) value = Number.parseInt(text.slice(1), 16);
+  else if (/^%[01]{1,16}$/.test(text)) value = Number.parseInt(text.slice(1), 2);
+  else if (/^\d{1,5}$/.test(text)) value = Number(text);
+  if (!(value >= 0 && value <= max)) throw new UsageError(`${what} must be from 0 to ${hex(max, max > 0xff ? 4 : 2)}, not ${text}`);
+  return value;
+}
+
+const show = (entry: Entry) => ({ start: hex(entry.start), ...(entry.end !== entry.start ? { end: hex(entry.end) } : {}), name: entry.name, meaning: entry.meaning });
+
+function run(argv: string[]): unknown {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { bank: { type: "string" }, out: { type: "string" }, help: { type: "boolean" } } });
+  if (values.help || positionals.length === 0) throw new UsageError("");
+  const [command, ...rest] = positionals;
+  switch (command) {
+    case "at": {
+      if (rest.length === 0) throw new UsageError("give at least one address");
+      return {
+        addresses: rest.map((text) => {
+          const found = lookup(number(text, 0xffff, "an address"));
+          // The chip registers, color RAM and the cartridge I/O areas show only while $01 maps I/O in.
+          const io = found.address >= 0xd000 && found.address <= 0xdfff;
+          return {
+            ...found,
+            address: hex(found.address),
+            ...(found.mirrorOf === undefined ? {} : { mirrorOf: hex(found.mirrorOf) }),
+            ...(found.entryStart === undefined ? {} : { entryStart: hex(found.entryStart) }),
+            ...(io ? { visible: "when $01 shows I/O at $D000 (the default)" } : {}),
+          };
+        }),
+      };
+    }
+    case "decode": {
+      if (rest.length !== 2) throw new UsageError("decode takes a register and a value");
+      const register = number(rest[0]!, 0xffff, "the register");
+      const value = number(rest[1]!, 0xff, "the value");
+      const bank = values.bank === undefined ? undefined : number(values.bank, 0xff, "--bank");
+      try {
+        return { register: hex(register), value: hex(value, 2), name: lookup(register).name, ...decode(register, value, bank) };
+      } catch (error) {
+        if (error instanceof RangeError) throw new UsageError(error.message);
+        throw error;
+      }
+    }
+    case "list": {
+      const lists: Record<string, Entry[]> = {
+        vic: IO[0]!.registers,
+        sid: IO[1]!.registers,
+        cia1: IO[2]!.registers,
+        cia2: IO[3]!.registers,
+        kernal: ROM,
+        system: SYSTEM,
+      };
+      const list = lists[rest[0] ?? ""];
+      if (list === undefined || rest.length !== 1) throw new UsageError(`list takes one of ${Object.keys(lists).join(", ")}`);
+      return { entries: list.map(show) };
+    }
+    case "export": {
+      if (rest.length !== 0 || values.out === undefined) throw new UsageError("export takes --out <file> and nothing else");
+      const names = platformNames();
+      const lines = ["; C64 platform names from the c64-memory-map skill, for ACME.", ...names.map((item) => `${item.name} = ${hex(item.address, item.address < 0x100 ? 2 : 4)}`.padEnd(24) + `; ${item.meaning}`)];
+      const bytes = Buffer.from(`${lines.join("\n")}\n`, "utf8");
+      writeProjectFile(values.out, bytes, { what: "--out" });
+      return { out: values.out, names: names.length, bytes: bytes.length };
+    }
+    default:
+      throw new UsageError(`unknown command ${command}`);
+  }
+}
+
+await runScript(() => run(process.argv.slice(2)), { usage: USAGE });