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

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

@@ -0,0 +1,254 @@
+// The long-lived Host Runtime connection an MCP process owns: one connection,
+// 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 { 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.";
+const SESSION_CLOSED = "The C64 session is closed because the c64-re-tools MCP server stops.";
+
+interface Pending {
+  op: ViceOperation;
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+}
+
+export class ViceSessionClient {
+  /** Settles when the session is gone, whether we closed it or the host went away. */
+  readonly closed: Promise<void>;
+  readonly #connection: HostConnection;
+  readonly #pending = new Map<number, Pending>();
+  #nextId = 1;
+  #lost: WireFailure | undefined;
+
+  private constructor(connection: HostConnection) {
+    this.#connection = connection;
+    connection.onMessage((message) => {
+      // 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);
+      if ("error" in message) {
+        pending.reject(new WireFailure(message.error.code, message.error.message));
+        return;
+      }
+      try {
+        pending.resolve(validateViceResult(pending.op, message.result));
+      } catch (error) {
+        pending.reject(
+          new WireFailure(
+            "operation-failed",
+            error instanceof ProtocolError ? "The c64-re-tools host runtime sent an invalid reply." : "The c64-re-tools MCP server could not read the reply of the host runtime.",
+          ),
+        );
+        this.#fail();
+      }
+    });
+    this.closed = connection.closed.then(() => {
+      this.#lost ??= new WireFailure("machine-state-lost", HOST_LOST);
+      for (const pending of this.#pending.values()) pending.reject(this.#lost);
+      this.#pending.clear();
+    });
+  }
+
+  /** Connects and waits until the host has started this session's emulator; `signal` stops the wait at once. */
+  static async open(options: { videoStandard: VideoStandard; env?: NodeJS.ProcessEnv; signal?: AbortSignal }): Promise<ViceSessionClient> {
+    const connection = await HostConnection.open({
+      role: "vice-session",
+      videoStandard: options.videoStandard,
+      ...(options.env === undefined ? {} : { env: options.env }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    return new ViceSessionClient(connection);
+  }
+
+  status(): Promise<MachineStatus> {
+    return this.#request("status", {});
+  }
+
+  memoryRead(params: MemoryReadParams): Promise<MemoryReadResult> {
+    return this.#request("memoryRead", params);
+  }
+
+  registersGet(space: Space): Promise<Registers> {
+    return this.#request("registersGet", { space });
+  }
+
+  memoryWrite(params: MemoryWriteParams): Promise<{ address: number; bytesWritten: number }> {
+    return this.#request("memoryWrite", params);
+  }
+
+  memorySearch(params: ViceOperations["memorySearch"]["params"]): Promise<{ matches: number[] }> {
+    return this.#request("memorySearch", params);
+  }
+
+  memoryCompare(params: ViceOperations["memoryCompare"]["params"]): Promise<ViceOperations["memoryCompare"]["result"]> {
+    return this.#request("memoryCompare", params);
+  }
+
+  disassemble(params: ViceOperations["disassemble"]["params"]): Promise<ViceOperations["disassemble"]["result"]> {
+    return this.#request("disassemble", params);
+  }
+
+  registersSet(space: Space, values: RegisterValues): Promise<Registers> {
+    return this.#request("registersSet", { space, values });
+  }
+
+  execution(params: ExecutionParams): Promise<ExecutionResult> {
+    return this.#request("execution", params);
+  }
+
+  runUntil(params: { target: RunTarget; timeoutFrames: number }): Promise<RunUntilResult> {
+    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);
+    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);
+    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);
+    return this.#request("diskAttach", { type: file.type }, [file.bytes]);
+  }
+
+  reset(params: { mode: ResetMode; run: boolean }): Promise<{ state: RunState; pc?: number }> {
+    return this.#request("reset", params);
+  }
+
+  /** Queues PETSCII bytes for the C64 keyboard. */
+  keyboard(petscii: Uint8Array): Promise<{ queuedBytes: number }> {
+    return this.#request("keyboard", { data: Buffer.from(petscii).toString("hex") });
+  }
+
+  joystick(state: JoystickState): Promise<JoystickState> {
+    return this.#request("joystick", state);
+  }
+
+  /** Action list gives all breakpoints; every other action gives the one breakpoint it added or changed. */
+  breakpoint(params: Extract<BreakpointParams, { action: "list" }>): Promise<{ breakpoints: Breakpoint[] }>;
+  breakpoint(params: Exclude<BreakpointParams, { action: "list" }>): Promise<Breakpoint>;
+  breakpoint(params: BreakpointParams): Promise<Breakpoint | { breakpoints: Breakpoint[] }> {
+    return this.#request("breakpoint", params);
+  }
+
+  /** Action list gives all watchpoints; every other action gives the one watchpoint it added or changed. */
+  watchpoint(params: Extract<WatchpointParams, { action: "list" }>): Promise<{ watchpoints: Watchpoint[] }>;
+  watchpoint(params: Exclude<WatchpointParams, { action: "list" }>): Promise<Watchpoint>;
+  watchpoint(params: WatchpointParams): Promise<Watchpoint | { watchpoints: Watchpoint[] }> {
+    return this.#request("watchpoint", params);
+  }
+
+  cpuHistory(params: ViceOperations["cpuHistory"]["params"]): Promise<ViceOperations["cpuHistory"]["result"]> {
+    return this.#request("cpuHistory", params);
+  }
+
+  backtrace(params: ViceOperations["backtrace"]["params"]): Promise<ViceOperations["backtrace"]["result"]> {
+    return this.#request("backtrace", params);
+  }
+
+  timing(action: ViceOperations["timing"]["params"]["action"]): Promise<ViceOperations["timing"]["result"]> {
+    return this.#request("timing", { action });
+  }
+
+  profile(limit: number): Promise<ViceOperations["profile"]["result"]> {
+    return this.#request("profile", { limit });
+  }
+
+  /** Action read gives the ranges; action clear gives cleared. */
+  memmap(params: Extract<ViceOperations["memmap"]["params"], { action: "read" }>): Promise<{ ranges: MemmapRange[] }>;
+  memmap(params: { action: "clear" }): Promise<{ cleared: boolean }>;
+  memmap(params: ViceOperations["memmap"]["params"]): Promise<ViceOperations["memmap"]["result"]> {
+    return this.#request("memmap", params);
+  }
+
+  vicii(): Promise<ViceOperations["vicii"]["result"]> {
+    return this.#request("vicii", {});
+  }
+
+  /** Empty `indexes` means all eight sprites. */
+  sprites(indexes: number[]): Promise<ViceOperations["sprites"]["result"]> {
+    return this.#request("sprites", { indexes });
+  }
+
+  cia(which: ViceOperations["cia"]["params"]["which"]): Promise<ViceOperations["cia"]["result"]> {
+    return this.#request("cia", { which });
+  }
+
+  sid(): Promise<ViceOperations["sid"]["result"]> {
+    return this.#request("sid", {});
+  }
+
+  observe(params: ViceOperations["observe"]["params"]): Promise<ViceOperations["observe"]["result"]> {
+    return this.#request("observe", params);
+  }
+
+  /** The last frame the VIC-II drew, as a base64 PNG with its size. */
+  screenCapture(baseline?: string): Promise<ViceOperations["screenCapture"]["result"]> {
+    return this.#request("screenCapture", baseline === undefined ? {} : { baseline });
+  }
+
+  screenCompare(params: ViceOperations["screenCompare"]["params"]): Promise<ViceOperations["screenCompare"]["result"]> {
+    return this.#request("screenCompare", params);
+  }
+
+  snapshot(params: ViceOperations["snapshot"]["params"]): Promise<ViceOperations["snapshot"]["result"]> {
+    return this.#request("snapshot", params);
+  }
+
+  screenBaselines(): Promise<{ baselines: string[] }> {
+    return this.#request("screenBaselines", {});
+  }
+
+  screenDiscard(baseline: string): Promise<{ discarded: boolean }> {
+    return this.#request("screenDiscard", { baseline });
+  }
+
+  warp(enabled: boolean): Promise<{ enabled: boolean }> {
+    return this.#request("warp", { enabled });
+  }
+
+  /** Moves the machine into a VICE with a window (open) or back into a headless one (close). */
+  window(action: ViceOperations["window"]["params"]["action"]): Promise<ViceOperations["window"]["result"]> {
+    return this.#request("window", { action });
+  }
+
+  /** 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);
+    await this.#connection.close();
+    await this.closed;
+  }
+
+  #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);
+    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.#connection.send({ type: "request", id, op, params }, attachments);
+    });
+  }
+
+  /** Drops a connection whose host broke the protocol; pending work fails as lost. */
+  #fail(): void {
+    void this.#connection.close();
+  }
+}

package/src/knowledge/database.ts

@@ -0,0 +1,132 @@
+// The one place that opens .c64-re-tools/knowledge.db.
+
+import { existsSync, mkdirSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+
+import { projectRoot } from "../project.ts";
+import { checkVersion, ensureSchema, schemaVersion } from "./schema.ts";
+
+export const KNOWLEDGE_DIRECTORY = ".c64-re-tools";
+export const KNOWLEDGE_FILE = "knowledge.db";
+
+export const KNOWLEDGE_ERROR_CODES = [
+  "invalid-input",
+  "not-found",
+  "conflict",
+  "stale-revision",
+  "invalid-database",
+  "unsupported-schema",
+] as const;
+export type KnowledgeErrorCode = (typeof KNOWLEDGE_ERROR_CODES)[number];
+
+/** A refused knowledge operation, with a stable code and an actionable message. */
+export class KnowledgeError extends Error {
+  override name = "KnowledgeError";
+  readonly code: KnowledgeErrorCode;
+
+  constructor(code: KnowledgeErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function knowledgePath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, KNOWLEDGE_FILE);
+}
+
+function configure(db: DatabaseSync): void {
+  // A committed write must be complete in knowledge.db itself: rollback journal, never WAL.
+  db.exec("PRAGMA journal_mode = DELETE; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+}
+
+function open(path: string, readOnly: boolean): DatabaseSync {
+  let db: DatabaseSync;
+  try {
+    db = new DatabaseSync(path, { readOnly });
+    configure(db);
+    db.prepare("SELECT count(*) FROM sqlite_master").get();
+  } catch (error) {
+    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${KNOWLEDGE_FILE} is not a readable SQLite database: ${(error as Error).message}`);
+  }
+  return db;
+}
+
+/**
+ * Opens the project's knowledge database read-only, as it is: a read never
+ * migrates and never writes. Returns undefined when the database does not
+ * exist or has no schema yet: that reads as empty knowledge, and a read
+ * creates nothing. Refuses a schema version other than this build's.
+ */
+export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
+  const path = knowledgePath(root);
+  if (!existsSync(path)) return undefined;
+  const db = open(path, true);
+  try {
+    const version = schemaVersion(db);
+    if (version === 0) {
+      db.close();
+      return undefined;
+    }
+    checkVersion(version);
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+  return db;
+}
+
+/**
+ * Opens the project's knowledge database for a write, creating
+ * .c64-re-tools/knowledge.db and its schema when needed. Refuses a schema
+ * version other than this build's.
+ */
+export function openForWrite(root: string = projectRoot()): DatabaseSync {
+  mkdirSync(join(root, KNOWLEDGE_DIRECTORY), { recursive: true });
+  const db = open(knowledgePath(root), false);
+  try {
+    ensureSchema(db);
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+  return db;
+}
+
+/**
+ * Runs one write on the project's knowledge database and closes it. When the
+ * project has no knowledge.db yet, `work` first runs on an empty database in
+ * memory: a write that is refused there creates no .c64-re-tools/. `work`
+ * must change nothing outside the database it gets.
+ */
+export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = projectRoot()): T {
+  if (!existsSync(knowledgePath(root))) {
+    const trial = new DatabaseSync(":memory:");
+    try {
+      configure(trial);
+      ensureSchema(trial);
+      work(trial);
+    } finally {
+      trial.close();
+    }
+  }
+  const db = openForWrite(root);
+  try {
+    return work(db);
+  } finally {
+    db.close();
+  }
+}
+
+/** Runs `work` in one immediate transaction: all of it commits, or none of it does. */
+export function transaction<T>(db: DatabaseSync, work: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = work();
+    db.exec("COMMIT");
+    return result;
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}

package/src/knowledge/history.ts

@@ -0,0 +1,128 @@
+// Knowledge history: what used to be known, which revision changed
+// it, who changed it and why. History rows are never deleted.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import { KnowledgeError } from "./database.ts";
+import {
+  COMMENT_COLUMNS,
+  REFERENCE_COLUMNS,
+  REGION_COLUMNS,
+  SYMBOL_COLUMNS,
+  toComment,
+  toReference,
+  toRegion,
+  toSymbol,
+  type CommentRow,
+  type ReferenceRow,
+  type RegionRow,
+  type SymbolRow,
+} from "./read.ts";
+import type { Origin } from "./schema.ts";
+
+export interface Revision {
+  id: number;
+  createdAt: string;
+  origin: Origin;
+  operation: string;
+  description?: string;
+  inputHash?: string;
+  toolVersion?: string;
+}
+
+/** One knowledge row with its validity: from its first revision until the revision that closed it. */
+export type HistoryEntry =
+  | { entity: "symbol"; row: SymbolRow; from: number; to?: number }
+  | { entity: "region"; row: RegionRow; from: number; to?: number }
+  | { entity: "comment"; row: CommentRow; from: number; to?: number }
+  | { entity: "reference"; row: ReferenceRow; from: number; to?: number };
+
+type Raw = Record<string, unknown>;
+
+function toRevision(row: Raw): Revision {
+  const revision: Revision = {
+    id: row.id as number,
+    createdAt: row.created_at as string,
+    origin: row.origin as Origin,
+    operation: row.operation as string,
+  };
+  if (row.description !== null) revision.description = row.description as string;
+  if (row.input_hash !== null) revision.inputHash = row.input_hash as string;
+  if (row.tool_version !== null) revision.toolVersion = row.tool_version as string;
+  return revision;
+}
+
+function entry<E extends HistoryEntry["entity"]>(entity: E, row: unknown, raw: Raw): HistoryEntry {
+  const result = { entity, row, from: raw.valid_from_revision as number } as HistoryEntry;
+  if (raw.valid_to_revision !== null) result.to = raw.valid_to_revision as number;
+  return result;
+}
+
+function bySequence(a: HistoryEntry, b: HistoryEntry): number {
+  return a.from - b.from || (a.to ?? Infinity) - (b.to ?? Infinity);
+}
+
+/** Every row, current or closed, that concerns one address, oldest first. */
+export function historyAt(db: DatabaseSync | undefined, address: number): HistoryEntry[] {
+  if (db === undefined) return [];
+  const validity = ", valid_to_revision";
+  const entries: HistoryEntry[] = [];
+  for (const raw of db.prepare(`SELECT ${SYMBOL_COLUMNS}${validity} FROM symbols WHERE address = ?`).all(address) as Raw[]) entries.push(entry("symbol", toSymbol(raw), raw));
+  for (const raw of db.prepare(`SELECT ${REGION_COLUMNS}${validity} FROM regions WHERE start_address <= ? AND end_address >= ?`).all(address, address) as Raw[]) {
+    entries.push(entry("region", toRegion(raw), raw));
+  }
+  for (const raw of db.prepare(`SELECT ${COMMENT_COLUMNS}${validity} FROM comments WHERE address = ?`).all(address) as Raw[]) entries.push(entry("comment", toComment(raw), raw));
+  for (const raw of db.prepare(`SELECT ${REFERENCE_COLUMNS}${validity} FROM "references" WHERE from_address = ? OR to_address = ?`).all(address, address) as Raw[]) {
+    entries.push(entry("reference", toReference(raw), raw));
+  }
+  return entries.sort(bySequence);
+}
+
+/** Every symbol row that ever had this name, oldest first: a name can move between addresses. */
+export function historyNamed(db: DatabaseSync | undefined, name: string): HistoryEntry[] {
+  if (db === undefined) return [];
+  return (db.prepare(`SELECT ${SYMBOL_COLUMNS}, valid_to_revision FROM symbols WHERE name = ?`).all(name) as Raw[])
+    .map((raw) => entry("symbol", toSymbol(raw), raw))
+    .sort(bySequence);
+}
+
+/** Revisions, newest first; with `before`, only revisions older than it. */
+export function revisions(db: DatabaseSync | undefined, options: { limit?: number; before?: number } = {}): Revision[] {
+  if (db === undefined) return [];
+  return (
+    db
+      .prepare("SELECT * FROM revisions WHERE id < ? ORDER BY id DESC LIMIT ?")
+      .all(options.before ?? Number.MAX_SAFE_INTEGER, options.limit ?? 50) as Raw[]
+  ).map(toRevision);
+}
+
+export interface RevisionChanges {
+  revision: Revision;
+  /** Rows this revision made current. */
+  added: HistoryEntry[];
+  /** Rows this revision closed. */
+  closed: HistoryEntry[];
+}
+
+/** One revision and exactly what it changed. */
+export function revision(db: DatabaseSync | undefined, id: number): RevisionChanges {
+  const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
+  if (db === undefined || raw === undefined) throw new KnowledgeError("not-found", `There is no revision ${id}.`);
+  const tables = [
+    ["symbol", "symbols", SYMBOL_COLUMNS, toSymbol],
+    ["region", "regions", REGION_COLUMNS, toRegion],
+    ["comment", "comments", COMMENT_COLUMNS, toComment],
+    ["reference", '"references"', REFERENCE_COLUMNS, toReference],
+  ] as const;
+  const added: HistoryEntry[] = [];
+  const closed: HistoryEntry[] = [];
+  for (const [entity, table, columns, map] of tables) {
+    for (const row of db.prepare(`SELECT ${columns}, valid_to_revision FROM ${table} WHERE valid_from_revision = ?`).all(id) as Raw[]) {
+      added.push(entry(entity, map(row), row));
+    }
+    for (const row of db.prepare(`SELECT ${columns}, valid_to_revision FROM ${table} WHERE valid_to_revision = ?`).all(id) as Raw[]) {
+      closed.push(entry(entity, map(row), row));
+    }
+  }
+  return { revision: toRevision(raw), added, closed };
+}