c64bridge 0.8.1 → 0.9.1

package/dist/vice/process.js

@@ -3,10 +3,37 @@ import fs from "node:fs";
 import net from "node:net";
 import { createOutputTailCapture, getDiagnosticsSessionInfo, writeDiagnosticEvent } from "../diagnostics.js";
 const DEFAULT_DISPLAY = ":99";
+function hasDisplayArtifacts(display) {
+    const match = /^:([0-9]+)$/.exec(display.trim());
+    if (!match) {
+        return false;
+    }
+    const displayNumber = match[1];
+    return fs.existsSync(`/tmp/.X11-unix/X${displayNumber}`) || fs.existsSync(`/tmp/.X${displayNumber}-lock`);
+}
+export function resolveXvfbDisplayForLaunch(display) {
+    const explicitDisplay = process.env.VICE_XVFB_DISPLAY?.trim();
+    if (explicitDisplay) {
+        return explicitDisplay;
+    }
+    if (display !== DEFAULT_DISPLAY || !hasDisplayArtifacts(display)) {
+        return display;
+    }
+    const baseDisplay = Number.parseInt(display.slice(1), 10);
+    for (let candidate = baseDisplay + 1; candidate < baseDisplay + 100; candidate += 1) {
+        const candidateDisplay = `:${candidate}`;
+        if (!hasDisplayArtifacts(candidateDisplay)) {
+            return candidateDisplay;
+        }
+    }
+    return display;
+}
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function hasGraphicalSession() {
+    if (process.platform === "darwin" || process.platform === "win32")
+        return true;
     return configuredDisplay() !== undefined || configuredWaylandDisplay() !== undefined;
 }
 function configuredDisplay() {
@@ -64,6 +91,53 @@ export async function waitForPort(host, port, timeoutMs = 4000) {
     }
     throw new Error(`Timeout waiting for VICE monitor at ${host}:${port}`);
 }
+async function sendResumeMonitorCommand(host, port, timeoutMs = 1500) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            await new Promise((resolve, reject) => {
+                const socket = net.connect({ host, port });
+                const cleanup = () => {
+                    socket.removeAllListeners();
+                    socket.destroy();
+                };
+                const packet = Buffer.alloc(11);
+                packet[0] = 0x02;
+                packet[1] = 0x02;
+                packet.writeUInt32LE(0, 2);
+                packet.writeUInt32LE(1, 6);
+                packet[10] = 0xaa;
+                socket.setTimeout(500, () => {
+                    cleanup();
+                    reject(new Error(`Timed out sending VICE monitor resume command to ${host}:${port}`));
+                });
+                socket.once("error", (error) => {
+                    cleanup();
+                    reject(error);
+                });
+                socket.once("connect", () => {
+                    socket.write(packet, (error) => {
+                        cleanup();
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        resolve();
+                    });
+                });
+            });
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            await delay(50);
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Failed to resume VICE monitor at ${host}:${port}`);
+}
 async function waitForXvfb(display, timeoutMs = 5000) {
     const match = /^:([0-9]+)/.exec(display.trim());
     if (!match) {
@@ -113,7 +187,19 @@ export async function terminateProcess(child, signal = "SIGTERM", timeoutMs = 10
 }
 export async function startViceProcess(options) {
     const debugEnabled = process.env.VICE_DEVICE_TEST_DEBUG === "1";
-    const { useXvfb, display } = shouldUseXvfb(options.visible);
+    // When headless=true, skip Xvfb entirely and rely on VICE's own -headless flag (VICE 3.5+).
+    const useHeadless = options.headless === true || process.env.VICE_HEADLESS === "1";
+    let useXvfb;
+    let display;
+    if (useHeadless) {
+        useXvfb = false;
+        display = "";
+    }
+    else {
+        const probe = shouldUseXvfb(options.visible);
+        useXvfb = probe.useXvfb;
+        display = useXvfb ? resolveXvfbDisplayForLaunch(probe.display) : probe.display;
+    }
     const viceEnv = { ...process.env };
     let xvfb = null;
     const xvfbOutput = createOutputTailCapture("xvfb");
@@ -123,6 +209,7 @@ export async function startViceProcess(options) {
         directory: options.directory,
         display,
         extraArgs: options.extraArgs ?? [],
+        headless: useHeadless,
         host: options.host,
         port: options.port,
         useXvfb,
@@ -157,12 +244,14 @@ export async function startViceProcess(options) {
         });
         viceEnv.DISPLAY = display;
         await waitForXvfb(display);
+        await delay(300);
     }
     const args = [
         "-binarymonitor",
         "-binarymonitoraddress", `${options.host}:${options.port}`,
         "-sounddev", "dummy",
         "-config", "/dev/null",
+        ...(useHeadless ? ["-headless"] : []),
         ...(options.directory ? ["-directory", options.directory] : []),
         ...(options.extraArgs ?? []),
     ];
@@ -216,7 +305,8 @@ export async function startViceProcess(options) {
             child.once("exit", onExit);
             child.once("error", onError);
             waitForPort(options.host, options.port)
-                .then(() => {
+                .then(async () => {
+                await sendResumeMonitorCommand(options.host, options.port);
                 if (debugEnabled) {
                     console.error("[vice-process] monitor port is ready", { host: options.host, port: options.port });
                 }
@@ -293,15 +383,43 @@ export async function startViceProcess(options) {
     });
     return { host: options.host, port: options.port, process: child, stop };
 }
+function isIgnorableSocketDirError(error) {
+    if (!error || typeof error !== "object" || !("code" in error)) {
+        return false;
+    }
+    const code = String(error.code ?? "");
+    return code === "EACCES" || code === "EPERM" || code === "EROFS" || code === "EEXIST";
+}
 export function ensureXvfbSocketDir(debugEnabled) {
     const socketDir = "/tmp/.X11-unix";
     try {
         if (!fs.existsSync(socketDir)) {
             fs.mkdirSync(socketDir, { mode: 0o1777 });
         }
+    }
+    catch (error) {
+        if (isIgnorableSocketDirError(error)) {
+            if (debugEnabled) {
+                console.error("[vice-process] unable to create Xvfb socket dir; continuing", error);
+            }
+            return;
+        }
+        writeDiagnosticEvent("xvfb_socket_dir_failed", { socketDir, error });
+        if (debugEnabled) {
+            console.error("[vice-process] failed to prepare Xvfb socket dir", error);
+        }
+        return;
+    }
+    try {
         fs.chmodSync(socketDir, 0o1777);
     }
     catch (error) {
+        if (isIgnorableSocketDirError(error)) {
+            if (debugEnabled) {
+                console.error("[vice-process] unable to chmod Xvfb socket dir; continuing", error);
+            }
+            return;
+        }
         writeDiagnosticEvent("xvfb_socket_dir_failed", { socketDir, error });
         if (debugEnabled) {
             console.error("[vice-process] failed to prepare Xvfb socket dir", error);

package/dist/vice/readiness.js

@@ -30,6 +30,41 @@ export async function waitForScreenPattern(bm, pattern, timeoutMs, tickMs = 50,
     await exitMonitorIfNeeded(bm);
     return idx;
 }
+export async function waitForStableScreenPattern(bm, pattern, timeoutMs, tickMs = 50, stableReads = 2, onRead, between) {
+    const requiredStableReads = Math.max(1, stableReads);
+    const start = nowNs();
+    let idx = -1;
+    let stableIdx = -1;
+    let consecutiveMatches = 0;
+    while (msSince(start) < timeoutMs) {
+        const t = nowNs();
+        const screen = await bm.memGet(0x0400, 0x0400 + 999);
+        onRead?.("bm_read_screen", t);
+        idx = screen.indexOf(pattern);
+        if (idx >= 0) {
+            if (idx === stableIdx) {
+                consecutiveMatches += 1;
+            }
+            else {
+                stableIdx = idx;
+                consecutiveMatches = 1;
+            }
+            if (consecutiveMatches >= requiredStableReads) {
+                break;
+            }
+        }
+        else {
+            stableIdx = -1;
+            consecutiveMatches = 0;
+        }
+        await exitMonitorIfNeeded(bm);
+        if (between)
+            await between();
+        await new Promise((r) => setTimeout(r, Math.max(1, tickMs)));
+    }
+    await exitMonitorIfNeeded(bm);
+    return consecutiveMatches >= requiredStableReads ? idx : -1;
+}
 /** Wait until any non-blank (non-0x00/0x20) character appears on the text screen. */
 export async function waitForAnyScreenText(bm, timeoutMs, tickMs = 50, onRead, between) {
     const start = nowNs();

package/dist/vice/smokeOptions.js

@@ -0,0 +1,44 @@
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+function parseVicePort(value) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        return { configuredPort: 6502, hasExplicitPort: false };
+    }
+    const parsed = Number(normalized);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return { configuredPort: 6502, hasExplicitPort: false };
+    }
+    return { configuredPort: parsed, hasExplicitPort: true };
+}
+export function parseEnvBoolean(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (TRUE_VALUES.has(normalized)) {
+        return true;
+    }
+    if (FALSE_VALUES.has(normalized)) {
+        return false;
+    }
+    return undefined;
+}
+export function resolveViceSmokeOptions(env = process.env, argv = process.argv.slice(2)) {
+    const visibleDemo = argv.includes("--visible-demo") || parseEnvBoolean(env.VICE_VISIBLE_DEMO) === true;
+    const useMock = String(env.VICE_TEST_TARGET ?? "").trim().toLowerCase() === "mock";
+    const { configuredPort, hasExplicitPort } = parseVicePort(env.VICE_PORT);
+    const visible = visibleDemo || parseEnvBoolean(env.VICE_VISIBLE) === true;
+    const keepOpen = visibleDemo || parseEnvBoolean(env.VICE_KEEP_OPEN) === true;
+    const warpSetting = parseEnvBoolean(env.VICE_WARP);
+    return {
+        useMock,
+        configuredPort,
+        hasExplicitPort,
+        visible,
+        keepOpen,
+        warp: useMock ? true : visibleDemo ? false : warpSetting ?? true,
+        display: env.DISPLAY || ":99",
+        visibleDemo,
+    };
+}

package/dist/vice/viceClient.js

@@ -9,6 +9,9 @@ export class ViceClient {
         this.pending = new Map();
         this.closing = false;
     }
+    setUnsolicitedHandler(handler) {
+        this.onUnsolicitedHandler = handler;
+    }
     async connect(port, host = "127.0.0.1") {
         this.socket = net.connect({ host, port });
         this.closing = false;
@@ -77,7 +80,8 @@ export class ViceClient {
             const err = frame[7];
             const reqId = frame.readUInt32LE(8);
             if (reqId === 0xffffffff) {
-                continue; // unsolicited event
+                this.onUnsolicitedHandler?.(responseType, frame);
+                continue;
             }
             const pending = this.pending.get(reqId);
             if (!pending) {

package/dist/viceRunner.js

@@ -65,6 +65,8 @@ function which(binary) {
     return null;
 }
 function shouldUseXvfb() {
+    if (process.platform === "darwin" || process.platform === "win32")
+        return false;
     if (process.env.FORCE_XVFB === "1")
         return true;
     const ciValue = (process.env.CI || "").toLowerCase();

package/doc/plans/prompts/README.md

@@ -27,13 +27,13 @@ suite can assert expectations in upcoming steps.
 
 | Family | Baseline Resources (URIs) | Rationale |
 | --- | --- | --- |
-| `basic-program` | `c64://specs/basic`, `c64://context/bootstrap`, `c64://docs/index` | Reinforce BASIC token rules, PETSCII gotchas, workflow expectations. |
-| `assembly-program` | `c64://specs/assembly`, `c64://context/bootstrap`, `c64://specs/vic`, `c64://specs/sid` | Provide opcode tables, IRQ setup, VIC/SID register references. |
-| `sid-music` | `c64://specs/sid`, `c64://specs/sidwave`, `c64://docs/sid/file-structure` | Supply register map, SIDWAVE format, SID file metadata. |
-| `graphics-demo` | `c64://specs/vic`, `c64://context/bootstrap` | Cover VIC mode bits, raster constraints, general workflow guidance. |
-| `printer-job` | `c64://specs/printer`, `c64://docs/printer/guide`, `c64://docs/printer/prompts` | Document PETSCII vs ESC/P workflows, sample templates, and safety checks. |
-| `memory-debug` | `c64://context/bootstrap`, `c64://specs/assembly`, `c64://docs/index` | Highlight addressing safeguards, workflow rules, and knowledge map summaries. |
-| `drive-manager` | `c64://context/bootstrap` | Ensure awareness of system-wide safety rules before altering drives. |
+| `basic-program` | `c64://basic/spec`, `c64://guide/bootstrap`, `c64://guide/index` | Reinforce BASIC token rules, PETSCII gotchas, workflow expectations. |
+| `assembly-program` | `c64://assembly/6510-spec`, `c64://guide/bootstrap`, `c64://graphics/vic/spec`, `c64://sound/sid/spec` | Provide opcode tables, IRQ setup, VIC/SID register references. |
+| `sid-music` | `c64://sound/sid/spec`, `c64://sound/sidwave/spec`, `c64://sound/sid/file-format` | Supply register map, SIDWAVE format, SID file metadata. |
+| `graphics-demo` | `c64://graphics/vic/spec`, `c64://guide/bootstrap` | Cover VIC mode bits, raster constraints, general workflow guidance. |
+| `printer-job` | `c64://printer/spec`, `c64://printer/commodore/text`, `c64://printer/prompt-guide` | Document PETSCII vs ESC/P workflows, sample templates, and safety checks. |
+| `memory-debug` | `c64://guide/bootstrap`, `c64://assembly/6510-spec`, `c64://guide/index` | Highlight addressing safeguards, workflow rules, and knowledge map summaries. |
+| `drive-manager` | `c64://guide/bootstrap` | Ensure awareness of system-wide safety rules before altering drives. |
 
 Notes:
 

package/mcp/prompts.json

@@ -6,9 +6,9 @@
       "description": "Route ultra-fast hello-world and smoke-test requests to the canonical greeting skill.",
       "_meta": {
         "requiredResources": [
-          "c64://context/bootstrap",
-          "c64://context/fast-paths",
-          "c64://docs/index"
+          "c64://guide/bootstrap",
+          "c64://guide/fast-paths",
+          "c64://guide/index"
         ],
         "optionalResources": [],
         "tools": [
@@ -29,12 +29,12 @@
       "description": "Route bespoke Commodore BASIC v2 requests to the canonical BASIC skill.",
       "_meta": {
         "requiredResources": [
-          "c64://specs/basic",
-          "c64://context/bootstrap",
-          "c64://docs/index"
+          "c64://basic/spec",
+          "c64://guide/bootstrap",
+          "c64://guide/index"
         ],
         "optionalResources": [
-          "c64://context/fast-paths"
+          "c64://guide/fast-paths"
         ],
         "tools": [
           "c64_program",
@@ -53,9 +53,9 @@
       "description": "Route quick visible demo requests to the cross-platform demo skill.",
       "_meta": {
         "requiredResources": [
-          "c64://context/bootstrap",
-          "c64://context/fast-paths",
-          "c64://docs/index"
+          "c64://guide/bootstrap",
+          "c64://guide/fast-paths",
+          "c64://guide/index"
         ],
         "optionalResources": [],
         "tools": [
@@ -75,12 +75,12 @@
       "description": "Route quick recognizable tune requests to the SID music skill.",
       "_meta": {
         "requiredResources": [
-          "c64://specs/sid",
-          "c64://specs/sidwave",
-          "c64://context/fast-paths"
+          "c64://sound/sid/spec",
+          "c64://sound/sidwave/spec",
+          "c64://guide/fast-paths"
         ],
         "optionalResources": [
-          "c64://docs/sid/best-practices"
+          "c64://sound/sid/best-practices"
         ],
         "tools": [
           "c64_sound"
@@ -100,24 +100,18 @@
       "arguments": [
         {
           "name": "hardware",
-          "description": "Optional focus area for the routine (sid, vic, cia, or multi for combined work).",
-          "options": [
-            "sid",
-            "vic",
-            "cia",
-            "multi"
-          ]
+          "description": "Optional focus area for the routine (sid, vic, cia, or multi for combined work)."
         }
       ],
       "_meta": {
         "requiredResources": [
-          "c64://specs/assembly",
-          "c64://specs/vic",
-          "c64://specs/sid",
-          "c64://context/bootstrap"
+          "c64://assembly/6510-spec",
+          "c64://graphics/vic/spec",
+          "c64://sound/sid/spec",
+          "c64://guide/bootstrap"
         ],
         "optionalResources": [
-          "c64://docs/sid/best-practices"
+          "c64://sound/sid/best-practices"
         ],
         "tools": [
           "c64_program",
@@ -143,13 +137,13 @@
       "description": "Route SID playback and composition work to the canonical SID skill.",
       "_meta": {
         "requiredResources": [
-          "c64://specs/sid",
-          "c64://specs/sidwave",
-          "c64://docs/sid/file-structure",
-          "c64://docs/sid/best-practices"
+          "c64://sound/sid/spec",
+          "c64://sound/sidwave/spec",
+          "c64://sound/sid/file-format",
+          "c64://sound/sid/best-practices"
         ],
         "optionalResources": [
-          "c64://context/fast-paths"
+          "c64://guide/fast-paths"
         ],
         "tools": [
           "c64_sound"
@@ -168,24 +162,18 @@
       "arguments": [
         {
           "name": "mode",
-          "description": "Target VIC-II technique (text, multicolour, bitmap, or sprite).",
-          "options": [
-            "text",
-            "multicolour",
-            "bitmap",
-            "sprite"
-          ]
+          "description": "Target VIC-II technique (text, multicolour, bitmap, or sprite)."
         }
       ],
       "_meta": {
         "requiredResources": [
-          "c64://specs/vic",
-          "c64://context/bootstrap"
+          "c64://graphics/vic/spec",
+          "c64://guide/bootstrap"
         ],
         "optionalResources": [
-          "c64://specs/assembly",
-          "c64://specs/charset",
-          "c64://docs/petscii-style"
+          "c64://assembly/6510-spec",
+          "c64://graphics/character-set",
+          "c64://graphics/petscii/style-guide"
         ],
         "tools": [
           "c64_program",
@@ -213,24 +201,19 @@
       "arguments": [
         {
           "name": "printerType",
-          "description": "Select Commodore (device 4) or Epson FX workflow helpers.",
-          "options": [
-            "commodore",
-            "epson"
-          ]
+          "description": "Select Commodore (device 4) or Epson FX workflow helpers."
         }
       ],
       "_meta": {
         "requiredResources": [
-          "c64://specs/printer",
-          "c64://docs/printer/guide",
-          "c64://docs/printer/prompts"
+          "c64://printer/spec",
+          "c64://printer/prompt-guide"
         ],
         "optionalResources": [
-          "c64://docs/printer/commodore-text",
-          "c64://docs/printer/commodore-bitmap",
-          "c64://docs/printer/epson-text",
-          "c64://docs/printer/epson-bitmap"
+          "c64://printer/commodore/text",
+          "c64://printer/commodore/bitmap",
+          "c64://printer/epson/text",
+          "c64://printer/epson/bitmap"
         ],
         "tools": [
           "c64_printer"
@@ -252,9 +235,9 @@
       "description": "Route reversible memory inspection or patching work to the canonical memory skill.",
       "_meta": {
         "requiredResources": [
-          "c64://context/bootstrap",
-          "c64://specs/assembly",
-          "c64://docs/index"
+          "c64://guide/bootstrap",
+          "c64://assembly/6510-spec",
+          "c64://guide/index"
         ],
         "optionalResources": [],
         "tools": [
@@ -274,7 +257,7 @@
       "description": "Route disk-image and drive-state requests to the canonical drive skill.",
       "_meta": {
         "requiredResources": [
-          "c64://context/bootstrap"
+          "c64://guide/bootstrap"
         ],
         "optionalResources": [],
         "tools": [

package/mcp/protocol-examples.json

@@ -1,5 +1,5 @@
 {
-  "protocolVersion": "2025-06-18",
+  "protocolVersion": "2025-11-25",
   "examples": {
     "initialize": {
       "description": "Client initialization request sent immediately after connecting to the stdio MCP server.",
@@ -8,7 +8,7 @@
         "id": 1,
         "method": "initialize",
         "params": {
-          "protocolVersion": "2025-06-18",
+          "protocolVersion": "2025-11-25",
           "capabilities": {
             "resources": {},
             "tools": {},