@henols/c64-re-tools 2.0.0-rc.8 → 2.0.0

package/skills/c64-unpacker/scripts/unpack.ts

@@ -4,7 +4,7 @@
 // cruncher whose bytes look like code. "capture" runs the program in an
 // emulator until it reaches a given address (the unpacked entry point) and
 // writes the memory into the project. "loads" captures each part of a
-// multi-load program (D53). No native unpack tool is used.
+// multi-load program. No native unpack tool is used.
 
 import { parseArgs } from "node:util";
 
@@ -17,14 +17,14 @@ import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts"
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { basicStart, inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./evidence.ts";
-import { loads, readLoadSteps } from "./loads.ts";
-import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, type Range } from "./stages.ts";
-import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./machine.ts";
+import { basicStart, inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
+import { loads, readLoadSteps } from "./lib/loads.ts";
+import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, withoutRanges, type Range } from "./lib/stages.ts";
+import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./lib/machine.ts";
 
 const USAGE = `unpack.ts inspect <program.prg>
 unpack.ts trace <program.prg> [--frames <n>] [--entry <address>] [--steps <file>]
-unpack.ts capture <program.prg> --until <address> --out <dir> [--range <start> <end>] [--timeout-frames <n>] [--entry <address>] [--steps <file>] [--min-stage <bytes>]
+unpack.ts capture <program.prg> --until <address> --out <dir> [--range <start> <end>] [--exclude <start>-<end>]... [--timeout-frames <n>] [--entry <address>] [--steps <file>] [--min-stage <bytes>]
 unpack.ts stages <program.prg> [--frames <n>] [--entry <address>] [--steps <file>] [--min-stage <bytes>]
 unpack.ts loads <program> --steps <file> --out <dir> [--drive] [--min-block <bytes>]
 
@@ -37,6 +37,8 @@ capture   run the program until the CPU gets to <address> after the steps, and w
           for each segment, and entry_state.json (registers, $00/$01, pages
           0-3, VIC, SID and CIA registers, vectors, and what differs from a
           clean reset). --range gives one segment in place of the found ones.
+          --exclude (more than once) leaves a range out of the segments, for
+          example bytes that a crack left and the program never reads.
           --entry starts it there instead of RUN.
 
 stages    run the program for <n> frames (default 3000) and report each stage:
@@ -74,7 +76,7 @@ const MAX_ADVANCE = 10_000;
 /** The most ranges one memory map read gives. */
 const MAX_RANGES = 1000;
 
-/** Reads and checks a steps file: action steps with $ addresses only (D43). */
+/** Reads and checks a steps file: action steps with $ addresses only. */
 function readSteps(path: string): ActionStep[] {
   let value: unknown;
   try {
@@ -102,7 +104,6 @@ async function runSteps(client: ViceSessionClient, steps: ActionStep[]): Promise
 async function trace(program: string, options: { frames: number; entry?: number; steps: ActionStep[] }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const { bytes } = readProjectFile(program);
   if (bytes.length < 3) throw new UsageError("the file is too short for a PRG");
-  const load = bytes[0]! | (bytes[1]! << 8);
   if (options.entry === undefined && basicStart(bytes) === undefined) throw new UsageError(NO_BASIC);
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
@@ -190,7 +191,7 @@ const SYS_FRAMES = 50;
  * BASIC computes: an exec breakpoint over that part of the program stops there.
  */
 /**
- * Starts the program as a c64-testing scenario does (D62): hard reset, load,
+ * Starts the program as a c64-testing scenario does: hard reset, load,
  * an empty memory map, then RUN up to the first BASIC line, or the pc at
  * `entry`. Gives why it did not start.
  */
@@ -203,7 +204,7 @@ async function startLoaded(client: ViceSessionClient, program: string, bytes: Ui
   return undefined;
 }
 
-/** The raster position now: where a step's frames end (D62). */
+/** The raster position now: where a step's frames end. */
 async function rasterAt(client: ViceSessionClient): Promise<{ line: number; cycle: number }> {
   const { timing } = await client.observe({ timing: true });
   return { line: timing!.rasterLine, cycle: timing!.rasterCycle };
@@ -219,7 +220,7 @@ const MAX_STAGES = 16;
 /** Most stops of one re-run of a chunk: own code and writes over it each stop once. */
 const MAX_STAGE_STOPS = 4096;
 const STAGE_SNAPSHOT = "stage-chunk";
-/** The snapshot at a call into written code, while the run checks if the call returns (D59). */
+/** The snapshot at a call into written code, while the run checks if the call returns. */
 const CALL_SNAPSHOT = "stage-call";
 
 interface Stage {
@@ -245,7 +246,7 @@ function trackedRunUntil(step: ActionStep): step is { runUntil: { at: string };
 }
 
 /**
- * Starts the program and follows its stages (D43). The memory map holds what
+ * Starts the program and follows its stages. The memory map holds what
  * the current stage wrote; when the CPU executed a block of at least
  * `minStage` written bytes during a chunk of frames, the chunk runs again from
  * its snapshot with exec breakpoints over those blocks, which stop at the
@@ -266,7 +267,7 @@ async function follow(
   if (options.entry === undefined && basic === undefined) throw new UsageError(NO_BASIC);
   const notStarted = await startLoaded(client, program, bytes, options.entry);
   if (notStarted !== undefined) return { stages: [], frames: 0, reached: false, failed: notStarted };
-  // The frames of each step end where a scenario's do: the first step counts from RUN, a later one from where it starts (D62).
+  // The frames of each step end where a scenario's do: the first step counts from RUN, a later one from where it starts.
   let anchor: { line: number; cycle: number } | undefined = await rasterAt(client);
   const framed = () => (anchor === undefined ? {} : { anchor });
   const found: Stage[] = [];
@@ -276,10 +277,10 @@ async function follow(
   let firstFrame = 0;
   let total = 0;
   let ended = false;
-  /** Where the run stops: the target of a runUntil step while it runs, then until (R2-06). */
+  /** Where the run stops: the target of a runUntil step while it runs, then until. */
   let stopAt: number | undefined;
   const atTarget = (pc: number) => stopAt !== undefined && pc === stopAt;
-  // The current stage: its memory map since it started, chunk by chunk, its own code, and the written code it calls (D59).
+  // The current stage: its memory map since it started, chunk by chunk, its own code, and the written code it calls.
   let stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] as Range[] };
   const startStage = async (next: number, last: Uint8Array) => {
     mergeMaps(stage.map, last);
@@ -355,7 +356,7 @@ async function follow(
         left -= advanced;
         const pc = run.pc ?? (await client.registersGet("c64")).pc;
         map = await readCoverage(client);
-        // A frame can end in written code that the stage called before (D59): that stop starts no stage.
+        // A frame can end in written code that the stage called before: that stop starts no stage.
         if (inRanges(candidates, pc) && !inRanges(stage.called, pc)) {
           if (written(pc)) {
             const back = left > 0 && !atTarget(pc) ? await returns(map, left) : undefined;
@@ -443,7 +444,7 @@ async function follow(
       stopAt = undefined;
     }
   };
-  // The steps run first and in the tracked time: a frames step and a runUntil step to an address (R2-06). The others act between two chunks.
+  // The steps run first and in the tracked time: a frames step and a runUntil step to an address. The others act between two chunks.
   for (const [index, step] of options.steps.entries()) {
     if ("frames" in step) await track(step.frames);
     else if (trackedRunUntil(step)) {
@@ -496,7 +497,7 @@ async function stages(program: string, options: { frames: number; entry?: number
 
 async function capture(
   program: string,
-  options: { until: number; out: string; range?: [number, number]; timeoutFrames: number; entry?: number; steps: ActionStep[]; minStage: number },
+  options: { until: number; out: string; range?: [number, number]; exclude: Array<{ start: number; end: number }>; timeoutFrames: number; entry?: number; steps: ActionStep[]; minStage: number },
 ): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
@@ -513,7 +514,12 @@ async function capture(
     const memory = await readRam(client, 0x0000, 0x10000);
     const state = await machineState(client);
     // The segments: what the stages wrote, without loader leftovers, with no overlap.
-    const segments = options.range !== undefined ? [{ start: options.range[0], end: options.range[1] }] : captureSegments(followed.stages, registers.pc);
+    const found = options.range !== undefined ? [{ start: options.range[0], end: options.range[1] }] : captureSegments(followed.stages, registers.pc);
+    const inside = options.exclude.find((range) => registers.pc >= range.start && registers.pc <= range.end);
+    if (inside !== undefined) {
+      return { output: { captured: false, reason: `The entry ${formatC64Address(registers.pc)} is in --exclude ${formatC64Address(inside.start)}-${formatC64Address(inside.end)}. A segment must hold the entry.` }, failed: true };
+    }
+    const segments = withoutRanges(found, options.exclude);
     const file = (path: string) => `${options.out}/${path}`;
     const write = (path: string, bytes: Uint8Array) => writeProjectFile(file(path), bytes, { what: "--out" });
     write("image.bin", memory);
@@ -530,6 +536,7 @@ async function capture(
           {
             entry: formatC64Address(registers.pc),
             segments: segments.map((segment, index) => ({ ...showRange(segment), ...("writtenBy" in segment ? { writtenBy: segment.writtenBy } : {}), file: files[index] })),
+            ...(options.exclude.length === 0 ? {} : { excluded: options.exclude.map(showRange) }),
             vectors,
             stages: showStages(followed.stages),
             image: "image.bin",
@@ -556,6 +563,7 @@ async function capture(
         out: options.out,
         files: ["image.json", "image.bin", "entry_state.json", ...files],
         segments: segments.map(showRange),
+        ...(options.exclude.length === 0 ? {} : { excluded: options.exclude.map(showRange) }),
         stages: followed.stages.length,
         differsFromReset: differs.length,
       },
@@ -571,7 +579,7 @@ const OPTIONS_OF: Record<string, string[]> = {
   inspect: [],
   trace: ["frames", "entry", "steps"],
   stages: ["frames", "entry", "steps", "min-stage"],
-  capture: ["until", "out", "range", "timeout-frames", "entry", "steps", "min-stage"],
+  capture: ["until", "out", "range", "exclude", "timeout-frames", "entry", "steps", "min-stage"],
   loads: ["steps", "out", "drive", "min-block"],
 };
 
@@ -584,6 +592,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
       until: { type: "string" },
       out: { type: "string" },
       range: { type: "string" },
+      exclude: { type: "string", multiple: true },
       "timeout-frames": { type: "string" },
       frames: { type: "string" },
       entry: { type: "string" },
@@ -636,7 +645,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     try {
       resolveProjectPath(values.out);
     } catch {
-      throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
     }
     const minBlock = values["min-block"] === undefined ? 64 : Number(values["min-block"]);
     if (!Number.isInteger(minBlock) || minBlock < 1 || minBlock > 0x10000) throw new UsageError("--min-block must be from 1 to 65536");
@@ -652,10 +661,17 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   } else if (rest.length > 0) {
     throw new UsageError("too many arguments");
   }
+  const exclude = (values.exclude ?? []).map((value) => {
+    const parts = value.split("-");
+    if (parts.length !== 2) throw new UsageError(`--exclude takes <start>-<end>, not ${value}`);
+    const range = { start: address(parts[0]!, "--exclude"), end: address(parts[1]!, "--exclude") };
+    if (range.end < range.start) throw new UsageError(`the --exclude end must not be before its start: ${value}`);
+    return range;
+  });
   try {
     resolveProjectPath(values.out);
   } catch {
-    throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+    throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
   }
   const timeoutFrames = values["timeout-frames"] === undefined ? 3000 : Number(values["timeout-frames"]);
   if (!Number.isInteger(timeoutFrames) || timeoutFrames < 1 || timeoutFrames > 30_000) throw new UsageError("--timeout-frames must be from 1 to 30000");
@@ -666,6 +682,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     until: address(values.until, "--until"),
     out: values.out,
     ...(range === undefined ? {} : { range }),
+    exclude,
     timeoutFrames,
     steps,
     minStage,
@@ -674,8 +691,8 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
 }
 
 await runScript(
-  async () => {
-    const { output, failed } = await run(process.argv.slice(2));
+  async (argv) => {
+    const { output, failed } = await run(argv);
     if (failed) process.exitCode = 1;
     return output;
   },

package/src/c64.ts

@@ -20,6 +20,16 @@ export function formatC64Address(value: number): string {
   return `$${checkAddress(value).toString(16).padStart(4, "0")}`;
 }
 
+/** VIC-II state with its addresses as $xxxx; the other values stay numbers. */
+export function formatVicii<T extends { screenAddress: number; graphicsAddress: number }>(state: T): Omit<T, "screenAddress" | "graphicsAddress"> & { screenAddress: string; graphicsAddress: string } {
+  return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+}
+
+/** A sprite with its data address as $xxxx; the other values stay numbers. */
+export function formatSprite<T extends { dataAddress: number }>(sprite: T): Omit<T, "dataAddress"> & { dataAddress: string } {
+  return { ...sprite, dataAddress: formatC64Address(sprite.dataAddress) };
+}
+
 /** A byte as $xx. Throws RangeError outside 0-255. */
 export function formatC64Byte(value: number): string {
   if (!Number.isInteger(value) || value < 0 || value > 0xff) throw new RangeError(`C64 byte out of range: ${value}`);
@@ -37,8 +47,25 @@ export function prgRange(prg: Uint8Array): { start: number; end: number; body: U
   return { start, end: start + prg.length - 3, body: prg.subarray(2) };
 }
 
-/** How 6502 code refers to an address. */
-export const REFERENCE_KINDS = ["call", "jump", "read", "write", "reference"] as const;
+/** The tables of addresses: words, or words minus 1 for an RTS dispatch; a split table has all low bytes, then all high bytes. */
+export const POINTER_TABLE_TYPES = ["addresses", "addresses-split", "rts-addresses", "rts-addresses-split"] as const;
+export type PointerTableType = (typeof POINTER_TABLE_TYPES)[number];
+
+/** The entries of a table of addresses in [start, end]: the address of each low and high byte, and the target that the entry names. */
+export function pointerTableEntries(table: { start: number; end: number; type: PointerTableType }, byteAt: (address: number) => number): Array<{ low: number; high: number; target: number }> {
+  const length = table.end - table.start + 1;
+  const split = table.type === "addresses-split" || table.type === "rts-addresses-split";
+  const minus = table.type === "rts-addresses" || table.type === "rts-addresses-split" ? 1 : 0;
+  const count = Math.floor(length / 2);
+  return Array.from({ length: count }, (_, index) => {
+    const low = split ? table.start + index : table.start + 2 * index;
+    const high = split ? table.start + count + index : low + 1;
+    return { low, high, target: ((byteAt(low) | (byteAt(high) << 8)) + minus) & 0xffff };
+  });
+}
+
+/** How 6502 code refers to an address. A pointer is code that builds the address from immediates. */
+export const REFERENCE_KINDS = ["call", "jump", "read", "write", "reference", "pointer"] as const;
 export type ReferenceKind = (typeof REFERENCE_KINDS)[number];
 
 /** A symbol or label name: assembler label syntax, at most 64 characters; a leading dot marks a local label. */
@@ -163,9 +190,9 @@ const MIN_BASIC_LOAD = 0x0400;
  * zero, the "marker" is the first machine code after the BASIC text (SYS
  * lines that jump right behind themselves). The stored links are not read:
  * BASIC relinks a loaded program, and a crack can store odd links to hide
- * lines from LIST. A load address below $0400 is a memory dump (F-12), and so
+ * lines from LIST. A load address below $0400 is a memory dump, and so
  * is a file whose bytes run past $ffff: a 64 KiB dump from $0000 always does
- * (b2/01, R3-02).
+ *.
  */
 export function parseTokenized(program: Uint8Array): TokenizedProgram {
   if (program.length < 4) return { reason: "The file is too short for a BASIC program." };
@@ -347,7 +374,7 @@ export function findHandoffs(lines: TokenizedLine[]): BasicHandoff[] {
   return handoffs;
 }
 
-// Execution coverage (D40): the byte format of a coverage map, and the 6502
+// Execution coverage: the byte format of a coverage map, and the 6502
 // instruction lengths that turn the instruction starts in it into code ranges.
 // VICE marks only the opcode byte of an executed instruction as executed.
 
@@ -409,3 +436,74 @@ export function executedRamCode(map: Uint8Array, base: number, memory: Uint8Arra
   }
   return ranges;
 }
+
+// Coverage flows: the seeds that a coverage map gives a static analysis.
+
+/**
+ * Instructions after which the next instruction starts a flow for the seeds: the
+ * ones that do not fall through, and JSR, because an analyzer that takes the
+ * called routine for one that does not return stops there (the Bruce Lee run).
+ */
+const FLOW_ENDS = new Set([0x00, 0x20, 0x40, 0x4c, 0x60, 0x6c]);
+/**
+ * The executed instruction starts in RAM that begin a flow: the first after
+ * a gap, or the first after an instruction that does not fall through or is a
+ * JSR. The analyzers follow the rest of a flow themselves.
+ */
+export function coverageEntries(map: Uint8Array, image: (address: number) => number | undefined): number[] {
+  const entries: number[] = [];
+  let falls: number | undefined;
+  for (let address = 0; address < 0x10000; address++) {
+    if ((map[address]! & COVERAGE.ramExecute) === 0) continue;
+    const opcode = image(address);
+    if (opcode === undefined) continue;
+    if (falls !== address) entries.push(address);
+    falls = FLOW_ENDS.has(opcode) ? undefined : address + instructionLength(opcode);
+  }
+  return entries;
+}
+
+/** Every executed instruction start in RAM inside the image: VICE marks the opcode byte of an instruction as executed, not its operand. */
+export function executedStarts(map: Uint8Array, image: (address: number) => number | undefined): number[] {
+  const starts: number[] = [];
+  for (let address = 0; address < 0x10000; address++) if ((map[address]! & COVERAGE.ramExecute) !== 0 && image(address) !== undefined) starts.push(address);
+  return starts;
+}
+
+const BRANCHES = new Set([0x10, 0x30, 0x50, 0x70, 0x90, 0xb0, 0xd0, 0xf0]);
+
+/** Instructions that never fall through to the next one. */
+const NO_FALL = new Set([0x00, 0x40, 0x4c, 0x60, 0x6c]);
+
+/**
+ * The coverage flow starts split for Ghidra. A start is a code start, a
+ * place in a routine, when it follows an executed JSR, or when an executed
+ * branch or JMP from outside its own flow reaches it (the loop of a routine
+ * that jumps back to its own start does not count). Any other start, for
+ * example a vector or table target, is a routine entry.
+ */
+export function coverageSeedKinds(map: Uint8Array, image: (address: number) => number | undefined): { routines: number[]; codeStarts: number[] } {
+  const entries = coverageEntries(map, image);
+  const flowOf = new Map<number, number>();
+  for (const entry of entries) {
+    // A flow runs over the executed instructions that fall through, also over a JSR.
+    for (let at = entry; ; ) {
+      const opcode = image(at);
+      if (opcode === undefined || (map[at]! & COVERAGE.ramExecute) === 0 || flowOf.has(at)) break;
+      flowOf.set(at, entry);
+      if (NO_FALL.has(opcode)) break;
+      at += instructionLength(opcode);
+    }
+  }
+  const inside = new Set<number>();
+  for (const address of executedStarts(map, image)) {
+    const opcode = image(address)!;
+    const low = image(address + 1);
+    const high = image(address + 2);
+    const reach = (target: number) => flowOf.get(address) !== target && inside.add(target);
+    if (BRANCHES.has(opcode) && low !== undefined) reach((address + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff);
+    if (opcode === 0x4c && low !== undefined && high !== undefined) reach(low | (high << 8));
+    if (opcode === 0x20) inside.add(address + 3);
+  }
+  return { routines: entries.filter((entry) => !inside.has(entry)), codeStarts: entries.filter((entry) => inside.has(entry)) };
+}

package/src/cli/cleanup.ts

@@ -29,7 +29,7 @@ interface Manifest {
 }
 
 /** The directory that the manifest and relative item paths belong to. */
-function scopeRoot(scope: Scope, cwd = process.cwd()): string {
+export function scopeRoot(scope: Scope, cwd = process.cwd()): string {
   return scope === "global" ? homedir() : cwd;
 }
 

package/src/cli/main.ts

@@ -14,7 +14,7 @@ import { WireFailure } from "../protocol/messages.ts";
 import { startTrace } from "../trace.ts";
 import { runApSdk } from "./ap-sdk.ts";
 import { installedItems, parseTargets, tidyAfterUninstall, undoWindsurfProjectMcp, windsurfBefore, withoutWindsurfMcp, type Scope } from "./cleanup.ts";
-import { hostStatusLines, toolLines } from "./status.ts";
+import { hostStatusLines, installedLines, toolLines } from "./status.ts";
 
 const HELP = `c64-re-tools: Commodore 64 reverse engineering and development
 
@@ -27,10 +27,12 @@ Usage:
 
 Harnesses: claude, codex, pi, opencode, gemini, copilot, cursor, windsurf
 (comma-separated; default: all). Without --global the files go into the
-current project; with --global into your home directory.
+current folder; with --global into your home directory.
 
-Run it in the project: npx -y ${PACKAGE.name}@${PACKAGE.tag} install. The VICE
-MCP declaration starts the latest c64-re-tools-mcp through npx. The Host
+Run it once at the root of the repository:
+npx -y ${PACKAGE.name}@${PACKAGE.tag} install. Each project folder below
+the root uses that install; a project is a folder with .c64-re-tools/. The
+VICE MCP declaration starts the latest c64-re-tools-mcp through npx. The Host
 Runtime runs on the machine with VICE: start it there with
 npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host.
 It runs VICE and the tools that come with it (c1541, petcat). The skill
@@ -50,6 +52,7 @@ async function status(): Promise<number> {
   console.log(`c64-re-tools ${PACKAGE.version}`);
   console.log(`Package: ${join(here, "..", "..")}`);
   console.log(`Node: ${process.version} (${process.execPath})`);
+  for (const line of installedLines()) console.log(line);
   // The skill scripts run these tools here, on this machine.
   const local = await localToolStatus(localToolContext());
   for (const line of toolLines("Tools here:", local)) console.log(line);

package/src/cli/status.ts

@@ -1,6 +1,10 @@
-// The status report of the CLI: the tools on this machine and the Host
-// Runtime with its tools.
+// The status report of the CLI: the installed skills and MCP declarations,
+// the tools on this machine and the Host Runtime with its tools.
 
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+import { installedItems, scopeRoot, type InstallItem, type Scope } from "./cleanup.ts";
 import { hostTools, type ToolCallOptions } from "../host-client/tools.ts";
 import { viceVersionOf } from "../native/discover.ts";
 import { PACKAGE } from "../package.ts";
@@ -34,7 +38,7 @@ export async function hostStatusLines(options: ToolCallOptions = {}): Promise<{
   try {
     ({ host, tools } = await hostTools(options));
   } catch (error) {
-    // status is read by a person: the instruction for an agent (D37) stays out.
+    // status is read by a person: the instruction for an agent stays out.
     return { lines: [`Host Runtime: not reachable. ${(error as Error).message.replace(` ${STOP_AND_ASK}`, "")}`], ready: false };
   }
   const mixed = mixedViceBuilds(tools);
@@ -59,3 +63,66 @@ export function mixedViceBuilds(tools: readonly ToolStatus[]): string | undefine
   if (new Set(builds).size <= 1) return undefined;
   return `the VICE tools come from different VICE builds: ${running.map((tool) => `${tool.version} (${tool.path})`).join(", ")}. Put x64sc, c1541 and petcat of one VICE first on PATH, or set C64RT_VICE, C64RT_C1541 and C64RT_PETCAT.`;
 }
+
+/**
+ * The skills and MCP declarations that install wrote for this project and
+ * globally: the c64-re-tools version of each harness's skills,
+ * from their package.json, and the command that starts the MCP server. A
+ * warning names skills of another version than this one.
+ */
+export function installedLines(cwd = process.cwd()): string[] {
+  const lines: string[] = [];
+  for (const scope of ["project", "global"] as const satisfies readonly Scope[]) {
+    const items = installedItems(scope, undefined, cwd);
+    if (items.length === 0) continue;
+    const root = scopeRoot(scope, cwd);
+    lines.push(`Installed ${scope === "project" ? `in this project (${root})` : "globally"}:`);
+    for (const harness of [...new Set(items.map((item) => item.harness))]) {
+      const skills = items.filter((item) => item.harness === harness && item.kind === "skill");
+      const versions = [...new Set(skills.map((item) => skillVersion(item, root)).filter((version) => version !== undefined))];
+      if (skills.length > 0) {
+        lines.push(`  ${harness}: ${skills.length} skills, c64-re-tools ${versions.length === 0 ? "of an unknown version" : versions.join(" and ")}`);
+        const other = versions.filter((version) => version !== PACKAGE.version);
+        if (other.length > 0) lines.push(`  Warning: the ${harness} skills are c64-re-tools ${other.join(" and ")} and this is ${PACKAGE.version}. Run npx -y ${PACKAGE.name}@${PACKAGE.tag} update${scope === "global" ? " --global" : ""} to install this version.`);
+      }
+      for (const item of items.filter((candidate) => candidate.harness === harness && candidate.kind === "mcp")) {
+        lines.push(`  ${harness} MCP server: ${mcpCommand(item, root) ?? `declared in ${item.files.join(", ")}`}`);
+      }
+    }
+  }
+  if (lines.length === 0) return ["Installed: nothing in this project or globally."];
+  lines.push("  The MCP server gives its own version in the result of c64_status.");
+  return lines;
+}
+
+function itemPath(file: string, root: string): string {
+  return isAbsolute(file) ? file : join(root, file);
+}
+
+/** The version in the package.json of an installed skill; a skill without scripts has none. */
+function skillVersion(item: InstallItem, root: string): string | undefined {
+  const file = item.files.find((candidate) => candidate.endsWith("/package.json") || candidate.endsWith("\\package.json"));
+  if (file === undefined) return undefined;
+  try {
+    const { version } = JSON.parse(readFileSync(itemPath(file, root), "utf8")) as { version?: unknown };
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The command of the MCP server in a JSON configuration file, or undefined for another format. */
+function mcpCommand(item: InstallItem, root: string): string | undefined {
+  const key = item.detail?.mergeKey;
+  const [file] = item.files;
+  if (key === undefined || file === undefined) return undefined;
+  try {
+    const servers = (JSON.parse(readFileSync(itemPath(file, root), "utf8")) as Record<string, unknown>)[key] as Record<string, { command?: unknown; args?: unknown }> | undefined;
+    const server = servers?.[item.name];
+    if (typeof server?.command !== "string") return undefined;
+    const args = Array.isArray(server.args) ? server.args.filter((arg): arg is string => typeof arg === "string") : [];
+    return [server.command, ...args].join(" ");
+  } catch {
+    return undefined;
+  }
+}

package/src/graphics.ts

@@ -0,0 +1,158 @@
+// Indexed images: the PNG encoder of emulator frames, and the C64 graphics
+// in memory as images for the documentation. A region of the knowledge
+// gives no display mode and no colours, so a sprite, a bitmap or a charset is read
+// both in hires and in multicolour, with fixed pattern palettes.
+
+import { crc32, deflateSync } from "node:zlib";
+
+export interface IndexedFrame {
+  width: number;
+  height: number;
+  /** One palette index per pixel, row by row. */
+  pixels: Uint8Array;
+}
+
+export type Rgb = readonly [number, number, number];
+
+function chunk(type: string, data: Uint8Array): Buffer {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([length, body, crc]);
+}
+
+/** Encodes an indexed frame as an 8-bit palette PNG. */
+export function encodePng(frame: IndexedFrame, palette: ReadonlyArray<Rgb>): Buffer {
+  for (const index of frame.pixels) {
+    if (index >= palette.length) throw new Error(`pixel colour ${index} is not in the ${palette.length}-colour palette`);
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(frame.width, 0);
+  header.writeUInt32BE(frame.height, 4);
+  header[8] = 8; // bit depth
+  header[9] = 3; // indexed colour
+  const rows = Buffer.alloc((frame.width + 1) * frame.height);
+  for (let row = 0; row < frame.height; row++) {
+    // Filter byte 0 (none), then the row.
+    rows.set(frame.pixels.subarray(row * frame.width, (row + 1) * frame.width), row * (frame.width + 1) + 1);
+  }
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", header),
+    chunk("PLTE", Buffer.from(palette.flat())),
+    chunk("IDAT", deflateSync(rows)),
+    chunk("IEND", new Uint8Array(0)),
+  ]);
+}
+
+export type GraphicsMode = "hires" | "multicolour";
+
+/**
+ * The pattern palettes: the index is the pixel value (hires: the bit; multicolour:
+ * the bit pair, 0 = background $d021, 1 = $d022 or screen high nibble, 2 = $d023 or
+ * screen low nibble, 3 = colour RAM), and the last index is the gap between sprites.
+ */
+export const PATTERN_PALETTES: Record<GraphicsMode, readonly Rgb[]> = {
+  hires: [
+    [0x00, 0x00, 0x00],
+    [0xff, 0xff, 0xff],
+    [0x35, 0x28, 0x79],
+  ],
+  multicolour: [
+    [0x00, 0x00, 0x00],
+    [0xad, 0xad, 0xad],
+    [0x6c, 0x6c, 0x6c],
+    [0xed, 0xf1, 0x71],
+    [0x35, 0x28, 0x79],
+  ],
+};
+
+/** The pixel values of one byte, left to right: 8 hires pixels, or 4 multicolour pixels of 2 each. */
+function bytePixels(byte: number, mode: GraphicsMode): number[] {
+  if (mode === "hires") return Array.from({ length: 8 }, (_, bit) => (byte >> (7 - bit)) & 1);
+  return Array.from({ length: 8 }, (_, pixel) => (byte >> (6 - 2 * (pixel >> 1))) & 3);
+}
+
+export const SPRITE = { width: 24, height: 21, bytes: 63 } as const;
+
+/**
+ * The sprites of `bytes` as one sheet, `perRow` sprites wide with a gap of one
+ * pixel. Each sprite takes `stride` bytes (64 in a VIC bank, 63 when packed).
+ */
+export function spriteSheet(bytes: Uint8Array, mode: GraphicsMode, stride = 64, perRow = 8): IndexedFrame {
+  const count = Math.max(1, Math.floor((bytes.length + stride - SPRITE.bytes) / stride));
+  const columns = Math.min(count, perRow);
+  const rows = Math.ceil(count / perRow);
+  const width = columns * (SPRITE.width + 1) + 1;
+  const height = rows * (SPRITE.height + 1) + 1;
+  const gap = PATTERN_PALETTES[mode].length - 1;
+  const pixels = new Uint8Array(width * height).fill(gap);
+  for (let sprite = 0; sprite < count; sprite++) {
+    const left = (sprite % perRow) * (SPRITE.width + 1) + 1;
+    const top = Math.floor(sprite / perRow) * (SPRITE.height + 1) + 1;
+    for (let row = 0; row < SPRITE.height; row++) {
+      for (let column = 0; column < 3; column++) {
+        const values = bytePixels(bytes[sprite * stride + row * 3 + column] ?? 0, mode);
+        values.forEach((value, x) => (pixels[(top + row) * width + left + column * 8 + x] = value));
+      }
+    }
+  }
+  return { width, height, pixels };
+}
+
+/** Cells of 8 bytes as 8x8 pixels, `perRow` cells to a row, cell 0 at the top left. */
+function cellFrame(bytes: Uint8Array, mode: GraphicsMode, perRow: number): IndexedFrame {
+  const cells = Math.ceil(bytes.length / 8);
+  const width = Math.min(cells, perRow) * 8;
+  const height = Math.ceil(cells / perRow) * 8;
+  const pixels = new Uint8Array(width * height);
+  for (let cell = 0; cell < cells; cell++) {
+    const left = (cell % perRow) * 8;
+    const top = Math.floor(cell / perRow) * 8;
+    for (let row = 0; row < 8; row++) {
+      bytePixels(bytes[cell * 8 + row] ?? 0, mode).forEach((value, x) => (pixels[(top + row) * width + left + x] = value));
+    }
+  }
+  return { width, height, pixels };
+}
+
+/** A bitmap of 8x8 cells of 8 bytes, 40 cells to a row, as the VIC reads it. */
+export function bitmapFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+  return cellFrame(bytes, mode, 40);
+}
+
+/** A character set: characters of 8 bytes, 16 to a row, so character N is in row N / 16 and column N % 16. */
+export function charsetFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+  return cellFrame(bytes, mode, 16);
+}
+
+/** Each pixel as a square of `factor` pixels, so a small image is readable on a page. */
+export function scaleFrame(frame: IndexedFrame, factor: number): IndexedFrame {
+  const width = frame.width * factor;
+  const height = frame.height * factor;
+  const pixels = new Uint8Array(width * height);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) pixels[y * width + x] = frame.pixels[Math.floor(y / factor) * frame.width + Math.floor(x / factor)]!;
+  }
+  return { width, height, pixels };
+}
+
+/**
+ * Screen codes as text rows of 40, as the character ROM shows the upper-case
+ * set: @, A-Z, the signs and digits; a reversed code (bit 7) shows as its
+ * code without bit 7, and a graphics code as a dot.
+ */
+export function screenText(bytes: Uint8Array): string[] {
+  const rows: string[] = [];
+  for (let start = 0; start < bytes.length; start += 40) {
+    let row = "";
+    for (const code of bytes.subarray(start, start + 40)) {
+      const plain = code & 0x7f;
+      row += plain === 0 ? "@" : plain <= 26 ? String.fromCharCode(0x40 + plain) : plain <= 31 ? "[£]^<"[plain - 27]! : plain <= 63 ? String.fromCharCode(plain) : ".";
+    }
+    rows.push(row);
+  }
+  return rows;
+}