@henols/c64-re-tools 2.0.0-rc.9 → 2.0.1

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;
+}

package/src/host/main.ts

@@ -7,10 +7,11 @@ import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
 import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
 import { viceFlaws, type ViceVersion } from "../native/discover.ts";
+import { inspect } from "./tools/c1541.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
-import { PACKAGE } from "../package.ts";
+import { oldNodeRefusal, PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-host
 
@@ -34,8 +35,9 @@ Options:
                            directory, with a copy of each VICE log.
   --help                   Show this help.
 
-Without --log-console and --log-dir the host logs only its start, its stop,
-connections and failures. C64RT_TRACE does not apply to the host.`;
+The host always logs its start and stop, connections, failures, and each call
+from a skill script (c1541, petcat) with its outcome. --log-console adds the
+calls of the MCP server and the tool runs. C64RT_TRACE does not apply to the host.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-host: ${line}\n`);
@@ -76,6 +78,9 @@ async function main(): Promise<number> {
     return 2;
   }
 
+  // First, so that every start, also a refused one, tells which runtime runs.
+  log(`${PACKAGE.name} ${PACKAGE.version} (Node.js ${process.version}, ${process.platform} ${process.arch})`);
+
   // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
   try {
     findVice(process.env);
@@ -101,7 +106,7 @@ async function main(): Promise<number> {
   }
   log(`VICE ${vice.major}.${vice.minor}${vice.revision === undefined ? "" : ` r${vice.revision}`} starts`);
   const flaws = viceFlaws(vice);
-  // A known VICE flaw is named, not worked around (D56).
+  // A known VICE flaw is named, not worked around.
   for (const flaw of flaws) log(`Known VICE flaw: ${flaw}`);
 
   let server;
@@ -110,7 +115,16 @@ async function main(): Promise<number> {
       host: "0.0.0.0",
       port,
       log,
-      createViceSession: viceSessionFactory({ supervisor, log, flaws }),
+      createViceSession: viceSessionFactory({
+        supervisor,
+        log,
+        flaws,
+        // c1541 lists the disk, so an autostart index selects a program.
+        directory: async (imageType, image) => {
+          const { result } = await inspect({ action: "directory", imageType }, image, { supervisor, signal: new AbortController().signal, log });
+          return result.action === "directory" ? result.entries : [];
+        },
+      }),
       tools: createToolDispatcher({ supervisor, log, vice }),
     });
   } catch (error) {
@@ -130,4 +144,10 @@ async function main(): Promise<number> {
   return 0;
 }
 
+const oldNode = oldNodeRefusal();
+if (oldNode !== undefined) {
+  log(oldNode);
+  process.exit(1);
+}
+
 process.exitCode = await main();

package/src/host/server.ts

@@ -4,7 +4,7 @@ import { encodeFrame, MessageReader } from "../protocol/framing.ts";
 import { checkHello, isOneOf, HEARTBEAT_TIMEOUT_MS, parseClientMessage, ProtocolError, type HostMessage, type ReceivedRequest, type VideoStandard, type WireError, WireFailure } from "../protocol/messages.ts";
 import { TOOL_OPERATIONS, validateToolParams, type ToolOperation, type ToolOperations } from "../protocol/tools.ts";
 import { attachmentCount, VICE_OPERATIONS, validateViceParams, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
-import { elapsedMs, trace } from "../trace.ts";
+import { elapsedMs, summarize, trace } from "../trace.ts";
 
 /** One live VICE session, owned by one connection. */
 export interface ViceSessionHandle {
@@ -234,8 +234,15 @@ class Connection {
 
   async #answer(request: ReceivedRequest, attachments: Buffer[]): Promise<void> {
     const started = performance.now();
-    const record = (outcome: Record<string, unknown>) =>
-      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms: elapsedMs(started), ...outcome });
+    const record = (outcome: Record<string, unknown>) => {
+      const ms = elapsedMs(started);
+      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms, ...outcome });
+      // A call from a skill script (c1541, petcat, status) is always logged; the many calls of a VICE session only in the trace.
+      if (this.#isTool) {
+        const what = outcome.ok === true ? "ok" : `${String(outcome.code)}: ${String(outcome.message)}`;
+        this.#log(`${request.op} ${JSON.stringify(summarize(request.params) ?? {})}: ${what} (${ms} ms)`);
+      }
+    };
     try {
       let result: unknown;
       let replyAttachments: Buffer[] = [];

package/src/host/tools/petcat.ts

@@ -18,7 +18,7 @@ const TIMEOUT_MS = 30_000;
 const LISTING = "listing.txt";
 /**
  * petcat's listing lines ("   10 sys2061"), as number and text. petcat
- * prints π ($ff) as `~`, which is no PETSCII character: the text has π (F-13).
+ * prints π ($ff) as `~`, which is no PETSCII character: the text has π.
  */
 export function parseListing(listing: string): Array<{ number: number; text: string }> {
   const lines: Array<{ number: number; text: string }> = [];

package/src/host/tools/status.ts

@@ -38,7 +38,7 @@ export async function hostStatus(context: ToolContext, started?: ViceVersion): P
   );
   const tools = started === undefined ? probed : [{ name: VICE.name, found: true, path: findVice(context.env ?? process.env), version: versionText(started), runs: true }, ...probed];
   const checked = tools.map((status, index) => requireMinimum(status, specs[index]!));
-  // VICE runs with its known flaws; status names them (D56).
+  // VICE runs with its known flaws; status names them.
   const vice = checked[0]!;
   const version = vice.runs ? viceVersionOf(vice.version ?? "") : undefined;
   const flaws = version === undefined ? [] : viceFlaws(version);

package/src/host/vice/adapter.ts

@@ -4,7 +4,8 @@
 import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
 import { type Comparison, type Condition, type BacktraceFrame, type HistoryEntry, type Instruction, type MemmapRange, type ProfileEntry, type JoystickState, type MemoryView, type RegisterValues, type Registers, type Space } from "../../protocol/vice.ts";
 import { COVERAGE, formatC64Address, formatC64Byte } from "../../c64.ts";
-import { decodeDisplay, decodePalette, visibleFrame, type IndexedFrame } from "./screen.ts";
+import type { IndexedFrame } from "../../graphics.ts";
+import { decodeDisplay, decodePalette, visibleFrame } from "./screen.ts";
 import type { TextMonitor } from "./text-monitor.ts";
 import type { CiaHidden } from "./chips.ts";
 import {
@@ -260,7 +261,7 @@ function unknownForm(what: string, lines: string[]): WireFailure {
   return new WireFailure("operation-failed", `VICE printed the ${what} in a form that c64-re-tools does not read: ${JSON.stringify(lines.slice(0, 3))}`);
 }
 
-/** The coverage byte (D40) of one memmap row's I/O, ROM and RAM columns, each "rwx" with "-" for no access. */
+/** The coverage byte of one memmap row's I/O, ROM and RAM columns, each "rwx" with "-" for no access. */
 export function memmapFlags(io: string, rom: string, ram: string): number {
   let flags = 0;
   if (ram[0] === "r") flags |= COVERAGE.ramRead;
@@ -434,7 +435,7 @@ export class ViceAdapter {
 
   /**
    * The timer latches and the interrupt mask of the CIA at `base`, from VICE's
-   * text-monitor dump: no register read gives them (D63).
+   * text-monitor dump: no register read gives them.
    */
   async ciaHidden(base: 0xdc00 | 0xdd00): Promise<CiaHidden> {
     const answer = await this.#computerText(`io ${hex4(base)}`);

package/src/host/vice/process.ts

@@ -12,7 +12,7 @@
 // - autostart of a PRG needs `-autostartprgmode 1` (inject into RAM);
 // - the joyport command reaches the C64 only through the "Joyport I/O
 //   simulation" device (37). In VICE 3.10 and older it holds bits 5-7 of
-//   both CIA 1 ports low (VICE bug #2202, a known flaw named by D56);
+//   both CIA 1 ports low (VICE bug #2202, a known flaw);
 // - with the default JAM action a jammed CPU hangs silently; -jamaction 2
 //   enters the monitor instead;
 // - the monitor's profiler prints numbers in the host locale, so VICE runs
@@ -97,7 +97,7 @@ export function viceArguments(options: {
     // Autostart injects a PRG into RAM; the default mode copies it to a disk image first.
     "-autostartprgmode",
     "1",
-    // VICE's default waits a random time before an autostart types its LOAD, so two runs of one file differ (R2-12).
+    // VICE's default waits a random time before an autostart types its LOAD, so two runs of one file differ.
     "+autostart-delay-random",
     // The same RAM after every power-up: a hard reset is a power cycle, and VICE's default can flip
     // random bits, so two runs from one start state could differ.

package/src/host/vice/screen.ts

@@ -1,18 +1,10 @@
 // Canonical emulator-frame capture: VICE's own rendered VIC-II frame, never a
 // desktop screenshot; the frame comparison and difference image for baselines.
 
-import { crc32, deflateSync } from "node:zlib";
-
+import type { IndexedFrame } from "../../graphics.ts";
 import type { VideoStandard } from "../../protocol/messages.ts";
 import { FRAME_SIZE } from "../../protocol/vice.ts";
 
-export interface IndexedFrame {
-  width: number;
-  height: number;
-  /** One palette index per pixel, row by row. */
-  pixels: Uint8Array;
-}
-
 export interface RawDisplay {
   /** Full buffer size, blanking included. */
   bufferWidth: number;
@@ -83,39 +75,6 @@ export function decodePalette(body: Buffer): Array<[number, number, number]> {
   return colours;
 }
 
-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<readonly [number, number, number]>): 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 interface FrameDifference {
   mismatchingPixels: number;
   /** Pixels compared: the frame minus the masked ones. */