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

package/src/protocol/tools.ts

@@ -5,7 +5,7 @@ import { type Fields, invalid, isInteger, isObject, isOneOf, onlyFields, Protoco
 
 // ---------------------------------------------------------------------------
 // Native-tool operations. Short-lived requests on "tool" connections; they
-// never touch an emulator or knowledge.db.
+// never touch an emulator or the knowledge.
 
 /** A transferred source tree: relative POSIX paths, one attachment per file in this order. */
 export type SourceTree = Array<{ path: string; size: number }>;
@@ -80,7 +80,7 @@ export interface ToolStatus {
   runs: boolean;
   /** What is wrong and what to do, when it is missing or does not run. */
   problem?: string;
-  /** Known flaws of this version, each with the version that fixes it (D56). The tool still runs. */
+  /** Known flaws of this version, each with the version that fixes it. The tool still runs. */
   flaws?: string[];
 }
 
@@ -109,20 +109,6 @@ export function isRelativePath(value: unknown): value is string {
   return typeof value === "string" && value.length <= 1024 && RELATIVE_PATH.test(value) && !value.includes("//") && !value.endsWith("/");
 }
 
-/** Validates a transferred source tree against its attachments. Throws WireFailure(invalid-input). */
-export function validateSourceTree(value: unknown, attachments: readonly Uint8Array[]): SourceTree {
-  if (!Array.isArray(value) || value.length > MAX_TREE_FILES) invalid(`files must list at most ${MAX_TREE_FILES} files`);
-  if (value.length !== attachments.length) invalid("each listed file needs exactly one attachment");
-  const seen = new Set<string>();
-  return value.map((entry, index) => {
-    if (!isObject(entry) || !isRelativePath(entry.path)) invalid("each file needs a relative path inside the source root");
-    if (seen.has(entry.path)) invalid(`the file ${entry.path} is listed twice`);
-    seen.add(entry.path);
-    if (entry.size !== attachments[index]!.length) invalid(`the size of ${entry.path} does not match its bytes`);
-    return { path: entry.path, size: entry.size as number };
-  });
-}
-
 /** Refuses anything but exactly one attachment with at least one byte, named by what it must hold. */
 function oneFile(attachments: readonly Uint8Array[], what: string): void {
   if (attachments.length !== 1 || attachments[0]!.length === 0) invalid(`${what} must be the one attachment, and it must not be empty`);

package/src/protocol/vice.ts

@@ -94,7 +94,7 @@ export const MAX_WATCH_SIZE = 256;
 export interface Breakpoint {
   id: number;
   address: number;
-  /** A range from address: the CPU stops at the first instruction it executes in it (D43). One address when not given. */
+  /** A range from address: the CPU stops at the first instruction it executes in it. One address when not given. */
   size?: number;
   space: Space;
   enabled: boolean;
@@ -168,7 +168,7 @@ export interface CiaState {
   ddrB: number;
   timerA: number;
   timerB: number;
-  /** The values that a timer loads at an underflow: write-only on the chip, from VICE's dump (D63). */
+  /** The values that a timer loads at an underflow: write-only on the chip, from VICE's dump. */
   latchA: number;
   latchB: number;
   controlA: number;
@@ -217,6 +217,50 @@ export interface HistoryEntry {
   rasterCycle?: number;
 }
 
+// Traces: checkpoints that record each hit and let the program run on.
+
+export const TRACE_KINDS = ["exec", "read", "write"] as const;
+export type TraceKind = (typeof TRACE_KINDS)[number];
+export const MAX_TRACE_POINTS = 8;
+export const MAX_TRACE_FRAMES = 3000;
+export const MAX_TRACE_HITS = 20_000;
+export const TRACE_ENDS = ["frames", "hits", "breakpoint", "watchpoint", "jam"] as const;
+
+export interface TracePoint {
+  kind: TraceKind;
+  start: number;
+  end: number;
+}
+
+/** One hit of a trace: the instruction that executed or made the access, the registers before it, and where the raster was. */
+export interface TraceHit {
+  /** The index of the point in the request. */
+  point: number;
+  /** The address of the instruction. */
+  pc: number;
+  bytes: string;
+  text: string;
+  a: number;
+  x: number;
+  y: number;
+  sp: number;
+  /** The frame of the trace, from 0, and the raster position when the instruction started. */
+  frame: number;
+  rasterLine: number;
+  rasterCycle: number;
+  /** read and write: the address that the instruction used, when its mode tells it, and the byte there after the access. */
+  address?: number;
+  value?: number;
+}
+
+export interface TraceResult {
+  hits: TraceHit[];
+  frames: number;
+  /** frames: the frame limit; hits: the hit limit; breakpoint, watchpoint or jam: the program stopped there. */
+  end: (typeof TRACE_ENDS)[number];
+  pc: number;
+}
+
 export interface BacktraceFrame {
   /** The routine's entry address. */
   address: number;
@@ -238,7 +282,7 @@ export interface ProfileEntry {
   percent: number;
 }
 
-/** Addresses with the same access flags: the coverage byte of src/c64.ts (D40), RAM, ROM and I/O apart. */
+/** Addresses with the same access flags: the coverage byte of src/c64.ts, RAM, ROM and I/O apart. */
 export interface MemmapRange {
   start: number;
   end: number;
@@ -337,8 +381,16 @@ export interface MachineStatus {
   pc?: number;
   /** True while a cartridge from an autostart is attached (D64). */
   cartridge: boolean;
+  /** Present only while stopped by a user breakpoint or watchpoint, or by a JAM. */
+  stopReason?: PointStopReason;
+  /** The id of the breakpoint or watchpoint that stopped the machine. */
+  pointId?: number;
 }
 
+/** What stopped the machine outside a request that stops it. */
+export const POINT_STOP_REASONS = ["breakpoint", "watchpoint", "jam"] as const;
+export type PointStopReason = (typeof POINT_STOP_REASONS)[number];
+
 export interface MemoryReadParams {
   address: number;
   size: number;
@@ -396,7 +448,7 @@ export interface ExecutionParams {
   /**
    * advance-frames only: the raster position that ends a frame, instead of the
    * position where this call starts. Runs that stop between frames then keep
-   * the frames of one timeline (D62).
+   * the frames of one timeline.
    */
   anchor?: { line: number; cycle: number };
 }
@@ -406,6 +458,10 @@ export interface ExecutionResult {
   pc?: number;
   executed?: number;
   advancedFrames?: number;
+  /** advance-frames only: frames when all frames ran, else what stopped the run early. */
+  stopReason?: "frames" | PointStopReason;
+  /** The id of the breakpoint or watchpoint that stopped the run. */
+  pointId?: number;
 }
 
 /** c64_run_until targets. */
@@ -425,12 +481,14 @@ export interface RunUntilResult {
   /** The PC of the CPU in `space`: the CPU that stopped. */
   pc: number;
   space: Space;
+  /** The id of the breakpoint or watchpoint that stopped the run. */
+  pointId?: number;
 }
 
 export interface ViceOperations {
   status: { params: Record<string, never>; result: MachineStatus };
   memoryRead: { params: MemoryReadParams; result: MemoryReadResult };
-  /** The I/O registers at $d000-$dfff as the chips hold them, whatever the CPU banks in, without side effects (D43). */
+  /** The I/O registers at $d000-$dfff as the chips hold them, whatever the CPU banks in, without side effects. */
   ioRead: { params: { address: number; size: number }; result: MemoryReadResult };
   registersGet: { params: { space: Space }; result: Registers };
   memoryWrite: { params: MemoryWriteParams; result: { address: number; bytesWritten: number } };
@@ -451,8 +509,8 @@ export interface ViceOperations {
   programLoad: { params: { address?: number }; result: { state: RunState; loadAddress: number; size: number } };
   /** Attachment: the program or image bytes; `type` is the file's extension. `index` is VICE's file number: 0 loads "*", 1 is the first directory entry. */
   /**
-   * `emulatorFlaw`: for a tape image, a known flaw of the host's VICE version that a tape load meets (D56).
-   * `joysticksCentred`: the control ports that held a direction or fire and were centred first (R3-05).
+   * `emulatorFlaw`: for a tape image, a known flaw of the host's VICE version that a tape load meets.
+   * `joysticksCentred`: the control ports that held a direction or fire and were centred first.
    */
   autostart: { params: { type: string; index: number; run: boolean }; result: { state: RunState; emulatorFlaw?: string; joysticksCentred?: Array<1 | 2> } };
   /** Attachment: the disk image bytes; `type` is the file's extension. */
@@ -460,16 +518,18 @@ export interface ViceOperations {
   /** pc is the reset vector when run is false: the CPU stops there. */
   reset: { params: { mode: ResetMode; run: boolean }; result: { state: RunState; pc?: number } };
   /** `data`: PETSCII bytes as lowercase hex. */
-  /** `emulatorFlaw`: a known flaw of the host's VICE version that this input meets (D56). */
+  /** `emulatorFlaw`: a known flaw of the host's VICE version that this input meets. */
   keyboard: { params: { data: string }; result: { queuedBytes: number; emulatorFlaw?: string } };
   joystick: { params: JoystickState; result: JoystickState & { emulatorFlaw?: string } };
   breakpoint: { params: BreakpointParams; result: Breakpoint | PointRemoved | { breakpoints: Breakpoint[] } };
   watchpoint: { params: WatchpointParams; result: Watchpoint | PointRemoved | { watchpoints: Watchpoint[] } };
   cpuHistory: { params: { limit: number; space: Space }; result: { entries: HistoryEntry[] } };
+  trace: { params: { points: TracePoint[]; frames: number; maxHits: number }; result: TraceResult };
   backtrace: { params: { depth: number; space: Space }; result: { frames: BacktraceFrame[] } };
   /** `cycles` is a decimal string. */
   timing: { params: { action: (typeof TIMING_ACTIONS)[number] }; result: { started: boolean } | { cycles: string } };
-  profile: { params: { limit: number }; result: { entries: ProfileEntry[] } };
+  /** clear starts the profiler again from zero. */
+  profile: { params: { action: "read"; limit: number } | { action: "clear" }; result: { entries: ProfileEntry[] } | { cleared: boolean } };
   memmap: {
     params: { action: "read"; start: number; end: number; maxRanges: number } | { action: "clear" };
     /** `next`: more ranges follow from this address; read again from there. */
@@ -493,7 +553,7 @@ export interface ViceOperations {
     result: { saved: boolean; name: string } | { restored: boolean; state: RunState } | { snapshots: string[] } | { discarded: boolean };
   };
   /**
-   * Snapshot files (D41): export sends the bytes of a named snapshot back as
+   * Snapshot files: export sends the bytes of a named snapshot back as
    * one attachment; restore takes the bytes of a .vsf as one attachment.
    */
   snapshotFile: {
@@ -532,6 +592,7 @@ export const VICE_OPERATIONS = [
   "snapshotFile",
   "ioRead",
   "cpuHistory",
+  "trace",
   "backtrace",
   "timing",
   "profile",
@@ -607,6 +668,20 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
       return { limit: params.limit, space: params.space } as ViceOperations[O]["params"];
     }
+    case "trace": {
+      onlyFields(params, ["points", "frames", "maxHits"]);
+      if (!Array.isArray(params.points) || params.points.length === 0 || params.points.length > MAX_TRACE_POINTS) invalid(`points must be a list of 1 to ${MAX_TRACE_POINTS} points`);
+      const points = (params.points as unknown[]).map((point) => {
+        if (!isObject(point)) return invalid("a point is an object with kind, start and end");
+        onlyFields(point, ["kind", "start", "end"]);
+        if (!isOneOf(TRACE_KINDS, point.kind)) invalid("a point kind must be exec, read or write");
+        if (!isInteger(point.start, 0, 0xffff) || !isInteger(point.end, point.start as number, 0xffff)) invalid("a point needs start and end from $0000 to $ffff, the end not before the start");
+        return { kind: point.kind, start: point.start, end: point.end } as TracePoint;
+      });
+      if (!isInteger(params.frames, 1, MAX_TRACE_FRAMES)) invalid(`frames must be an integer from 1 to ${MAX_TRACE_FRAMES}`);
+      if (!isInteger(params.maxHits, 1, MAX_TRACE_HITS)) invalid(`maxHits must be an integer from 1 to ${MAX_TRACE_HITS}`);
+      return { points, frames: params.frames, maxHits: params.maxHits } as ViceOperations[O]["params"];
+    }
     case "backtrace": {
       onlyFields(params, ["depth", "space"]);
       if (!isInteger(params.depth, 1, MAX_BACKTRACE)) invalid(`depth must be an integer from 1 to ${MAX_BACKTRACE}`);
@@ -646,9 +721,11 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       return result as ViceOperations[O]["params"];
     }
     case "profile": {
-      onlyFields(params, ["limit"]);
+      onlyFields(params, params.action === "clear" ? ["action"] : ["action", "limit"]);
+      if (params.action === "clear") return { action: "clear" } as ViceOperations[O]["params"];
+      if (params.action !== "read") invalid("action must be read or clear");
       if (!isInteger(params.limit, 1, MAX_PROFILE)) invalid(`limit must be an integer from 1 to ${MAX_PROFILE}`);
-      return { limit: params.limit } as ViceOperations[O]["params"];
+      return { action: "read", limit: params.limit } as ViceOperations[O]["params"];
     }
     case "memmap": {
       onlyFields(params, params.action === "clear" ? ["action"] : ["action", "start", "end", "maxRanges"]);
@@ -1011,7 +1088,9 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         typeof value.warp === "boolean" &&
         typeof value.window === "boolean" &&
         (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
-        typeof value.cartridge === "boolean";
+        typeof value.cartridge === "boolean" &&
+        (value.stopReason === undefined || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
       if (!ok) throw new ProtocolError("status result is malformed");
       break;
     }
@@ -1080,7 +1159,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isOneOf(STOP_REASONS, value.stopReason) &&
         isOneOf(RUN_STATES, value.state) &&
         isInteger(value.pc, 0, 0xffff) &&
-        isOneOf(SPACES, value.space);
+        isOneOf(SPACES, value.space) &&
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
       if (!ok) throw new ProtocolError("runUntil result is malformed");
       break;
     }
@@ -1089,7 +1169,9 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isOneOf(RUN_STATES, value.state) &&
         (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
         (value.executed === undefined || isInteger(value.executed, 0, MAX_EXECUTION_COUNT)) &&
-        (value.advancedFrames === undefined || isInteger(value.advancedFrames, 0, MAX_EXECUTION_COUNT));
+        (value.advancedFrames === undefined || isInteger(value.advancedFrames, 0, MAX_EXECUTION_COUNT)) &&
+        (value.stopReason === undefined || value.stopReason === "frames" || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
       if (!ok) throw new ProtocolError("execution result is malformed");
       break;
     }
@@ -1182,6 +1264,29 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       if (!ok) throw new ProtocolError("cpuHistory result is malformed");
       break;
     }
+    case "trace": {
+      const ok =
+        Array.isArray(value.hits) &&
+        isInteger(value.frames, 0, MAX_TRACE_FRAMES) &&
+        isOneOf(TRACE_ENDS, value.end) &&
+        isInteger(value.pc, 0, 0xffff) &&
+        value.hits.every(
+          (hit) =>
+            isObject(hit) &&
+            isInteger(hit.point, 0, MAX_TRACE_POINTS - 1) &&
+            isInteger(hit.pc, 0, 0xffff) &&
+            isHexData(hit.bytes) &&
+            typeof hit.text === "string" &&
+            (["a", "x", "y", "sp"] as const).every((name) => isInteger(hit[name], 0, 0xff)) &&
+            isInteger(hit.frame, 0, MAX_TRACE_FRAMES) &&
+            isInteger(hit.rasterLine, 0, 511) &&
+            isInteger(hit.rasterCycle, 0, 127) &&
+            (hit.address === undefined || isInteger(hit.address, 0, 0xffff)) &&
+            (hit.value === undefined || isInteger(hit.value, 0, 0xff)),
+        );
+      if (!ok) throw new ProtocolError("trace result is malformed");
+      break;
+    }
     case "backtrace": {
       const ok =
         Array.isArray(value.frames) &&
@@ -1198,6 +1303,10 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "profile": {
+      if ("cleared" in value) {
+        if (value.cleared !== true) throw new ProtocolError("profile result is malformed");
+        break;
+      }
       const ok =
         Array.isArray(value.entries) &&
         value.entries.every(

package/src/script.ts

@@ -1,7 +1,8 @@
 // The one error envelope for the skill scripts and the CLI: a script prints one JSON line,
 // a refusal prints {"error":{code,message}} with exit status 1, and a usage error prints the
-// usage text as an invalid-input error with exit status 2.
+// usage text as an invalid-input error with exit status 2. Every script takes --project <folder>.
 
+import { ProjectError, useProject } from "./project.ts";
 import { shownMessage, WireFailure } from "./protocol/messages.ts";
 import { elapsedMs, startTrace, trace, type TraceFields } from "./trace.ts";
 
@@ -17,27 +18,65 @@ function isParseArgsError(error: unknown): error is Error {
   return error instanceof Error && typeof code === "string" && code.startsWith("ERR_PARSE_ARGS_");
 }
 
+/** The line that every usage text ends with. */
+export const PROJECT_USAGE = "Every script takes --project <folder>: the project folder, relative to the working directory. Without it, the script uses the nearest folder at or above the working directory that holds .c64-re-tools/.";
+
+/**
+ * Takes --project <folder> and --project=<folder> out of a command line, up to "--".
+ * Returns the folder and the other arguments. Throws UsageError for a --project without a folder or a second --project.
+ */
+export function takeProject(argv: readonly string[]): { project?: string; argv: string[] } {
+  const rest: string[] = [];
+  let project: string | undefined;
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index]!;
+    if (argument === "--") {
+      rest.push(...argv.slice(index));
+      break;
+    }
+    let value: string | undefined;
+    if (argument === "--project") {
+      value = argv[index + 1];
+      if (value === undefined || value.startsWith("-")) throw new UsageError("--project needs a folder");
+      index++;
+    } else if (argument.startsWith("--project=")) {
+      value = argument.slice("--project=".length);
+      if (value === "") throw new UsageError("--project needs a folder");
+    } else {
+      rest.push(argument);
+      continue;
+    }
+    if (project !== undefined) throw new UsageError("give --project only once");
+    project = value;
+  }
+  return project === undefined ? { argv: rest } : { project, argv: rest };
+}
+
 function printLine(value: unknown): void {
   process.stdout.write(`${JSON.stringify(value)}\n`);
 }
 
 /**
- * Runs a script body. Prints its result as one JSON line when it returns a value (undefined prints nothing).
- * A refusal (WireFailure always, plus `refusals`) prints {"error":{code,message}} with exit status 1.
+ * Runs a script body with the command line of the process, without --project: that sets the project first.
+ * Prints its result as one JSON line when it returns a value (undefined prints nothing).
+ * A refusal (WireFailure and ProjectError always, plus `refusals`) prints {"error":{code,message}} with exit status 1.
  * A UsageError or a node:util parseArgs error (code ERR_PARSE_ARGS_*) prints {"error":{"code":"invalid-input",
  * "message": message === "" ? usage : message + "\n\n" + usage}} with exit status 2. Anything else is rethrown.
  * The body may set process.exitCode itself for an extra exit status; a value it returns is printed as usual.
  */
-export async function runScript(body: () => unknown, options: { usage: string; refusals?: readonly RefusalClass[] }): Promise<void> {
+export async function runScript(body: (argv: string[]) => unknown, options: { usage: string; refusals?: readonly RefusalClass[] }): Promise<void> {
+  const usage = `${options.usage}\n\n${PROJECT_USAGE}`;
   // The trace of the script, when C64RT_TRACE is set; its start event carries the script and its arguments.
   startTrace("script", { warn: (line) => process.stderr.write(`${line}\n`) });
   const started = performance.now();
   const end = (fields: TraceFields) => trace().event("script.end", { ms: elapsedMs(started), status: process.exitCode ?? 0, ...fields });
   let result: unknown;
   try {
-    result = await body();
+    const { project, argv } = takeProject(process.argv.slice(2));
+    if (project !== undefined) useProject(project);
+    result = await body(argv);
   } catch (error) {
-    if ([WireFailure, ...(options.refusals ?? [])].some((refusal) => error instanceof refusal)) {
+    if ([WireFailure, ProjectError, ...(options.refusals ?? [])].some((refusal) => error instanceof refusal)) {
       const { code } = error as Error & { code: string };
       const message = shownMessage(error as Error & { code: string });
       printLine({ error: { code, message } });
@@ -47,7 +86,7 @@ export async function runScript(body: () => unknown, options: { usage: string; r
     }
     if (error instanceof UsageError || isParseArgsError(error)) {
       const { message } = error;
-      printLine({ error: { code: "invalid-input", message: message === "" ? options.usage : `${message}\n\n${options.usage}` } });
+      printLine({ error: { code: "invalid-input", message: message === "" ? usage : `${message}\n\n${usage}` } });
       process.exitCode = 2;
       end({ error: { code: "invalid-input", message } });
       return;

package/src/trace.ts

@@ -1,7 +1,8 @@
 // An opt-in trace for the person who debugs a run. With C64RT_TRACE=<directory>
-// in the environment, each process appends its events as JSON lines to a file
-// of its own in that directory; unset, every call does nothing. The trace is
-// for people: nothing of it reaches the agent, and no result depends on it.
+// in the environment (the host: --log-dir), each process appends its events as
+// JSON lines to a file of its own in that directory. The host can also echo
+// each event to the console (--log-console). Off, every call does nothing. The
+// trace is for people: nothing of it reaches the agent, and no result depends on it.
 
 import { appendFileSync, copyFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -66,14 +67,16 @@ export class Trace {
   readonly kind: TraceKind;
   /** The directory of the trace, or undefined when the trace is off. */
   readonly dir: string | undefined;
-  /** The file this trace appends to, or undefined when the trace is off. */
+  /** The file this trace appends to, or undefined when the trace writes no file. */
   readonly file: string | undefined;
+  readonly #echo: ((line: string) => void) | undefined;
   #broken = false;
 
-  private constructor(kind: TraceKind, dir: string | undefined, file: string | undefined) {
+  private constructor(kind: TraceKind, dir: string | undefined, file: string | undefined, echo?: (line: string) => void) {
     this.kind = kind;
     this.dir = dir;
     this.file = file;
+    this.#echo = echo;
   }
 
   /** A trace that records nothing. */
@@ -81,31 +84,46 @@ export class Trace {
     return new Trace(kind, undefined, undefined);
   }
 
+  /** A trace that writes no file and gives each event to `echo` as one line. */
+  static echoing(kind: TraceKind, echo: (line: string) => void): Trace {
+    return new Trace(kind, undefined, undefined, echo);
+  }
+
   /**
    * A trace into `dir`, created when it is missing. The file is
    * `<kind>-<CET time>-<pid>.jsonl`, and its first event is `trace.start`.
    * Throws when the directory cannot be used.
    */
-  static open(kind: TraceKind, dir: string, now = new Date()): Trace {
+  static open(kind: TraceKind, dir: string, now = new Date(), echo?: (line: string) => void): Trace {
     mkdirSync(dir, { recursive: true });
-    const trace = new Trace(kind, dir, join(dir, `${kind}-${fileStampCet(now)}-${process.pid}.jsonl`));
+    const trace = new Trace(kind, dir, join(dir, `${kind}-${fileStampCet(now)}-${process.pid}.jsonl`), echo);
     trace.event("trace.start", { version: runningVersion(), pid: process.pid, argv: process.argv.slice(1), cwd: process.cwd(), node: process.version, platform: process.platform });
     return trace;
   }
 
   get on(): boolean {
+    return this.#writes || this.#echo !== undefined;
+  }
+
+  get #writes(): boolean {
     return this.file !== undefined && !this.#broken;
   }
 
-  /** Appends one event. A write that fails turns the trace off; nothing throws. */
+  /**
+   * Records one event: appends it to the file, and gives it to the echo as
+   * "<event> <fields as JSON>". The echo skips `log` events, which the program
+   * prints itself. A write that fails stops the file; nothing throws.
+   */
   event(name: string, fields: TraceFields = {}): void {
     if (!this.on) return;
-    const line: Record<string, unknown> = { t: isoCet(), kind: this.kind, event: name };
+    const summary: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(fields)) {
-      if (!RESERVED.has(key) && value !== undefined) line[key] = summarize(value);
+      if (!RESERVED.has(key) && value !== undefined) summary[key] = summarize(value);
     }
+    if (this.#echo !== undefined && name !== "log") this.#echo(`${name} ${JSON.stringify(summary)}`);
+    if (!this.#writes) return;
     try {
-      appendFileSync(this.file!, `${JSON.stringify(line)}\n`);
+      appendFileSync(this.file!, `${JSON.stringify({ t: isoCet(), kind: this.kind, event: name, ...summary })}\n`);
     } catch {
       this.#broken = true;
     }
@@ -121,7 +139,7 @@ export class Trace {
    * trace, as `<kind>-<pid>-<name>`. A copy that fails is recorded, not thrown.
    */
   keep(source: string, name: string): void {
-    if (!this.on) return;
+    if (!this.#writes) return;
     const target = join(this.dir!, `${this.kind}-${process.pid}-${name}`);
     try {
       copyFileSync(source, target);
@@ -135,23 +153,37 @@ export class Trace {
 // Off until a program calls startTrace; the kind is a placeholder until then.
 let current = Trace.off("script");
 
+/** Where the trace of a process goes: a directory for its file, and an echo for each event. */
+export interface TraceTarget {
+  /** The directory, and how the user gave it (`--log-dir <path>`, for example) for a warning. */
+  dir?: { path: string; given: string };
+  echo?: (line: string) => void;
+}
+
+/** The target that C64RT_TRACE in `env` gives: its directory, or nothing. */
+export function traceTargetFromEnv(env: NodeJS.ProcessEnv = process.env): TraceTarget {
+  const path = env[TRACE_VARIABLE];
+  return path === undefined || path === "" ? {} : { dir: { path, given: `${TRACE_VARIABLE}=${path}` } };
+}
+
 /**
- * Switches the trace of this process on when `env` (the environment by
- * default) has C64RT_TRACE, and off otherwise. A directory that cannot be used
- * leaves the trace off and reports that through `warn`. Called once, at the
- * start of a program.
+ * Switches the trace of this process on for `target` (by default what
+ * C64RT_TRACE in `env` gives), and off when the target is empty. A directory
+ * that cannot be used writes no file and reports that through `warn`; an echo
+ * stays on. Called once, at the start of a program.
  */
-export function startTrace(kind: TraceKind, options: { env?: NodeJS.ProcessEnv; warn?: (line: string) => void } = {}): Trace {
-  const dir = (options.env ?? process.env)[TRACE_VARIABLE];
-  if (dir === undefined || dir === "") {
-    current = Trace.off(kind);
+export function startTrace(kind: TraceKind, options: { env?: NodeJS.ProcessEnv; target?: TraceTarget; warn?: (line: string) => void } = {}): Trace {
+  const { dir, echo } = options.target ?? traceTargetFromEnv(options.env);
+  const noFile = () => (echo === undefined ? Trace.off(kind) : Trace.echoing(kind, echo));
+  if (dir === undefined) {
+    current = noFile();
     return current;
   }
   try {
-    current = Trace.open(kind, dir);
+    current = Trace.open(kind, dir.path, new Date(), echo);
   } catch (error) {
-    current = Trace.off(kind);
-    options.warn?.(`${TRACE_VARIABLE}=${dir} cannot be used (${error instanceof Error ? error.message : String(error)}); the trace is off.`);
+    current = noFile();
+    options.warn?.(`${dir.given} cannot be used (${error instanceof Error ? error.message : String(error)}); no trace file is written.`);
   }
   return current;
 }

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

@@ -1,84 +0,0 @@
-// The byte check of a build (D47): the assembled program against the image
-// of the unpacker (image.json with image.bin), a reference PRG, or 64 KiB of
-// memory, segment by segment.
-
-import { posix } from "node:path";
-
-import { formatC64Address, prgRange } from "#src/c64.ts";
-import { readProjectFile } from "#src/host-client/transfer.ts";
-import { UsageError } from "#src/script.ts";
-
-export interface SegmentCheck {
-  start: string;
-  end: string;
-  result: "identical" | "different" | "not covered";
-  /** Bytes of the segment that the build does not hold. */
-  uncovered?: number;
-  differences?: number;
-  firstDifference?: { address: string; built: number; reference: number };
-}
-
-const FULL = 0x10000;
-
-/** The reference as memory and the ranges to check in it. */
-function reference(path: string, built: { start: number; end: number }): { memory: (address: number) => number | undefined; segments: Array<{ start: number; end: number }> } {
-  const { bytes } = readProjectFile(path);
-  if (path.endsWith(".json")) {
-    let manifest: { image?: unknown; segments?: unknown };
-    try {
-      manifest = JSON.parse(bytes.toString("utf8")) as typeof manifest;
-    } catch (error) {
-      throw new UsageError(`--compare ${path} is not JSON: ${(error as Error).message}`);
-    }
-    const segments = manifest.segments;
-    if (typeof manifest.image !== "string" || !Array.isArray(segments) || segments.length === 0) throw new UsageError(`--compare ${path} is not an image.json: it needs image and segments`);
-    const image = readProjectFile(posix.join(posix.dirname(path), manifest.image)).bytes;
-    if (image.length !== FULL) throw new UsageError(`the image of ${path} has ${image.length} bytes, not 65536`);
-    return {
-      memory: (address) => image[address],
-      segments: segments.map((segment: { start?: unknown; end?: unknown }) => {
-        const parse = (value: unknown) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : NaN);
-        const range = { start: parse(segment.start), end: parse(segment.end) };
-        if (!(range.start <= range.end)) throw new UsageError(`--compare ${path}: a segment needs start and end as $ addresses`);
-        return range;
-      }),
-    };
-  }
-  if (bytes.length === FULL && !path.endsWith(".prg")) return { memory: (address) => bytes[address], segments: [built] };
-  let range: ReturnType<typeof prgRange>;
-  try {
-    range = prgRange(bytes);
-  } catch (error) {
-    throw new UsageError(`--compare ${path}: ${(error as Error).message}`);
-  }
-  return { memory: (address) => (address >= range.start && address <= range.end ? range.body[address - range.start] : undefined), segments: [{ start: range.start, end: range.end }] };
-}
-
-/** Compares the assembled PRG with the reference, segment by segment. */
-export function compareBuild(prg: Uint8Array, path: string): { against: string; identical: boolean; segments: SegmentCheck[] } {
-  const built = prgRange(prg);
-  const { memory, segments } = reference(path, built);
-  const checks = segments.map((segment): SegmentCheck => {
-    const from = Math.max(segment.start, built.start);
-    const to = Math.min(segment.end, built.end);
-    const shown = { start: formatC64Address(segment.start), end: formatC64Address(segment.end) };
-    if (from > to) return { ...shown, result: "not covered", uncovered: segment.end - segment.start + 1 };
-    let differences = 0;
-    let first: SegmentCheck["firstDifference"];
-    for (let address = from; address <= to; address++) {
-      const builtByte = built.body[address - built.start]!;
-      const referenceByte = memory(address);
-      if (referenceByte === undefined || builtByte === referenceByte) continue;
-      differences++;
-      first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
-    }
-    const uncovered = segment.end - segment.start + 1 - (to - from + 1);
-    return {
-      ...shown,
-      result: differences > 0 ? "different" : uncovered > 0 ? "not covered" : "identical",
-      ...(uncovered > 0 ? { uncovered } : {}),
-      ...(differences > 0 ? { differences, firstDifference: first! } : {}),
-    };
-  });
-  return { against: path, identical: checks.every((check) => check.result === "identical"), segments: checks };
-}