c64bridge 1.0.0 → 1.0.1

package/dist/device.js

@@ -4,13 +4,13 @@
 import axios from "axios";
 import { Buffer } from "node:buffer";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { Api } from "../generated/c64/index.js";
 import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { ViceClient } from "./vice/viceClient.js";
 import { waitForBasicReady } from "./vice/readiness.js";
 import { startViceProcess } from "./vice/process.js";
+import { loadConfig } from "./config.js";
 const DEFAULT_C64U_HOST = "c64u";
 const DEFAULT_C64U_PORT = 80;
 const DEFAULT_VICE_HOST = "127.0.0.1";
@@ -53,44 +53,12 @@ function coalesceMemoryWriteBlocks(blocks) {
     return merged;
 }
 function readConfigFile() {
-    const envPath = process.env.C64BRIDGE_CONFIG;
-    const candidates = [];
-    if (envPath)
-        candidates.push(envPath);
-    // Repo root
-    try {
-        const here = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", ".c64bridge.json");
-        candidates.push(here);
-    }
-    catch { }
-    const home = process.env.HOME || os.homedir();
-    if (home)
-        candidates.push(path.join(home, ".c64bridge.json"));
-    let foundCandidate = false;
-    const merged = {};
-    for (const p of candidates) {
-        try {
-            if (fs.existsSync(p)) {
-                foundCandidate = true;
-                const text = fs.readFileSync(p, "utf8");
-                const json = JSON.parse(text);
-                if (!merged.c64u && json?.c64u && typeof json.c64u === "object" && !Array.isArray(json.c64u)) {
-                    merged.c64u = json.c64u;
-                }
-                if (!merged.u2 && json?.u2 && typeof json.u2 === "object" && !Array.isArray(json.u2)) {
-                    merged.u2 = json.u2;
-                }
-                if (!merged.vice && json?.vice && typeof json.vice === "object" && !Array.isArray(json.vice)) {
-                    merged.vice = json.vice;
-                }
-                if ((merged.c64u || merged.u2) && merged.vice) {
-                    break;
-                }
-            }
-        }
-        catch { }
-    }
-    return foundCandidate ? merged : null;
+    const sections = loadConfig().backendConfig;
+    return Object.keys(sections).length === 0 ? null : {
+        c64u: sections.c64u,
+        u2: sections.u2,
+        vice: sections.vice,
+    };
 }
 class C64uBackend {
     constructor(config, type = "c64u") {
@@ -117,6 +85,14 @@ class C64uBackend {
         }
     }
     getBaseUrl() { return this.baseUrl; }
+    actionResult(data) {
+        const errors = data && typeof data === "object" && Array.isArray(data.errors)
+            ? data.errors.filter((error) => error !== undefined && error !== null && String(error).trim() !== "")
+            : [];
+        return errors.length > 0
+            ? { success: false, details: { response: data, errors: errors.map(String) } }
+            : { success: true, details: data };
+    }
     async ping() {
         try {
             const res = await axios.get(this.baseUrl, {
@@ -132,30 +108,35 @@ class C64uBackend {
     async runPrg(prg) {
         const payload = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
         const res = await this.api.v1.runnersRunPrgCreate(":run_prg", payload, { headers: { "Content-Type": "application/octet-stream" } });
-        return { success: true, details: res.data };
+        return this.actionResult(res.data);
+    }
+    async loadPrg(prg) {
+        const payload = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
+        const res = await this.api.v1.runnersLoadPrgCreate(":load_prg", payload, { headers: { "Content-Type": "application/octet-stream" } });
+        return this.actionResult(res.data);
     }
     async loadPrgFile(pathStr) {
         const res = await this.api.v1.runnersLoadPrgUpdate(":load_prg", { file: pathStr });
-        return { success: true, details: res.data };
+        return this.actionResult(res.data);
     }
     async runPrgFile(pathStr) {
         const res = await this.api.v1.runnersRunPrgUpdate(":run_prg", { file: pathStr });
-        return { success: true, details: res.data };
+        return this.actionResult(res.data);
     }
     async runCrtFile(pathStr) {
         const res = await this.api.v1.runnersRunCrtUpdate(":run_crt", { file: pathStr });
-        return { success: true, details: res.data };
+        return this.actionResult(res.data);
     }
     async sidplayFile(pathStr, songnr) {
         const res = await this.api.v1.runnersSidplayUpdate(":sidplay", { file: pathStr, songnr });
-        return { success: true, details: res.data };
+        return this.actionResult(res.data);
     }
     async sidplayAttachment(sid, options) {
         const form = { sid: Buffer.isBuffer(sid) ? sid : Buffer.from(sid) };
         if (options?.songlengths)
             form.songlengths = Buffer.isBuffer(options.songlengths) ? options.songlengths : Buffer.from(options.songlengths);
         const res = await this.api.v1.runnersSidplayCreate(":sidplay", form, options?.songnr !== undefined ? { songnr: options.songnr } : undefined);
-        return { success: true, details: res.data };
+        return this.actionResult(res.data);
     }
     async readMemory(address, length) {
         const addrStr = address.toString(16).toUpperCase().padStart(4, "0");
@@ -189,13 +170,13 @@ class C64uBackend {
         const mergedBlocks = coalesceMemoryWriteBlocks(blocks);
         await Promise.all(mergedBlocks.map(({ address, bytes }) => this.writeMemory(address, bytes)));
     }
-    async reset() { const res = await this.api.v1.machineResetUpdate(":reset"); return { success: true, details: res.data }; }
-    async reboot() { const res = await this.api.v1.machineRebootUpdate(":reboot"); return { success: true, details: res.data }; }
-    async pause() { const res = await this.api.v1.machinePauseUpdate(":pause"); return { success: true, details: res.data }; }
-    async resume() { const res = await this.api.v1.machineResumeUpdate(":resume"); return { success: true, details: res.data }; }
-    async poweroff() { this.requireC64u("poweroff"); const res = await this.api.v1.machinePoweroffUpdate(":poweroff"); return { success: true, details: res.data }; }
+    async reset() { const res = await this.api.v1.machineResetUpdate(":reset"); return this.actionResult(res.data); }
+    async reboot() { const res = await this.api.v1.machineRebootUpdate(":reboot"); return this.actionResult(res.data); }
+    async pause() { const res = await this.api.v1.machinePauseUpdate(":pause"); return this.actionResult(res.data); }
+    async resume() { const res = await this.api.v1.machineResumeUpdate(":resume"); return this.actionResult(res.data); }
+    async poweroff() { this.requireC64u("poweroff"); const res = await this.api.v1.machinePoweroffUpdate(":poweroff"); return this.actionResult(res.data); }
     async powerCycle() { this.requireC64u("powerCycle"); throw unsupported("powerCycle must be coordinated by C64Client"); }
-    async menuButton() { const res = await this.api.v1.machineMenuButtonUpdate(":menu_button"); return { success: true, details: res.data }; }
+    async menuButton() { const res = await this.api.v1.machineMenuButtonUpdate(":menu_button"); return this.actionResult(res.data); }
     async readMenuScreen() {
         const response = await this.api.v1.machineMenuScreenList(":menu_screen", { format: "arraybuffer", headers: { Accept: "application/octet-stream" } });
         const body = response.data;
@@ -215,29 +196,42 @@ class C64uBackend {
     async debugregWrite(value) { this.requireC64u("debugregWrite"); const res = await this.api.v1.machineDebugregUpdate(":debugreg", { value }); return { success: true, value: res.data.value, details: res.data }; }
     async version() { const res = await this.api.v1.versionList(); return res.data; }
     async info() { const res = await this.api.v1.infoList(); return res.data; }
-    async drivesList() { const res = await this.api.v1.drivesList(); return res.data; }
-    async driveMount(d, img, options) { const res = await this.api.v1.drivesMountUpdate(d, ":mount", { image: img, type: options?.type, mode: options?.mode }); return { success: true, details: res.data }; }
-    async driveRemove(d) { const res = await this.api.v1.drivesRemoveUpdate(d, ":remove"); return { success: true, details: res.data }; }
-    async driveReset(d) { const res = await this.api.v1.drivesResetUpdate(d, ":reset"); return { success: true, details: res.data }; }
-    async driveOn(d) { const res = await this.api.v1.drivesOnUpdate(d, ":on"); return { success: true, details: res.data }; }
-    async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(d, ":off"); return { success: true, details: res.data }; }
-    async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(d, ":set_mode", { mode }); return { success: true, details: res.data }; }
-    async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(d, ":load_rom", { file: romPath }); return { success: true, details: res.data }; }
-    async streamStart(s, ip) { this.requireC64u("streamStart"); const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return { success: true, details: res.data }; }
-    async streamStop(s) { this.requireC64u("streamStop"); const res = await this.api.v1.streamsStopUpdate(s, ":stop"); return { success: true, details: res.data }; }
+    async drivesList() {
+        const res = await this.api.v1.drivesList();
+        const raw = res.data;
+        const entries = Array.isArray(raw.drives)
+            ? raw.drives
+            : raw.drives && typeof raw.drives === "object" ? [raw.drives] : [];
+        return entries.flatMap((entry) => Object.entries(entry).map(([id, info]) => ({
+            id,
+            power: info.enabled === true || info.enabled === "on" || info.power === "on" ? "on" : "off",
+            image: (info.image_path ?? info.image_file ?? info.image ?? null),
+            type: info.type ?? null,
+            raw: info,
+        })));
+    }
+    async driveMount(d, img, options) { const res = await this.api.v1.drivesMountUpdate(d, ":mount", { image: img, type: options?.type, mode: options?.mode }); return this.actionResult(res.data); }
+    async driveRemove(d) { const res = await this.api.v1.drivesRemoveUpdate(d, ":remove"); return this.actionResult(res.data); }
+    async driveReset(d) { const res = await this.api.v1.drivesResetUpdate(d, ":reset"); return this.actionResult(res.data); }
+    async driveOn(d) { const res = await this.api.v1.drivesOnUpdate(d, ":on"); return this.actionResult(res.data); }
+    async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(d, ":off"); return this.actionResult(res.data); }
+    async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(d, ":set_mode", { mode }); return this.actionResult(res.data); }
+    async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(d, ":load_rom", { file: romPath }); return this.actionResult(res.data); }
+    async streamStart(s, ip) { this.requireC64u("streamStart"); const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return this.actionResult(res.data); }
+    async streamStop(s) { this.requireC64u("streamStop"); const res = await this.api.v1.streamsStopUpdate(s, ":stop"); return this.actionResult(res.data); }
     async configsList() { const res = await this.api.v1.configsList(); return res.data; }
     async configGet(cat, item) { const res = item ? await this.api.v1.configsDetail2(cat, item) : await this.api.v1.configsDetail(cat); return res.data; }
-    async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(cat, item, { value }); return { success: true, details: res.data }; }
-    async configBatchUpdate(payload) { const res = await this.api.v1.configsCreate(payload); return { success: true, details: res.data }; }
-    async configLoadFromFlash() { const res = await this.api.v1.configsLoadFromFlashUpdate(":load_from_flash"); return { success: true, details: res.data }; }
-    async configSaveToFlash() { const res = await this.api.v1.configsSaveToFlashUpdate(":save_to_flash"); return { success: true, details: res.data }; }
-    async configResetToDefault() { const res = await this.api.v1.configsResetToDefaultUpdate(":reset_to_default"); return { success: true, details: res.data }; }
-    async filesInfo(p) { const res = await this.api.v1.filesInfoDetail(encodeURIComponent(p), ":info"); return res.data; }
-    async filesCreateD64(p, options) { const res = await this.api.v1.filesCreateD64Update(encodeURIComponent(p), ":create_d64", { tracks: options?.tracks, diskname: options?.diskname }); return { success: true, details: res.data }; }
-    async filesCreateD71(p, options) { const res = await this.api.v1.filesCreateD71Update(encodeURIComponent(p), ":create_d71", { diskname: options?.diskname }); return { success: true, details: res.data }; }
-    async filesCreateD81(p, options) { const res = await this.api.v1.filesCreateD81Update(encodeURIComponent(p), ":create_d81", { diskname: options?.diskname }); return { success: true, details: res.data }; }
-    async filesCreateDnp(p, tracks, options) { const res = await this.api.v1.filesCreateDnpUpdate(encodeURIComponent(p), ":create_dnp", { tracks, diskname: options?.diskname }); return { success: true, details: res.data }; }
-    async modplayFile(pathStr) { const res = await this.api.v1.runnersModplayUpdate(":modplay", { file: pathStr }); return { success: true, details: res.data }; }
+    async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(cat, item, { value }); return this.actionResult(res.data); }
+    async configBatchUpdate(payload) { const res = await this.api.v1.configsCreate(payload); return this.actionResult(res.data); }
+    async configLoadFromFlash() { const res = await this.api.v1.configsLoadFromFlashUpdate(":load_from_flash"); return this.actionResult(res.data); }
+    async configSaveToFlash() { const res = await this.api.v1.configsSaveToFlashUpdate(":save_to_flash"); return this.actionResult(res.data); }
+    async configResetToDefault() { const res = await this.api.v1.configsResetToDefaultUpdate(":reset_to_default"); return this.actionResult(res.data); }
+    async filesInfo(p) { const res = await this.api.v1.filesInfoDetail(encodeDevicePath(p), ":info"); return res.data; }
+    async filesCreateD64(p, options) { const res = await this.api.v1.filesCreateD64Update(encodeDevicePath(p), ":create_d64", { tracks: options?.tracks, diskname: options?.diskname }); return this.actionResult(res.data); }
+    async filesCreateD71(p, options) { const res = await this.api.v1.filesCreateD71Update(encodeDevicePath(p), ":create_d71", { diskname: options?.diskname }); return this.actionResult(res.data); }
+    async filesCreateD81(p, options) { const res = await this.api.v1.filesCreateD81Update(encodeDevicePath(p), ":create_d81", { diskname: options?.diskname }); return this.actionResult(res.data); }
+    async filesCreateDnp(p, tracks, options) { const res = await this.api.v1.filesCreateDnpUpdate(encodeDevicePath(p), ":create_dnp", { tracks, diskname: options?.diskname }); return this.actionResult(res.data); }
+    async modplayFile(pathStr) { const res = await this.api.v1.runnersModplayUpdate(":modplay", { file: pathStr }); return this.actionResult(res.data); }
 }
 export class ViceBackend {
     constructor(config) {
@@ -402,13 +396,19 @@ export class ViceBackend {
             return;
         }
         ViceBackend.cleanupRegistered = true;
-        /* c8 ignore next 5 -- global process exit hooks are not practical to exercise in the unit test process */
-        process.once("exit", () => {
+        const cleanupSync = () => {
             for (const [, handle] of ViceBackend.supervisors) {
-                handle.stop().catch(() => { });
+                handle.stopSync();
             }
             ViceBackend.supervisors.clear();
-        });
+        };
+        process.once("exit", cleanupSync);
+        for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+            process.once(signal, () => {
+                cleanupSync();
+                process.exit(signal === "SIGINT" ? 130 : 143);
+            });
+        }
     }
     async withClient(fn, options) {
         const previous = this.monitorQueue;
@@ -472,7 +472,15 @@ export class ViceBackend {
         }
         return false;
     }
-    async injectPrg(buffer) {
+    /**
+     * Reset, wait for a usable BASIC prompt, and load PRG bytes into memory.
+     * `finish` decides what happens next: a genuine BASIC PRG needs its
+     * pointers set and RUN typed, but machine code must never receive either
+     * — RUN would misinterpret raw opcodes as tokenized BASIC text, and
+     * rewriting TXTTAB/VARTAB/ARYTAB/STREND corrupts the BASIC workspace for
+     * an origin that isn't BASIC program text at all.
+     */
+    async loadPrgAndFinish(buffer, finish) {
         if (buffer.length < 2)
             throw new Error("PRG data too short");
         const loadAddress = buffer.readUInt16LE(0);
@@ -482,7 +490,12 @@ export class ViceBackend {
             await waitForBasicReady(client, { timeoutMs: 10000, ensurePrompt: true });
             if (body.length > 0)
                 await client.memSet(loadAddress, body);
-            const programEnd = loadAddress + body.length;
+            await finish(client, loadAddress, loadAddress + body.length);
+            await client.exitMonitor();
+        });
+    }
+    async injectPrg(buffer) {
+        await this.loadPrgAndFinish(buffer, async (client, loadAddress, programEnd) => {
             const ptrs = Buffer.alloc(8);
             ptrs.writeUInt16LE(loadAddress, 0);
             ptrs.writeUInt16LE(programEnd, 2);
@@ -490,7 +503,6 @@ export class ViceBackend {
             ptrs.writeUInt16LE(programEnd, 6);
             await client.memSet(0x002B, ptrs);
             await client.keyboardFeed("RUN\r");
-            await client.exitMonitor();
         });
     }
     async runPrg(prg) {
@@ -498,6 +510,13 @@ export class ViceBackend {
         await this.injectPrg(buffer);
         return { success: true };
     }
+    /** Load PRG bytes without starting them — the caller decides how to enter
+     * the code (e.g. a subsequent typed `SYS <entry>` for machine code). */
+    async loadPrg(prg) {
+        const buffer = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
+        await this.loadPrgAndFinish(buffer, async () => { });
+        return { success: true };
+    }
     async loadPrgFile(_path) { throw unsupported("loadPrgFile"); }
     async runPrgFile(prgPath) {
         const data = fs.readFileSync(prgPath);
@@ -540,22 +559,29 @@ export class ViceBackend {
         });
     }
     async reset() {
+        let readiness;
+        // Overridable only for deterministic tests of the readiness-failure path;
+        // production always uses the 20s default.
+        const resetReadinessTimeoutMs = Number(process.env.C64BRIDGE_VICE_RESET_TIMEOUT_MS) || 20000;
         await this.withClient(async (client) => {
             await client.reset();
             const opts = this.debugEnabled
                 ? {
-                    timeoutMs: 20000,
+                    timeoutMs: resetReadinessTimeoutMs,
                     ensurePrompt: true,
                     onPointersSample: (p) => {
                         console.error("[vice-backend] BASIC pointers", p);
                     },
                 }
-                : { timeoutMs: 20000, ensurePrompt: true };
-            const readiness = await waitForBasicReady(client, opts);
+                : { timeoutMs: resetReadinessTimeoutMs, ensurePrompt: true };
+            readiness = await waitForBasicReady(client, opts);
             if (this.debugEnabled)
                 console.error("[vice-backend] waitForBasicReady result", readiness);
         });
-        return { success: true };
+        const ready = Boolean(readiness?.pointersOk && readiness?.promptOk);
+        return ready
+            ? { success: true, details: readiness }
+            : { success: false, details: { readiness, message: "VICE reset completed but BASIC READY was not observed. Reset again or inspect the emulator monitor." } };
     }
     async reboot() { return this.reset(); }
     async pause() {
@@ -742,9 +768,12 @@ export class ViceBackend {
         });
     }
     async configSet(_category, item, value) {
-        const numValue = Number(value);
-        const parsed = !isNaN(numValue) && value.trim() !== "" ? numValue : value;
+        let parsed = value;
         await this.withClient(async (client) => {
+            const current = await client.resourceGet(item);
+            parsed = current.type === "int" ? Number(value) : value;
+            if (current.type === "int" && !Number.isFinite(parsed))
+                throw new Error(`VICE resource '${item}' requires an integer value`);
             await client.resourceSet(item, parsed);
         });
         return { success: true, details: { item, value: parsed } };
@@ -756,8 +785,10 @@ export class ViceBackend {
                 for (const [item, value] of Object.entries(items)) {
                     try {
                         const str = String(value ?? "");
-                        const numValue = Number(str);
-                        const parsed = !isNaN(numValue) && str.trim() !== "" ? numValue : str;
+                        const current = await client.resourceGet(item);
+                        const parsed = current.type === "int" ? Number(str) : str;
+                        if (current.type === "int" && !Number.isFinite(parsed))
+                            throw new Error(`VICE resource '${item}' requires an integer value`);
                         await client.resourceSet(item, parsed);
                         results.push({ item: `${category}/${item}`, success: true });
                     }
@@ -784,6 +815,11 @@ export class ViceBackend {
 ViceBackend.supervisors = new Map();
 ViceBackend.cleanupRegistered = false;
 function unsupported(name) { const err = new Error(`Operation '${name}' is not supported by the VICE backend in phase one`); err.code = "UNSUPPORTED"; return err; }
+/** Ultimate file APIs treat slash as a path separator. Encode each name once,
+ * preserving leading and nested separators for firmware routing. */
+function encodeDevicePath(value) {
+    return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
 function parseDriveNumber(drive) {
     const match = /\d+/.exec(drive);
     const n = match ? parseInt(match[0], 10) : NaN;

package/dist/knowledge.js

@@ -82,7 +82,7 @@ Key SID Registers (decimal addresses):
 **PAL vs NTSC Clock Differences:**
 - PAL: 985,248 Hz SID clock
 - NTSC: 1,022,727 Hz SID clock
-- Formula: freq_value = (frequency_Hz × 65536) / clock_rate
+- Formula: freq_value = round((frequency_Hz × 16777216) / clock_rate) (SID has a 24-bit phase accumulator)
 
 **Complete SID Frequency Lookup Table (All Notes, Multiple Octaves):**
 

package/dist/loggingHttpClient.js

@@ -1,5 +1,17 @@
 import { HttpClient } from "../generated/c64/index.js";
 import { formatErrorMessage, formatPayloadForDebug, loggerFor, payloadByteLength } from "./logger.js";
+/** Headers are useful in diagnostics, but credentials must never leave the
+ * transport layer.  Axios normalises some keys and preserves others, so do a
+ * case-insensitive pass instead of relying on one spelling. */
+function redactHeaders(headers) {
+    if (!headers)
+        return headers;
+    const sensitive = /^(x-password|authorization|proxy-authorization|cookie|set-cookie|x-api-key)$/i;
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+        key,
+        sensitive.test(key) ? "***" : value,
+    ]));
+}
 export function createLoggingHttpClient(config, logger = loggerFor("c64u")) {
     const http = new HttpClient(config);
     http.instance.interceptors.request.use((request) => {
@@ -9,7 +21,7 @@ export function createLoggingHttpClient(config, logger = loggerFor("c64u")) {
             startedAt: Date.now(),
             method,
             path,
-            headers: request.headers ? { ...request.headers } : undefined,
+            headers: redactHeaders(request.headers),
             params: request.params ? { ...request.params } : undefined,
             body: request.data,
         };
@@ -40,7 +52,7 @@ function handleResponse(response, logger) {
         });
         logger.debug(`response ${method} ${path}`, {
             status: response.status,
-            headers: response.headers ?? {},
+            headers: redactHeaders(response.headers),
             body: formatPayloadForDebug(response.data),
         });
     }
@@ -68,7 +80,7 @@ function handleError(error, logger) {
         });
         logger.debug(`error ${method} ${path}`, {
             status,
-            headers: response?.headers ?? {},
+            headers: redactHeaders(response?.headers),
             body: response ? formatPayloadForDebug(response.data) : null,
             message,
         });

package/dist/mcp-server.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import "./bootstrap/stdio-logger.js";
+import { createServer } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig } from "./config.js";
 import { C64Client } from "./c64Client.js";
@@ -32,7 +34,7 @@ function createPromptRegistryGetter() {
         return registry;
     };
 }
-function parseCliOptions(argv) {
+export function parseCliOptions(argv) {
     const httpIndex = argv.indexOf("--http");
     if (httpIndex === -1) {
         return { mode: "stdio" };
@@ -420,12 +422,34 @@ async function main() {
             throw error;
         }
     });
-    // Connect via stdio
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    writeDiagnosticEvent("mcp_transport_connected", { mode: "stdio" });
+    const cli = parseCliOptions(process.argv.slice(2));
+    if (cli.mode === "http") {
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        await server.connect(transport);
+        const port = cli.port ?? 3000;
+        const httpServer = createServer((request, response) => {
+            if (request.url?.split("?")[0] !== "/mcp") {
+                response.statusCode = 404;
+                response.end("Not found");
+                return;
+            }
+            void transport.handleRequest(request, response).catch((error) => {
+                if (!response.headersSent)
+                    response.statusCode = 500;
+                response.end(error instanceof Error ? error.message : "MCP transport error");
+            });
+        });
+        await new Promise((resolve, reject) => httpServer.listen(port, "127.0.0.1", resolve).once("error", reject));
+        writeDiagnosticEvent("mcp_transport_connected", { mode: "http", port });
+        console.error(`c64bridge MCP server running on HTTP at http://127.0.0.1:${port}/mcp`);
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        writeDiagnosticEvent("mcp_transport_connected", { mode: "stdio" });
+        console.error("c64bridge MCP server running on stdio");
+    }
     await logConnectivity(client, baseUrl);
-    console.error("c64bridge MCP server running on stdio");
     writeDiagnosticEvent("server_ready", {
         diagnosticsFile: diagnostics.filePath,
     });
@@ -447,11 +471,18 @@ function createPlatformResourceDescriptor() {
         },
     };
 }
-async function renderPlatformStatusMarkdown(client) {
+export async function renderPlatformStatusMarkdown(client) {
     const status = getPlatformStatus();
     const availableBackends = client.getAvailableBackends();
     const capabilities = describePlatformCapabilities(toolRegistry.list());
-    const nativeEndpoints = await client.getNativeEndpointCapabilities();
+    // Resource reads must remain responsive while an Ultimate boots or is
+    // unreachable. The probe itself remains retryable (unknown is not cached).
+    const nativeEndpoints = await Promise.race([
+        client.getNativeEndpointCapabilities(),
+        new Promise((resolve) => {
+            setTimeout(() => resolve({ machineInput: "unknown", machineMenuScreen: "unknown" }), 750).unref();
+        }),
+    ]);
     const lines = [
         "# MCP Platform Status",
         "",
@@ -590,11 +621,21 @@ function toPromptMessage(segment) {
         },
     };
 }
-main().catch((error) => {
-    writeDiagnosticEvent("server_fatal", {
-        diagnosticsFile: getDiagnosticsSessionInfo()?.filePath,
-        error,
+// The documented entrypoint (src/index.ts / dist/index.js, per package.json
+// "main"/"bin") always imports this module as a side effect rather than
+// invoking it as the process's own script, so process.argv[1] never points
+// here — an entrypoint-identity check would wrongly skip startup in every
+// real deployment. Test code that only needs a pure export (e.g.
+// parseCliOptions, renderPlatformStatusMarkdown) sets this opt-out instead,
+// mirroring the existing C64BRIDGE_START_SKIP_AUTO_LAUNCH convention in
+// scripts/start.mjs.
+if (process.env.C64BRIDGE_SKIP_AUTO_START !== "1") {
+    main().catch((error) => {
+        writeDiagnosticEvent("server_fatal", {
+            diagnosticsFile: getDiagnosticsSessionInfo()?.filePath,
+            error,
+        });
+        console.error("Fatal error in MCP server:", error);
+        process.exit(1);
     });
-    console.error("Fatal error in MCP server:", error);
-    process.exit(1);
-});
+}

package/dist/rag/indexer.js

@@ -4,16 +4,19 @@ GPL-2.0-only
 */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import fsSync from "node:fs";
-const BASIC_DIR = path.resolve("data/basic/examples");
-const ASM_DIR = path.resolve("data/assembly/examples");
-const EXTERNAL_DIR = path.resolve("external");
-const DOC_ROOT = path.resolve("doc");
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ASSET_ROOT = process.env.C64BRIDGE_ASSET_ROOT ? path.resolve(process.env.C64BRIDGE_ASSET_ROOT) : PACKAGE_ROOT;
+const BASIC_DIR = path.join(ASSET_ROOT, "data/basic/examples");
+const ASM_DIR = path.join(ASSET_ROOT, "data/assembly/examples");
+const EXTERNAL_DIR = path.join(ASSET_ROOT, "external");
+const DOC_ROOT = path.join(ASSET_ROOT, "doc");
 const DOC_EXCLUDE_DIRS = new Set(["plans"]);
-const CONTEXT_DIR = path.resolve("data/context");
+const CONTEXT_DIR = path.join(ASSET_ROOT, "data/context");
 const BOOTSTRAP_PATH = path.join(CONTEXT_DIR, "bootstrap.md");
-const AGENTS_PATH = path.resolve("AGENTS.md");
-const PROMPTS_DIR = path.resolve(".github/prompts");
+const AGENTS_PATH = path.join(ASSET_ROOT, "AGENTS.md");
+const PROMPTS_DIR = path.join(ASSET_ROOT, ".github/prompts");
 const CHAT_PATH = path.join(CONTEXT_DIR, "chat.md");
 // RAG_DOC_FILES env var can add extra specific files, comma-separated
 const ENV_DOC_FILES = (process.env.RAG_DOC_FILES ?? "")
@@ -34,7 +37,7 @@ function shouldExcludeDocFile(file) {
     return firstSegment !== undefined && DOC_EXCLUDE_DIRS.has(firstSegment);
 }
 function resolveEmbeddingsDir(override) {
-    return path.resolve(override ?? process.env.RAG_EMBEDDINGS_DIR ?? "data");
+    return path.resolve(override ?? process.env.RAG_EMBEDDINGS_DIR ?? path.join(ASSET_ROOT, "data"));
 }
 function embeddingIndexPaths(dir) {
     return {

package/dist/rag/init.js

@@ -4,22 +4,25 @@ GPL-2.0-only
 */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
 import { LocalMiniHashEmbedding } from "./embeddings.js";
 import { buildAllIndexes, loadIndexes } from "./indexer.js";
 import { LocalRagRetriever } from "./retriever.js";
 import { LoggingRagRetriever } from "./loggingRetriever.js";
-const EXTERNAL_DIR = path.resolve("external");
-const BASIC_DATA_DIR = path.resolve("data/basic/examples");
-const ASM_DATA_DIR = path.resolve("data/assembly/examples");
-const DOC_DIR = path.resolve("doc");
-const CONTEXT_DIR = path.resolve("data/context");
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const assetRoot = process.env.C64BRIDGE_ASSET_ROOT ? path.resolve(process.env.C64BRIDGE_ASSET_ROOT) : PACKAGE_ROOT;
+const EXTERNAL_DIR = path.join(assetRoot, "external");
+const BASIC_DATA_DIR = path.join(assetRoot, "data/basic/examples");
+const ASM_DATA_DIR = path.join(assetRoot, "data/assembly/examples");
+const DOC_DIR = path.join(assetRoot, "doc");
+const CONTEXT_DIR = path.join(assetRoot, "data/context");
 const BOOTSTRAP_PATH = path.join(CONTEXT_DIR, "bootstrap.md");
-const AGENTS_PATH = path.resolve("AGENTS.md");
-const PROMPTS_DIR = path.resolve(".github/prompts");
+const AGENTS_PATH = path.join(assetRoot, "AGENTS.md");
+const PROMPTS_DIR = path.join(assetRoot, ".github/prompts");
 const CHAT_PATH = path.join(CONTEXT_DIR, "chat.md");
 function resolveEmbeddingsDir() {
-    return path.resolve(process.env.RAG_EMBEDDINGS_DIR ?? "data");
+    return path.resolve(process.env.RAG_EMBEDDINGS_DIR ?? path.join(assetRoot, "data"));
 }
 function embeddingIndexPaths() {
     const dir = resolveEmbeddingsDir();

package/dist/sidwaveCompiler.js

@@ -169,9 +169,9 @@ export function compileSidwaveToSid(doc, prg, options) {
     const body = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
     return { sid: Buffer.concat([header, body]) };
 }
-function hzToSidFrequency(hz, system) {
+export function hzToSidFrequency(hz, system) {
     const phi2 = system === "PAL" ? 985248 : 1022727;
-    const value = Math.round((hz * 65536) / phi2);
+    const value = Math.round((hz * 16777216) / phi2);
     return Math.max(0, Math.min(0xffff, value));
 }
 function waveformToCtrl(w) {