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

package/src/host/main.ts

@@ -7,6 +7,7 @@ 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";
@@ -15,7 +16,7 @@ import { PACKAGE } from "../package.ts";
 const HELP = `c64-re-tools-host
 
 Usage:
-  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host [--port <port>]
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host [--port <port>] [--log-console] [--log-dir <directory>]
   c64-re-tools-host --help
 
 Runs the c64-re-tools Host Runtime in the foreground. It first starts VICE
@@ -27,8 +28,16 @@ connected c64-re-tools-mcp process, and runs the tools that come with VICE
 emulator and tool it started.
 
 Options:
-  --port <port>       Listen on this port instead (0 picks a free port).
-  --help              Show this help.`;
+  --port <port>            Listen on this port instead (0 picks a free port).
+  --log-console            Also print each request with its result, and each run
+                           of c1541 or petcat, to the console.
+  --log-dir <directory>    Write the same events as JSON lines to a file in this
+                           directory, with a copy of each VICE log.
+  --help                   Show this help.
+
+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`);
@@ -36,9 +45,12 @@ function log(line: string): void {
 }
 
 async function main(): Promise<number> {
-  let values: { help?: boolean; port?: string };
+  let values: { help?: boolean; port?: string; "log-console"?: boolean; "log-dir"?: string };
   try {
-    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" } }, strict: true }));
+    ({ values } = parseArgs({
+      options: { help: { type: "boolean" }, port: { type: "string" }, "log-console": { type: "boolean" }, "log-dir": { type: "string" } },
+      strict: true,
+    }));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
     return 2;
@@ -47,7 +59,18 @@ async function main(): Promise<number> {
     process.stdout.write(`${HELP}\n`);
     return 0;
   }
-  startTrace("host", { warn: log });
+  const logDir = values["log-dir"];
+  if (logDir === "") {
+    process.stderr.write("--log-dir needs a directory.\n");
+    return 2;
+  }
+  startTrace("host", {
+    target: {
+      ...(logDir === undefined ? {} : { dir: { path: logDir, given: `--log-dir ${logDir}` } }),
+      ...(values["log-console"] ? { echo: (line: string) => process.stderr.write(`c64-re-tools-host: ${line}\n`) } : {}),
+    },
+    warn: log,
+  });
 
   const port = values.port === undefined ? DEFAULT_HOST_PORT : parsePort(values.port);
   if (port === undefined) {
@@ -55,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);
@@ -80,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;
@@ -89,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) {

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. */