@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/src/host-client/vice-session.ts

@@ -2,18 +2,29 @@
 // one VICE. Exposes C64-domain operations only.
 
 import { ProtocolError, WireFailure, type VideoStandard } from "../protocol/messages.ts";
-import { validateViceResult, type Breakpoint, type BreakpointParams, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
+import { MAX_MEMORY_READ, validateViceResult, type Breakpoint, type BreakpointParams, type PointRemoved, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type ProfileEntry, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
 import { HostConnection } from "./connect.ts";
 import { readProjectFile } from "./transfer.ts";
 
 const HOST_LOST =
-  "The connection to the c64-re-tools host runtime was lost, and the emulator and its machine state went with it. " +
-  "Check that the Host Runtime (c64-re-tools-host) is running, then restart the c64-re-tools MCP server.";
+  "The connection to the c64-re-tools host runtime was lost. The emulator and its machine state are gone: memory, registers, breakpoints, snapshots and the loaded program. " +
+  "The next call starts a new machine when the Host Runtime (c64-re-tools-host) runs. Load the program again and set the breakpoints again.";
 const SESSION_CLOSED = "The C64 session is closed because the c64-re-tools MCP server stops.";
+const LOST_BEFORE_ANSWER = "The connection to the c64-re-tools host runtime was lost before the emulator answered. No machine state was lost. Do the call again.";
+
+/**
+ * The loss of a session that never answered (D57): it had no machine state,
+ * so the caller can do the call again on a new session.
+ */
+export class LostBeforeAnswer extends WireFailure {
+  constructor() {
+    super("machine-unavailable", LOST_BEFORE_ANSWER);
+  }
+}
 
 interface Pending {
   op: ViceOperation;
-  resolve: (value: unknown) => void;
+  resolve: (value: unknown, attachments: Buffer[]) => void;
   reject: (error: Error) => void;
 }
 
@@ -24,21 +35,24 @@ export class ViceSessionClient {
   readonly #pending = new Map<number, Pending>();
   #nextId = 1;
   #lost: WireFailure | undefined;
+  #answered = false;
+  #lossReported = false;
 
   private constructor(connection: HostConnection) {
     this.#connection = connection;
-    connection.onMessage((message) => {
+    connection.onMessage((message, attachments) => {
       // Anything but a reply after the handshake breaks the contract.
       if (message.type !== "reply") return this.#fail();
       const pending = this.#pending.get(message.id);
       if (pending === undefined) return; // not ours; ignore
       this.#pending.delete(message.id);
+      this.#answered = true;
       if ("error" in message) {
         pending.reject(new WireFailure(message.error.code, message.error.message));
         return;
       }
       try {
-        pending.resolve(validateViceResult(pending.op, message.result));
+        pending.resolve(validateViceResult(pending.op, message.result), attachments);
       } catch (error) {
         pending.reject(
           new WireFailure(
@@ -50,7 +64,8 @@ export class ViceSessionClient {
       }
     });
     this.closed = connection.closed.then(() => {
-      this.#lost ??= new WireFailure("machine-state-lost", HOST_LOST);
+      this.#lost ??= this.#answered ? new WireFailure("machine-state-lost", HOST_LOST) : new LostBeforeAnswer();
+      this.#lossReported = this.#pending.size > 0;
       for (const pending of this.#pending.values()) pending.reject(this.#lost);
       this.#pending.clear();
     });
@@ -75,6 +90,11 @@ export class ViceSessionClient {
     return this.#request("memoryRead", params);
   }
 
+  /** The I/O registers at $d000-$dfff as the chips hold them, without side effects. */
+  ioRead(address: number, size: number): Promise<MemoryReadResult> {
+    return this.#request("ioRead", { address, size });
+  }
+
   registersGet(space: Space): Promise<Registers> {
     return this.#request("registersGet", { space });
   }
@@ -107,21 +127,21 @@ export class ViceSessionClient {
     return this.#request("runUntil", params);
   }
 
-  /** Loads a project PRG into memory without reset or start; finishes stopped. */
-  async programLoad(params: { path: string; address?: number }): Promise<{ state: RunState; loadAddress: number; size: number }> {
-    const file = readProjectFile(params.path);
+  /** Loads a project PRG into memory without reset or start; finishes stopped. `root` is the project folder; it stays on this side. */
+  async programLoad(params: { path: string; address?: number; root?: string }): Promise<{ state: RunState; loadAddress: number; size: number }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("programLoad", params.address === undefined ? {} : { address: params.address }, [file.bytes]);
   }
 
-  /** Autostarts a project program or image, as VICE's autostart does. */
-  async autostart(params: { path: string; index: number; run: boolean }): Promise<{ state: RunState }> {
-    const file = readProjectFile(params.path);
+  /** Autostarts a project program or image, as VICE's autostart does. `root` is the project folder; it stays on this side. */
+  async autostart(params: { path: string; index: number; run: boolean; root?: string }): Promise<{ state: RunState; emulatorFlaw?: string }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("autostart", { type: file.type, index: params.index, run: params.run }, [file.bytes]);
   }
 
-  /** Attaches a project disk image to drive 8. */
-  async diskAttach(params: { path: string }): Promise<{ attached: boolean }> {
-    const file = readProjectFile(params.path);
+  /** Attaches a project disk image to drive 8. `root` is the project folder; it stays on this side. */
+  async diskAttach(params: { path: string; root?: string }): Promise<{ attached: boolean }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("diskAttach", { type: file.type }, [file.bytes]);
   }
 
@@ -138,17 +158,19 @@ export class ViceSessionClient {
     return this.#request("joystick", state);
   }
 
-  /** Action list gives all breakpoints; every other action gives the one breakpoint it added or changed. */
+  /** Action list gives all breakpoints, remove gives `{removed, id}`; add, enable and disable give the one breakpoint. */
   breakpoint(params: Extract<BreakpointParams, { action: "list" }>): Promise<{ breakpoints: Breakpoint[] }>;
-  breakpoint(params: Exclude<BreakpointParams, { action: "list" }>): Promise<Breakpoint>;
-  breakpoint(params: BreakpointParams): Promise<Breakpoint | { breakpoints: Breakpoint[] }> {
+  breakpoint(params: Extract<BreakpointParams, { action: "remove" }>): Promise<PointRemoved>;
+  breakpoint(params: Exclude<BreakpointParams, { action: "list" | "remove" }>): Promise<Breakpoint>;
+  breakpoint(params: BreakpointParams): Promise<Breakpoint | PointRemoved | { breakpoints: Breakpoint[] }> {
     return this.#request("breakpoint", params);
   }
 
-  /** Action list gives all watchpoints; every other action gives the one watchpoint it added or changed. */
+  /** Action list gives all watchpoints, remove gives `{removed, id}`; add, enable and disable give the one watchpoint. */
   watchpoint(params: Extract<WatchpointParams, { action: "list" }>): Promise<{ watchpoints: Watchpoint[] }>;
-  watchpoint(params: Exclude<WatchpointParams, { action: "list" }>): Promise<Watchpoint>;
-  watchpoint(params: WatchpointParams): Promise<Watchpoint | { watchpoints: Watchpoint[] }> {
+  watchpoint(params: Extract<WatchpointParams, { action: "remove" }>): Promise<PointRemoved>;
+  watchpoint(params: Exclude<WatchpointParams, { action: "list" | "remove" }>): Promise<Watchpoint>;
+  watchpoint(params: WatchpointParams): Promise<Watchpoint | PointRemoved | { watchpoints: Watchpoint[] }> {
     return this.#request("watchpoint", params);
   }
 
@@ -156,6 +178,11 @@ export class ViceSessionClient {
     return this.#request("cpuHistory", params);
   }
 
+  /** Records each hit of the points while the program runs on (D76). */
+  trace(params: ViceOperations["trace"]["params"]): Promise<ViceOperations["trace"]["result"]> {
+    return this.#request("trace", params);
+  }
+
   backtrace(params: ViceOperations["backtrace"]["params"]): Promise<ViceOperations["backtrace"]["result"]> {
     return this.#request("backtrace", params);
   }
@@ -164,12 +191,14 @@ export class ViceSessionClient {
     return this.#request("timing", { action });
   }
 
-  profile(limit: number): Promise<ViceOperations["profile"]["result"]> {
-    return this.#request("profile", { limit });
+  profile(params: { action: "read"; limit: number }): Promise<{ entries: ProfileEntry[] }>;
+  profile(params: { action: "clear" }): Promise<{ cleared: boolean }>;
+  profile(params: ViceOperations["profile"]["params"]): Promise<ViceOperations["profile"]["result"]> {
+    return this.#request("profile", params);
   }
 
   /** Action read gives the ranges; action clear gives cleared. */
-  memmap(params: Extract<ViceOperations["memmap"]["params"], { action: "read" }>): Promise<{ ranges: MemmapRange[] }>;
+  memmap(params: Extract<ViceOperations["memmap"]["params"], { action: "read" }>): Promise<{ ranges: MemmapRange[]; next?: number }>;
   memmap(params: { action: "clear" }): Promise<{ cleared: boolean }>;
   memmap(params: ViceOperations["memmap"]["params"]): Promise<ViceOperations["memmap"]["result"]> {
     return this.#request("memmap", params);
@@ -209,6 +238,19 @@ export class ViceSessionClient {
     return this.#request("snapshot", params);
   }
 
+  /** The bytes of a named snapshot, as a .vsf file holds them (D41). */
+  async snapshotExport(name: string): Promise<Buffer> {
+    const { attachments } = await this.#requestWithAttachments("snapshotFile", { action: "export", name });
+    const [bytes] = attachments;
+    if (bytes === undefined || attachments.length !== 1) throw new WireFailure("operation-failed", "The c64-re-tools host runtime sent no snapshot file.");
+    return bytes;
+  }
+
+  /** Restores the machine from the bytes of a .vsf file; the CPU stays stopped. */
+  snapshotRestore(bytes: Uint8Array): Promise<ViceOperations["snapshotFile"]["result"]> {
+    return this.#request("snapshotFile", { action: "restore" }, [bytes]);
+  }
+
   screenBaselines(): Promise<{ baselines: string[] }> {
     return this.#request("screenBaselines", {});
   }
@@ -226,6 +268,21 @@ export class ViceSessionClient {
     return this.#request("window", { action });
   }
 
+  /** True when the connection to the host is gone, whatever the reason. */
+  get lost(): boolean {
+    return this.#lost !== undefined;
+  }
+
+  /** True when the emulator answered a request: then the session had machine state to lose (D57). */
+  get answered(): boolean {
+    return this.#answered;
+  }
+
+  /** The loss of a lost session, when no request got it; undefined while the session lives (D57). */
+  get unreportedLoss(): WireFailure | undefined {
+    return this.#lost?.code === "machine-state-lost" && !this.#lossReported ? this.#lost : undefined;
+  }
+
   /** Ends the session; the host stops its emulator. Open and later requests fail as closed. */
   async close(): Promise<void> {
     this.#lost ??= new WireFailure("machine-unavailable", SESSION_CLOSED);
@@ -233,16 +290,28 @@ export class ViceSessionClient {
     await this.closed;
   }
 
-  #request<O extends ViceOperation>(
+  async #request<O extends ViceOperation>(
     op: O,
     params: ViceOperations[O]["params"],
     attachments: readonly Uint8Array[] = [],
   ): Promise<ViceOperations[O]["result"]> {
-    if (this.#lost !== undefined) return Promise.reject(this.#lost);
+    return (await this.#requestWithAttachments(op, params, attachments)).result;
+  }
+
+  /** One request; the reply's result and the attachments that came with it. */
+  #requestWithAttachments<O extends ViceOperation>(
+    op: O,
+    params: ViceOperations[O]["params"],
+    attachments: readonly Uint8Array[] = [],
+  ): Promise<{ result: ViceOperations[O]["result"]; attachments: Buffer[] }> {
+    if (this.#lost !== undefined) {
+      this.#lossReported = true;
+      return Promise.reject(this.#lost);
+    }
     const id = this.#nextId;
     this.#nextId = this.#nextId >= 0xffff_ffff ? 1 : this.#nextId + 1;
     return new Promise((resolve, reject) => {
-      this.#pending.set(id, { op, resolve: resolve as (value: unknown) => void, reject });
+      this.#pending.set(id, { op, resolve: (result, received) => resolve({ result: result as ViceOperations[O]["result"], attachments: received }), reject });
       this.#connection.send({ type: "request", id, op, params }, attachments);
     });
   }
@@ -252,3 +321,13 @@ export class ViceSessionClient {
     void this.#connection.close();
   }
 }
+
+
+/** Reads `size` bytes from `address` of the C64 in reads of at most 4 KiB, in one view: up to all 64 KiB (M23.9). */
+export async function readMemoryInParts(client: Pick<ViceSessionClient, "memoryRead">, address: number, size: number, view: "cpu" | "ram"): Promise<Buffer> {
+  const parts: Buffer[] = [];
+  for (let at = address; at < address + size; at += MAX_MEMORY_READ) {
+    parts.push(Buffer.from((await client.memoryRead({ address: at, size: Math.min(MAX_MEMORY_READ, address + size - at), space: "c64", view })).data, "hex"));
+  }
+  return Buffer.concat(parts);
+}

package/src/knowledge/conflicts.ts

@@ -0,0 +1,161 @@
+// Conflicts (D69): current rows that break a current-row rule. One computer
+// never writes them, but git joins the knowledge of two computers line by
+// line, so after a merge two names can be current at one address, or two
+// regions can overlap. Reads show them; writes are refused until a merge
+// revision decides them.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import type { HistoryEntry } from "./history.ts";
+import {
+  COMMENT_COLUMNS,
+  MACRO_COLUMNS,
+  MACRO_USE_COLUMNS,
+  MODULE_COLUMNS,
+  OPERAND_COLUMNS,
+  PATCH_COLUMNS,
+  REFERENCE_COLUMNS,
+  REGION_COLUMNS,
+  SUPPRESSION_COLUMNS,
+  SYMBOL_COLUMNS,
+  toComment,
+  toMacro,
+  toMacroUse,
+  toModule,
+  toOperand,
+  toPatch,
+  toReference,
+  toRegion,
+  toSuppression,
+  toSymbol,
+} from "./read.ts";
+import type { Space } from "./schema.ts";
+import { compareText, sqlName } from "./text.ts";
+
+/** The current-row rules, each with what breaks it. */
+export const CONFLICT_RULES = {
+  "symbol-address": "two symbols at one address",
+  "analyzer-name-address": "two names of one analyzer at one address",
+  "analyzer-name-name": "one analyzer name at two addresses",
+  "symbol-name": "one name at two addresses",
+  region: "regions that overlap",
+  comment: "two comments at one place",
+  reference: "the same reference two times",
+  operand: "two operand expressions at one address",
+  "module-start": "two modules at one address",
+  "module-file": "one module file at two addresses",
+  "suppression-symbol": "the same symbol suppression two times",
+  "suppression-reference": "the same reference suppression two times",
+  "suppression-region": "region suppressions that overlap",
+  patch: "patches that overlap",
+  macro: "two macros with one name",
+  "macro-use": "macro uses that overlap",
+} as const;
+export type ConflictRule = keyof typeof CONFLICT_RULES;
+
+/** One row of a conflict: the row with its revisions and its id. */
+export type ConflictRow = HistoryEntry & { id: string };
+
+/** Current rows that break one rule together, oldest first. */
+export interface Conflict {
+  rule: ConflictRule;
+  space: Space;
+  rows: ConflictRow[];
+}
+
+type Raw = Record<string, unknown>;
+
+interface TableRule {
+  rule: ConflictRule;
+  table: string;
+  entity: HistoryEntry["entity"];
+  columns: string;
+  map: (raw: Raw) => HistoryEntry["row"];
+  /** The columns that must differ between current rows, or "overlap" for address ranges. */
+  key: readonly string[] | "overlap";
+  /** Rows of the table that the rule is about. */
+  where?: string;
+}
+
+const RULES: readonly TableRule[] = [
+  { rule: "symbol-address", table: "symbols", entity: "symbol", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["address"] },
+  { rule: "symbol-name", table: "symbols", entity: "symbol", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["name"] },
+  { rule: "analyzer-name-address", table: "analyzer_names", entity: "analyzer-name", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["address", "origin"] },
+  { rule: "analyzer-name-name", table: "analyzer_names", entity: "analyzer-name", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["name", "origin"] },
+  { rule: "region", table: "regions", entity: "region", columns: REGION_COLUMNS, map: toRegion, key: "overlap" },
+  { rule: "comment", table: "comments", entity: "comment", columns: COMMENT_COLUMNS, map: toComment, key: ["address", "placement"] },
+  { rule: "reference", table: "references", entity: "reference", columns: REFERENCE_COLUMNS, map: toReference, key: ["from_address", "to_address", "kind"] },
+  { rule: "operand", table: "operands", entity: "operand", columns: OPERAND_COLUMNS, map: toOperand, key: ["address"] },
+  { rule: "module-start", table: "modules", entity: "module", columns: MODULE_COLUMNS, map: toModule, key: ["start_address"] },
+  { rule: "module-file", table: "modules", entity: "module", columns: MODULE_COLUMNS, map: toModule, key: ["file"] },
+  { rule: "suppression-symbol", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: ["start_address"], where: "entity = 'symbol'" },
+  {
+    rule: "suppression-reference",
+    table: "suppressions",
+    entity: "suppression",
+    columns: SUPPRESSION_COLUMNS,
+    map: toSuppression,
+    key: ["start_address", "to_address", "kind"],
+    where: "entity = 'reference'",
+  },
+  { rule: "suppression-region", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: "overlap", where: "entity = 'region'" },
+  { rule: "patch", table: "patches", entity: "patch", columns: PATCH_COLUMNS, map: toPatch, key: "overlap" },
+  { rule: "macro", table: "macros", entity: "macro", columns: MACRO_COLUMNS, map: toMacro, key: ["name"] },
+  { rule: "macro-use", table: "macro_uses", entity: "macro-use", columns: MACRO_USE_COLUMNS, map: toMacroUse, key: "overlap" },
+];
+
+function conflictRow(rule: TableRule, raw: Raw): ConflictRow {
+  return { entity: rule.entity, row: rule.map(raw), from: raw.valid_from_revision as string, id: raw.id as string } as ConflictRow;
+}
+
+const byAge = (a: ConflictRow, b: ConflictRow) => compareText(a.from, b.from) || compareText(a.id, b.id);
+
+/** The current rows of one rule that share a key, in groups. */
+function sameKey(db: DatabaseSync, rule: TableRule, key: readonly string[]): Conflict[] {
+  const where = `valid_to_revision IS NULL${rule.where === undefined ? "" : ` AND ${rule.where}`}`;
+  const columns = ["space", ...key].join(", ");
+  const rows = db
+    .prepare(`SELECT ${rule.columns}, id FROM ${sqlName(rule.table)} WHERE ${where} AND (${columns}) IN (SELECT ${columns} FROM ${sqlName(rule.table)} WHERE ${where} GROUP BY ${columns} HAVING count(*) > 1)`)
+    .all() as Raw[];
+  const groups = new Map<string, Conflict>();
+  for (const raw of rows) {
+    const id = JSON.stringify(["space", ...key].map((column) => raw[column]));
+    const group = groups.get(id) ?? { rule: rule.rule, space: raw.space as Space, rows: [] };
+    group.rows.push(conflictRow(rule, raw));
+    groups.set(id, group);
+  }
+  return [...groups.values()];
+}
+
+/** The current rows of one rule whose address ranges overlap, in groups of rows that overlap in a chain. */
+function overlapping(db: DatabaseSync, rule: TableRule): Conflict[] {
+  const rows = db
+    .prepare(`SELECT ${rule.columns}, id FROM ${sqlName(rule.table)} WHERE valid_to_revision IS NULL${rule.where === undefined ? "" : ` AND ${rule.where}`} ORDER BY space, start_address, end_address`)
+    .all() as Raw[];
+  const conflicts: Conflict[] = [];
+  let group: Conflict | undefined;
+  let end = -1;
+  for (const raw of rows) {
+    if (group !== undefined && raw.space === group.space && (raw.start_address as number) <= end) {
+      group.rows.push(conflictRow(rule, raw));
+      end = Math.max(end, raw.end_address as number);
+      continue;
+    }
+    if (group !== undefined && group.rows.length > 1) conflicts.push(group);
+    group = { rule: rule.rule, space: raw.space as Space, rows: [conflictRow(rule, raw)] };
+    end = raw.end_address as number;
+  }
+  if (group !== undefined && group.rows.length > 1) conflicts.push(group);
+  return conflicts;
+}
+
+/** Every conflict of the knowledge, rule by rule; the rows of each, oldest first. */
+export function conflicts(db: DatabaseSync | undefined): Conflict[] {
+  if (db === undefined) return [];
+  return RULES.flatMap((rule) => (rule.key === "overlap" ? overlapping(db, rule) : sameKey(db, rule, rule.key))).map((conflict) => ({ ...conflict, rows: conflict.rows.sort(byAge) }));
+}
+
+/** The table of a conflict rule. */
+export function conflictTable(rule: ConflictRule): string {
+  return RULES.find((item) => item.rule === rule)!.table;
+}