c64bridge 0.9.3 → 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,54 +53,25 @@ 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.vice && json?.vice && typeof json.vice === "object" && !Array.isArray(json.vice)) {
-                    merged.vice = json.vice;
-                }
-                if (merged.c64u && 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) {
-        this.type = "c64u";
-        const envHost = configuredString(process.env.C64U_HOST);
-        const envPort = configuredPort(process.env.C64U_PORT);
+    constructor(config, type = "c64u") {
+        this.type = type;
+        const envHost = configuredString(type === "u2" ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST);
+        const envPort = configuredPort(type === "u2" ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT);
         const configBaseUrl = normaliseBaseUrl(config.baseUrl);
         const parsedConfigBaseUrl = configBaseUrl ? parseEndpoint(configBaseUrl) : {};
         const baseUrl = envHost !== undefined || envPort !== undefined
             ? buildBaseUrl(firstDefined(envHost, configuredString(config.host), configuredString(config.hostname), parsedConfigBaseUrl.hostname) ?? DEFAULT_C64U_HOST, firstDefined(envPort, configuredPort(config.port), parsedConfigBaseUrl.port) ?? DEFAULT_C64U_PORT)
             : resolveBaseUrl(config);
         this.baseUrl = baseUrl;
-        this.networkPassword = firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(config.networkPassword));
+        this.networkPassword = firstDefined(configuredString(type === "u2" ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(config.networkPassword));
         const http = createLoggingHttpClient({
             baseURL: baseUrl,
             timeout: 10000,
@@ -108,7 +79,20 @@ class C64uBackend {
         });
         this.api = new Api(http);
     }
+    requireC64u(feature) {
+        if (this.type === "u2") {
+            throw unsupported(`${feature} is unavailable on U2-family cartridges`);
+        }
+    }
     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, {
@@ -124,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");
@@ -181,39 +170,68 @@ 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() { const res = await this.api.v1.machinePoweroffUpdate(":poweroff"); return { success: true, details: res.data }; }
-    async menuButton() { const res = await this.api.v1.machineMenuButtonUpdate(":menu_button"); return { success: true, details: res.data }; }
-    async debugregRead() { const res = await this.api.v1.machineDebugregList(":debugreg"); return { success: true, value: res.data.value, details: res.data }; }
-    async debugregWrite(value) { const res = await this.api.v1.machineDebugregUpdate(":debugreg", { value }); return { success: true, value: res.data.value, 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 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;
+        return body instanceof ArrayBuffer ? new Uint8Array(body) : extractBytes(body);
+    }
+    async getInputState() {
+        this.requireC64u("getInputState");
+        const response = await this.api.v1.machineInputList(":input");
+        return response.data;
+    }
+    async sendInputEvents(batch) {
+        this.requireC64u("sendInputEvents");
+        const response = await this.api.v1.machineInputCreate(":input", batch);
+        return response.data;
+    }
+    async debugregRead() { this.requireC64u("debugregRead"); const res = await this.api.v1.machineDebugregList(":debugreg"); return { success: true, value: res.data.value, details: res.data }; }
+    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) { const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return { success: true, details: res.data }; }
-    async streamStop(s) { 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) {
@@ -378,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;
@@ -448,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);
@@ -458,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);
@@ -466,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) {
@@ -474,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);
@@ -516,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() {
@@ -580,6 +630,7 @@ export class ViceBackend {
             return { success: false, details };
         }
     }
+    async powerCycle() { return this.nuclearReset(); }
     async nuclearReset() {
         const poweroffResult = await this.poweroff();
         if (!poweroffResult.success) {
@@ -606,6 +657,9 @@ export class ViceBackend {
         }
     }
     async menuButton() { throw unsupported("menuButton"); }
+    async readMenuScreen() { throw unsupported("readMenuScreen"); }
+    async getInputState() { throw unsupported("getInputState"); }
+    async sendInputEvents(_batch) { throw unsupported("sendInputEvents"); }
     async debugregRead() { throw unsupported("debugregRead"); }
     async debugregWrite(_v) { throw unsupported("debugregWrite"); }
     async version() { return { emulator: "vice", host: this.host, port: this.port }; }
@@ -714,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 } };
@@ -728,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 });
                     }
@@ -756,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;
@@ -885,46 +949,53 @@ export function __buildViceProcessOptionsForTests(input) {
     return buildManagedViceProcessOptions(input);
 }
 export async function createFacade(logger, options) {
+    const envMode = (process.env.C64_MODE || "").toLowerCase().trim();
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
     if (options?.preferredC64uBaseUrl) {
+        const type = envMode === "u2" ? "u2" : "c64u";
         const backend = new C64uBackend({
             baseUrl: options.preferredC64uBaseUrl,
             networkPassword: options.preferredC64uNetworkPassword,
-        });
-        logger?.info?.("Active backend: c64u (forced by caller)");
-        return { facade: backend, selected: "c64u", reason: "forced by caller", details: { baseUrl: options.preferredC64uBaseUrl } };
+        }, type);
+        logger?.info?.(`Active backend: ${type} (forced by caller)`);
+        return { facade: backend, selected: type, reason: "forced by caller", details: { baseUrl: options.preferredC64uBaseUrl } };
     }
     const cfg = readConfigFile();
-    const envMode = (process.env.C64_MODE || "").toLowerCase().trim();
     const hasC64u = Boolean(cfg?.c64u);
+    const hasU2 = Boolean(cfg?.u2);
     const hasVice = Boolean(cfg?.vice);
     if (envMode === "c64u") {
         const backend = new C64uBackend(cfg?.c64u ?? {});
         logger?.info?.("Active backend: c64u (from env override)");
         return { facade: backend, selected: "c64u", reason: "env override", details: { baseUrl: backend.getBaseUrl?.() } };
     }
+    if (envMode === "u2") {
+        const backend = new C64uBackend(cfg?.u2 ?? {}, "u2");
+        logger?.info?.("Active backend: u2 (from env override)");
+        return { facade: backend, selected: "u2", reason: "env override", details: { baseUrl: backend.getBaseUrl?.() } };
+    }
     if (envMode === "vice") {
         const backend = new ViceBackend(cfg?.vice ?? {});
         logger?.info?.("Active backend: vice (from env override)");
         const endpoint = backend.getEndpoint();
         return { facade: backend, selected: "vice", reason: "env override", details: { host: endpoint.host, port: endpoint.port } };
     }
-    if (hasC64u && !hasVice) {
+    if (hasC64u) {
         const backend = new C64uBackend(cfg.c64u);
         logger?.info?.("Active backend: c64u (from config)");
-        return { facade: backend, selected: "c64u", reason: "config only", details: { baseUrl: backend.getBaseUrl?.() } };
+        return { facade: backend, selected: "c64u", reason: hasVice ? "both defined (prefer c64u)" : "config only", details: { baseUrl: backend.getBaseUrl?.() } };
+    }
+    if (hasU2) {
+        const backend = new C64uBackend(cfg.u2, "u2");
+        logger?.info?.("Active backend: u2 (from config)");
+        return { facade: backend, selected: "u2", reason: "config only", details: { baseUrl: backend.getBaseUrl?.() } };
     }
-    if (!hasC64u && hasVice) {
+    if (hasVice) {
         const backend = new ViceBackend(cfg.vice);
         logger?.info?.("Active backend: vice (from config)");
         const endpoint = backend.getEndpoint();
         return { facade: backend, selected: "vice", reason: "config only", details: { host: endpoint.host, port: endpoint.port } };
     }
-    if (hasC64u && hasVice) {
-        const backend = new C64uBackend(cfg.c64u);
-        logger?.info?.("Active backend: c64u (both defined; default preference)");
-        return { facade: backend, selected: "c64u", reason: "both defined (prefer c64u)", details: { baseUrl: backend.getBaseUrl?.() } };
-    }
     // No configuration
     const probeBase = resolveBaseUrl({});
     try {
@@ -942,35 +1013,30 @@ export async function createFacade(logger, options) {
     return { facade: backend, selected: "vice", reason: "fallback (hardware unavailable)", details: { host: endpoint.host, port: endpoint.port } };
 }
 export async function createAllFacades(logger, options) {
-    const primary = await createFacade(logger);
+    // C64U/VICE preserve config-file selection semantics. U2 needs the
+    // caller-provided endpoint because it is selected through C64_MODE=u2.
+    const primary = await createFacade(logger, process.env.C64_MODE?.toLowerCase().trim() === "u2" ? options : undefined);
     const config = readConfigFile();
-    const secondaryType = primary.selected === "c64u" ? "vice" : "c64u";
-    if (secondaryType === "c64u" && shouldProvisionSecondaryC64u(config, options)) {
-        const secondaryConfig = {
+    const facades = new Map([[primary.selected, primary.facade]]);
+    if (config?.c64u && primary.selected !== "c64u") {
+        facades.set("c64u", new C64uBackend(config.c64u));
+    }
+    if (config?.u2 && primary.selected !== "u2") {
+        facades.set("u2", new C64uBackend(config.u2, "u2"));
+    }
+    if (config?.vice && primary.selected !== "vice") {
+        facades.set("vice", new ViceBackend(config.vice));
+    }
+    if (!facades.has("c64u") && !config?.u2 && shouldProvisionSecondaryC64u(config, options) && primary.selected !== "u2") {
+        facades.set("c64u", new C64uBackend({
             ...(config?.c64u ?? {}),
             ...(!config?.c64u?.baseUrl && options?.preferredC64uBaseUrl ? { baseUrl: options.preferredC64uBaseUrl } : {}),
             ...(!config?.c64u?.networkPassword && options?.preferredC64uNetworkPassword
                 ? { networkPassword: options.preferredC64uNetworkPassword }
                 : {}),
-        };
-        return {
-            primary,
-            secondary: new C64uBackend(secondaryConfig),
-            secondaryType,
-        };
-    }
-    if (secondaryType === "vice" && config?.vice) {
-        return {
-            primary,
-            secondary: new ViceBackend(config.vice),
-            secondaryType,
-        };
+        }));
     }
-    return {
-        primary,
-        secondary: null,
-        secondaryType: null,
-    };
+    return { primary, facades };
 }
 function shouldProvisionSecondaryC64u(config, options) {
     return Boolean(config?.c64u

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,
         });