c64bridge 1.0.0 → 1.0.2

package/dist/c64Client.js

@@ -18,6 +18,17 @@ import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { withDiagnosticSpan, writeDiagnosticEvent } from "./diagnostics.js";
 import { C64U_NTSC_AUDIO_SAMPLE_RATE, C64U_PAL_AUDIO_SAMPLE_RATE, collectCompleteVideoFrames, parseAudioPacket, parseVideoPacket, } from "./streamCapture.js";
 import { buildVicBitmapRegisters, resolveVicBitmapMemoryLayout, } from "./vicBitmap.js";
+/** Raised when the KERNAL keyboard buffer did not drain before another chunk
+ * could safely be queued. Callers must report this as partial delivery. */
+export class KeyboardQueueDrainTimeoutError extends Error {
+    constructor(delivered, requested, timeoutMs) {
+        super(`Keyboard queue did not drain after ${timeoutMs}ms; delivered ${delivered} of ${requested} byte(s). Resume the machine and retry the remaining input.`);
+        this.name = "KeyboardQueueDrainTimeoutError";
+        this.delivered = delivered;
+        this.requested = requested;
+        this.timeoutMs = timeoutMs;
+    }
+}
 function menuMatrixIncludes(matrix, expected) {
     // Firmware supplies the character matrix followed by its colour matrix. The
     // documented wire format is raw bytes, so only inspect the first 40×25
@@ -27,6 +38,38 @@ function menuMatrixIncludes(matrix, expected) {
     return [screenCodesToAscii(characters), petsciiToAscii(characters)]
         .some((text) => text.replace(/\s+/g, " ").toUpperCase().includes(normalizedExpected));
 }
+function selectedMenuRow(matrix) {
+    // The firmware contract exposes a 40x25 character matrix followed by its
+    // colour matrix. A selected menu row is rendered with one uniform colour
+    // distinct from the normal rows. Reject malformed/ambiguous matrices.
+    if (matrix.length < 2000)
+        return null;
+    const colours = matrix.subarray(1000, 2000);
+    const rows = [];
+    for (let row = 0; row < 25; row += 1) {
+        const cells = colours.subarray(row * 40, row * 40 + 40);
+        if (cells.length === 40 && cells.every((value) => value === cells[0]))
+            rows.push(row);
+    }
+    if (rows.length === 0)
+        return null;
+    const normal = new Map();
+    for (const row of rows)
+        normal.set(colours[row * 40], (normal.get(colours[row * 40]) ?? 0) + 1);
+    const [colour, count] = [...normal.entries()].sort((a, b) => b[1] - a[1])[0] ?? [];
+    if (colour === undefined || count === undefined)
+        return null;
+    const selected = rows.filter((row) => colours[row * 40] !== colour);
+    return selected.length === 1 ? selected[0] : null;
+}
+function selectedMenuRowIncludes(matrix, expected) {
+    const row = selectedMenuRow(matrix);
+    if (row === null)
+        return false;
+    const text = [screenCodesToAscii(matrix.subarray(row * 40, row * 40 + 40)), petsciiToAscii(matrix.subarray(row * 40, row * 40 + 40))]
+        .map((value) => value.replace(/\s+/g, " ").toUpperCase());
+    return text.some((value) => value.includes(expected.replace(/\s+/g, " ").toUpperCase()));
+}
 function isMissingEndpoint(error) {
     return axios.isAxiosError(error) && error.response?.status === 404;
 }
@@ -101,6 +144,15 @@ export class C64Client {
     async getBackendType() {
         return this.getActiveBackendType();
     }
+    /**
+     * Snapshot the facade currently active for this invocation. A multi-step
+     * flow (pause/read/write/resume, or repeated polling) must resolve the
+     * facade once and reuse that same instance for every step, so a concurrent
+     * `switchBackend` cannot retarget an operation already underway.
+     */
+    async pinFacade() {
+        return this.facadePromise;
+    }
     async getActiveBackendType() {
         await this.initPromise;
         return this.activeType;
@@ -124,6 +176,13 @@ export class C64Client {
                 .then(() => "available")
                 .catch((error) => isMissingEndpoint(error) ? "unavailable" : "unknown");
             this.machineInputCapabilityProbes.set(facade.type, probe);
+            // A transport error is not a capability result. Keep confirmed states,
+            // but make a later resource read retry rather than poisoning the cache.
+            void probe.then((result) => {
+                if (result === "unknown" && this.machineInputCapabilityProbes.get(facade.type) === probe) {
+                    this.machineInputCapabilityProbes.delete(facade.type);
+                }
+            });
         }
         return { machineInput: await probe, machineMenuScreen: "unknown" };
     }
@@ -399,9 +458,37 @@ export class C64Client {
             };
         }
     }
+    /**
+     * Assemble, load, and execute a pure machine-code program. Loading a PRG
+     * with LOAD+RUN (the generic path used by {@link runPrg}) is only correct
+     * for tokenized BASIC text: RUN misinterprets raw 6510 opcodes as BASIC
+     * tokens, and setting BASIC's TXTTAB/VARTAB/ARYTAB/STREND to the code
+     * range corrupts the workspace. Instead this loads the assembled bytes
+     * without running them, then types `SYS <entry>` to transfer control
+     * directly to the first assembled instruction, whatever its address.
+     */
     async uploadAndRunAsm(program) {
-        const prg = assemblyToPrg(program);
-        return this.runPrg(prg);
+        try {
+            const prg = assemblyToPrg(program);
+            if (prg.length < 2) {
+                return { success: false, details: { message: "Assembled program produced no output" } };
+            }
+            const entryAddress = prg.readUInt16LE(0);
+            const facade = await this.facadePromise;
+            const loadResult = await facade.loadPrg(prg);
+            if (!loadResult.success) {
+                return { success: false, details: loadResult.details };
+            }
+            const sysCommand = Buffer.from(`SYS${entryAddress}\r`, "ascii");
+            const injectResult = await this.injectKeyboardQueue(sysCommand, { pinnedFacade: facade });
+            return {
+                success: true,
+                details: { load: loadResult.details, entryAddress, delivered: injectResult.delivered },
+            };
+        }
+        catch (error) {
+            return { success: false, details: this.normaliseError(error) };
+        }
     }
     async runPrg(prg) {
         try {
@@ -517,13 +604,13 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async readMemory(addressInput, lengthInput) {
+    async readMemory(addressInput, lengthInput, pinnedFacade) {
         try {
             const resolved = resolveAddressSymbol(addressInput);
             const address = resolved ?? this.parseNumeric(addressInput);
             const length = this.parseNumeric(lengthInput);
             validateMemoryRange(address, length);
-            const rawBytes = await this.readMemoryRaw(address, length);
+            const rawBytes = await this.readMemoryRaw(address, length, pinnedFacade);
             const bytes = rawBytes.slice(0, length);
             return {
                 success: true,
@@ -541,7 +628,7 @@ export class C64Client {
             };
         }
     }
-    async writeMemory(addressInput, bytesInput) {
+    async writeMemory(addressInput, bytesInput, pinnedFacade) {
         try {
             const resolved = resolveAddressSymbol(addressInput);
             const address = resolved ?? this.parseNumeric(addressInput);
@@ -550,7 +637,7 @@ export class C64Client {
             // Prefer PUT with hex data for up to 128 bytes; fall back to POST binary for larger writes
             const addrStr = this.formatAddress(address);
             try {
-                const facade = await this.facadePromise;
+                const facade = pinnedFacade ?? await this.facadePromise;
                 await facade.writeMemory(address, dataBuffer);
                 return {
                     success: true,
@@ -594,10 +681,10 @@ export class C64Client {
         }
     }
     // --- SID/Music helpers ---
-    async sidSetVolume(volume) {
+    async sidSetVolume(volume, pinnedFacade) {
         const clamped = Math.max(0, Math.min(15, Math.floor(volume)));
         const byte = Buffer.from([clamped]);
-        return this.writeMemory("$D418", this.bytesToHex(byte));
+        return this.writeMemory("$D418", this.bytesToHex(byte), pinnedFacade);
     }
     async sidReset(hard = false) {
         try {
@@ -620,7 +707,7 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async sidNoteOn(options) {
+    async sidNoteOn(options, pinnedFacade) {
         const voice = options.voice ?? 1;
         if (voice < 1 || voice > 3) {
             return { success: false, details: { message: "Voice must be 1..3" } };
@@ -653,7 +740,7 @@ export class C64Client {
         const base = 0xd400 + (voice - 1) * 7;
         const bytes = Buffer.from([freqLo, freqHi, pwLo, pwHi, ctrl, ad, sr]);
         try {
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             await facade.writeMemory(base, bytes);
             return { success: true };
         }
@@ -661,13 +748,13 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async sidNoteOff(voice) {
+    async sidNoteOff(voice, pinnedFacade) {
         if (voice < 1 || voice > 3) {
             return { success: false, details: { message: "Voice must be 1..3" } };
         }
         const ctrlAddr = 0xd400 + (voice - 1) * 7 + 4;
         try {
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             await facade.writeMemory(ctrlAddr, Buffer.from([0x00]));
             return { success: true };
         }
@@ -687,26 +774,26 @@ export class C64Client {
         const facade = await this.facadePromise;
         return facade.info();
     }
-    async pause() {
+    async pause(pinnedFacade) {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
+            if (!pinnedFacade && await this.shouldUseC64uMockBypass()) {
                 const res = await this.api.v1.machinePauseUpdate(":pause");
                 return { success: true, details: res.data };
             }
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.pause();
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async resume() {
+    async resume(pinnedFacade) {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
+            if (!pinnedFacade && await this.shouldUseC64uMockBypass()) {
                 const res = await this.api.v1.machineResumeUpdate(":resume");
                 return { success: true, details: res.data };
             }
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.resume();
         }
         catch (error) {
@@ -728,8 +815,12 @@ export class C64Client {
      * VICE is restarted when it is managed by c64bridge.
      */
     async powerCycle() {
+        let menuOpened = false;
+        let cleanup;
+        let pinnedFacade;
         try {
             const facade = await this.facadePromise;
+            pinnedFacade = facade;
             if (facade.type === "u2") {
                 const result = await facade.reboot();
                 return { ...result, details: { strategy: "reboot", result: result.details } };
@@ -753,6 +844,7 @@ export class C64Client {
             if (!menuResult.success) {
                 throw new Error("Unable to open the Ultimate menu for power cycling");
             }
+            menuOpened = true;
             const initial = await this.readVerifiedMenuScreen(facade, "open Ultimate menu");
             await this.requirePowerCycleInput(facade, ["f1"]);
             await this.readVerifiedMenuScreen(facade, "open Tool Menu", "TOOL MENU", initial);
@@ -762,10 +854,21 @@ export class C64Client {
                 await this.requirePowerCycleInput(facade, ["cursor_up_down"]);
                 current = await this.readVerifiedMenuScreen(facade, `move to Power Cycle (${index + 1}/4)`, "POWER CYCLE", current);
             }
+            if (!selectedMenuRowIncludes(current, "POWER CYCLE")) {
+                throw new Error("Unable to verify that POWER CYCLE is the selected Tool Menu item; final RETURN was not sent.");
+            }
             await this.requirePowerCycleInput(facade, ["return"]);
             return { success: true, details: { strategy: "tool_menu", verifiedMenu: "Tool Menu", selectedItem: "Power Cycle" } };
         }
         catch (error) {
+            if (menuOpened) {
+                try {
+                    cleanup = await pinnedFacade?.menuButton() ?? { success: false, details: "No facade available for menu cleanup" };
+                }
+                catch (cleanupError) {
+                    cleanup = { success: false, details: this.normaliseError(cleanupError) };
+                }
+            }
             if (isMissingEndpoint(error)) {
                 return {
                     success: false,
@@ -776,7 +879,7 @@ export class C64Client {
                     },
                 };
             }
-            return { success: false, details: this.normaliseError(error) };
+            return { success: false, details: { error: this.normaliseError(error), cleanup: cleanup ?? { success: false, details: "menu cleanup was not attempted" } } };
         }
     }
     async requirePowerCycleInput(facade, inputs) {
@@ -1588,10 +1691,10 @@ export class C64Client {
      * raw binary bytes or JSON with a base64 payload.
      * Public to allow advanced polling and monitoring use cases.
      */
-    async readMemoryRaw(address, length) {
+    async readMemoryRaw(address, length, pinnedFacade) {
         validateMemoryRange(address, length);
         try {
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.readMemory(address, length);
         }
         catch (facadeError) {
@@ -1620,11 +1723,11 @@ export class C64Client {
      * Public so tools that need to drive cross-platform machine state (e.g.
      * keyboard-buffer injection) can avoid backend-specific paths.
      */
-    async writeMemoryRaw(address, bytes) {
+    async writeMemoryRaw(address, bytes, pinnedFacade) {
         if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
             throw new Error("Address must be within 0x0000 - 0xFFFF");
         }
-        const facade = await this.facadePromise;
+        const facade = pinnedFacade ?? await this.facadePromise;
         const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
         validateMemoryRange(address, buf.length);
         await facade.writeMemory(address, buf);
@@ -1648,32 +1751,39 @@ export class C64Client {
             ? bytes
             : Buffer.from(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes));
         if (data.length === 0) {
-            return;
+            return { delivered: 0 };
         }
         const chunkSize = Math.max(1, Math.min(10, options?.chunkSize ?? 10));
         const pollMs = Math.max(1, options?.drainPollMs ?? 8);
         const totalTimeoutMs = Math.max(50, options?.drainTimeoutMs ?? 2000);
-        const facade = await this.facadePromise;
+        const facade = options?.pinnedFacade ?? await this.facadePromise;
         const KEYD = 0x0277; // KERNAL keyboard buffer base
         const NDX = 0x00C6; // pending byte count
+        let delivered = 0;
         for (let offset = 0; offset < data.length; offset += chunkSize) {
             const slice = data.subarray(offset, Math.min(data.length, offset + chunkSize));
             // Write the bytes into the queue first so KERNAL never reads a stale
             // length+old-byte combination.
             await facade.writeMemory(KEYD, Buffer.from(slice));
             await facade.writeMemory(NDX, Buffer.from([slice.length]));
-            // Drain: wait for KERNAL to consume the queue. If the machine is paused
-            // or otherwise not running, give up after the timeout and continue —
-            // higher layers can decide whether that is a failure for their context.
+            // Drain before another write.  Overwriting a non-empty KERNAL queue loses
+            // user input, so a timeout is an explicit partial-delivery failure.
             const drainStart = Date.now();
+            let drained = false;
             while (Date.now() - drainStart < totalTimeoutMs) {
                 const ndx = await facade.readMemory(NDX, 1);
                 if ((ndx[0] ?? 0) === 0) {
+                    drained = true;
                     break;
                 }
                 await new Promise((resolve) => setTimeout(resolve, pollMs));
             }
+            delivered += slice.length;
+            if (!drained) {
+                throw new KeyboardQueueDrainTimeoutError(delivered, data.length, totalTimeoutMs);
+            }
         }
+        return { delivered };
     }
     async viceExitMonitor() {
         await this.withViceMonitor((client) => client.exitMonitor());
@@ -1685,6 +1795,9 @@ export class C64Client {
         const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
         await this.withViceMonitor((client) => client.memSet(address, buf));
     }
+    async viceJoyportSet(port, activeLowMask) {
+        await this.withViceMonitor((client) => client.joyportSet(port, activeLowMask));
+    }
     async viceMemGet(address, length) {
         const end = (address + length - 1) & 0xffff;
         return this.withViceMonitor((client) => client.memGet(address, end));
@@ -1883,7 +1996,7 @@ export class C64Client {
     }
     hzToSidFrequency(hz, system = "PAL") {
         const phi2 = system === "PAL" ? 985248 : 1022727;
-        const value = Math.round((hz * 65536) / phi2);
+        const value = Math.round((hz * 16777216) / phi2);
         // Clamp to 16-bit
         return Math.max(0, Math.min(0xffff, value));
     }
@@ -2064,7 +2177,7 @@ function buildSingleSpriteProgram(opts) {
     const source = lines.join("\n");
     return assemblyToPrg(source, { fileName: "sprite_gen.asm", loadAddress: 0x0801 });
 }
-function buildPetsciiScreenBasic(opts) {
+export function buildPetsciiScreenBasic(opts) {
     const border = toByte(opts.borderColor ?? 6); // default blue-ish
     const bg = toByte(opts.backgroundColor ?? 0); // default black
     // Clear screen, set colours, print text starting at 1,1
@@ -2073,7 +2186,7 @@ function buildPetsciiScreenBasic(opts) {
     const program = [
         `10 POKE 53280,${border}:POKE 53281,${bg}:PRINT CHR$(147)`,
         `20 PRINT "${sanitized}"`,
-        `30 GETA$:IFA$<>""THENEND:REM wait for key then end`,
+        `30 GETA$:IFA$=""THEN30:END:REM wait for key then end`,
     ].join("\n");
     return program;
 }
@@ -2099,11 +2212,11 @@ export function buildPrinterBasicProgram(opts) {
             ln += 10;
             continue;
         }
-        const chunks = chunkString(logical, 60);
+        const chunks = chunkString(logical, 45);
         for (let i = 0; i < chunks.length; i += 1) {
-            const chunk = escapeBasicQuotes(chunks[i]);
+            const chunk = basicStringExpression(chunks[i]);
             const tail = i < chunks.length - 1 ? ";" : ""; // avoid CR between chunks within the same logical line
-            lines.push(`${ln} PRINT#1,"${chunk}"${tail}`);
+            lines.push(`${ln} PRINT#1,${chunk}${tail}`);
             ln += 10;
         }
     }
@@ -2127,9 +2240,10 @@ function chunkString(input, maxLen) {
     }
     return parts;
 }
-function escapeBasicQuotes(input) {
-    // In Commodore BASIC, embed a double quote by doubling it
-    return input.replace(/"/g, '""');
+function basicStringExpression(input) {
+    // BASIC V2 has no doubled-quote escaping. Splice literal quote characters
+    // through CHR$(34), including leading/trailing/consecutive quote cases.
+    return input.split('"').map((part) => `"${part}"`).join(";CHR$(34);");
 }
 export function buildCommodoreBitmapBasicProgram(opts) {
     const repeats = Math.max(1, Math.floor(opts.repeats ?? 1));

package/dist/config.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
+import os from "node:os";
 import { fileURLToPath } from "url";
 const DEFAULT_HOST = "c64u";
 const DEFAULT_PORT = 80;
@@ -8,16 +9,16 @@ const DEFAULT_CONFIG = {
     baseUrl: buildBaseUrl(DEFAULT_HOST, DEFAULT_PORT),
     c64_port: DEFAULT_PORT,
     vicePrewarm: false,
+    backendConfig: {},
 };
-let cachedConfig = null;
 export function loadConfig() {
-    if (cachedConfig) {
-        return cachedConfig;
-    }
     const configPath = process.env.C64BRIDGE_CONFIG;
-    const repoConfigPath = join(dirname(fileURLToPath(import.meta.url)), "..", ".c64bridge.json");
-    const homeConfigPath = process.env.HOME ? `${process.env.HOME}/.c64bridge.json` : null;
-    const candidatePaths = [configPath, repoConfigPath, homeConfigPath];
+    const cwdConfigPath = join(process.cwd(), ".c64bridge.json");
+    const homeConfigPath = join(os.homedir(), ".c64bridge.json");
+    // Legacy package-adjacent config is deliberately last: it is useful for
+    // source checkouts but must never override a project or user config.
+    const legacyPackageConfigPath = join(dirname(fileURLToPath(import.meta.url)), "..", ".c64bridge.json");
+    const candidatePaths = [configPath, cwdConfigPath, homeConfigPath, legacyPackageConfigPath];
     let rawConfig;
     for (const candidatePath of candidatePaths) {
         if (!candidatePath) {
@@ -29,7 +30,9 @@ export function loadConfig() {
         }
         catch (error) {
             if (error.code !== "ENOENT") {
-                throw error;
+                // Deliberately omit file contents/credentials. Configuration mistakes
+                // should not prevent the MCP server from exposing a recoverable path.
+                console.error(`[c64bridge] ignoring configuration '${candidatePath}': ${error instanceof Error ? error.message : String(error)}`);
             }
         }
     }
@@ -80,8 +83,12 @@ export function loadConfig() {
         c64_port: port,
         networkPassword: firstDefined(configuredString(useU2 ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(hardware?.networkPassword), configuredString(rawConfig?.networkPassword)),
         vicePrewarm: firstDefined(configuredBoolean(process.env.VICE_PREWARM), configuredBoolean(vice?.prewarm), configuredBoolean(rawConfig?.vicePrewarm)) ?? false,
+        backendConfig: {
+            ...(rawConfig?.c64u && typeof rawConfig.c64u === "object" && !Array.isArray(rawConfig.c64u) ? { c64u: rawConfig.c64u } : {}),
+            ...(rawConfig?.u2 && typeof rawConfig.u2 === "object" && !Array.isArray(rawConfig.u2) ? { u2: rawConfig.u2 } : {}),
+            ...(rawConfig?.vice && typeof rawConfig.vice === "object" && !Array.isArray(rawConfig.vice) ? { vice: rawConfig.vice } : {}),
+        },
     };
-    cachedConfig = config;
     return config;
 }
 function configuredString(value) {
@@ -166,5 +173,6 @@ function formatHost(host) {
     return host;
 }
 export function __resetConfigCacheForTests() {
-    cachedConfig = null;
+    // Kept as a no-op compatibility hook: config is intentionally reloaded for
+    // each construction so startup and facade creation cannot disagree.
 }