c64bridge 0.9.0 → 0.9.2

package/dist/c64Client.js

@@ -8,8 +8,8 @@ See <https://www.gnu.org/licenses/> for details.
 import { Buffer } from "node:buffer";
 import { createSocket } from "node:dgram";
 import axios from "axios";
-import { basicToPrg } from "./basicConverter.js";
-import { assemblyToPrg } from "./assemblyConverter.js";
+import { basicToPrg } from "./tools/translation/basicTokenizer.js";
+import { assemblyToPrg } from "./tools/translation/assembler.js";
 import { screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
 import { createAllFacades, createFacade } from "./device.js";
@@ -28,6 +28,17 @@ const DEFAULT_TEXT_FOREGROUND = 1;
 const DEFAULT_BORDER_COLOR = 6;
 const DEFAULT_BACKGROUND_COLOR = 0;
 const SPACE_SCREEN_CODE = 0x20;
+function validateMemoryRange(address, length) {
+    if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
+        throw new Error("Address must be within 0x0000 - 0xFFFF");
+    }
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error("Length must be greater than zero");
+    }
+    if (address + length - 1 > 0xffff) {
+        throw new Error("Memory range must stay within 0x0000 - 0xFFFF");
+    }
+}
 export class C64Client {
     constructor(baseUrl, options = {}) {
         this.allFacades = new Map();
@@ -481,9 +492,7 @@ export class C64Client {
             const resolved = resolveAddressSymbol(addressInput);
             const address = resolved ?? this.parseNumeric(addressInput);
             const length = this.parseNumeric(lengthInput);
-            if (length <= 0) {
-                throw new Error("Length must be greater than zero");
-            }
+            validateMemoryRange(address, length);
             const rawBytes = await this.readMemoryRaw(address, length);
             const bytes = rawBytes.slice(0, length);
             return {
@@ -507,9 +516,7 @@ export class C64Client {
             const resolved = resolveAddressSymbol(addressInput);
             const address = resolved ?? this.parseNumeric(addressInput);
             const dataBuffer = this.hexStringToBuffer(bytesInput);
-            if (dataBuffer.length === 0) {
-                throw new Error("No bytes provided");
-            }
+            validateMemoryRange(address, dataBuffer.length);
             // Prefer PUT with hex data for up to 128 bytes; fall back to POST binary for larger writes
             const addrStr = this.formatAddress(address);
             try {
@@ -1467,6 +1474,7 @@ export class C64Client {
      * Public to allow advanced polling and monitoring use cases.
      */
     async readMemoryRaw(address, length) {
+        validateMemoryRange(address, length);
         try {
             const facade = await this.facadePromise;
             return await facade.readMemory(address, length);
@@ -1492,6 +1500,84 @@ export class C64Client {
         }
         return body instanceof ArrayBuffer ? new Uint8Array(body) : this.extractBytes(body);
     }
+    /**
+     * Low-level memory write that delegates to the active backend's facade.
+     * 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) {
+        if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
+            throw new Error("Address must be within 0x0000 - 0xFFFF");
+        }
+        const facade = await this.facadePromise;
+        const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        validateMemoryRange(address, buf.length);
+        await facade.writeMemory(address, buf);
+    }
+    /**
+     * Inject a sequence of PETSCII byte values into the KERNAL keyboard buffer
+     * using shared memory writes. Works on both C64U and VICE because both
+     * backends expose `writeMemory`/`readMemory` against the C64 zero-page and
+     * the keyboard queue at $0277.
+     *
+     * The KERNAL buffer ($0277-$0280) holds 10 bytes; $00C6 (NDX) tracks the
+     * number of pending characters. We chunk the input, then poll NDX until
+     * the kernel has consumed each chunk before queueing the next one.
+     *
+     * @param bytes      Raw PETSCII bytes (already token-expanded by caller)
+     * @param options    Optional knobs for chunk size, drain timing, and total
+     *                   timeout. The defaults mirror KERNAL behavior.
+     */
+    async injectKeyboardQueue(bytes, options) {
+        const data = Buffer.isBuffer(bytes)
+            ? bytes
+            : Buffer.from(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes));
+        if (data.length === 0) {
+            return;
+        }
+        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 KEYD = 0x0277; // KERNAL keyboard buffer base
+        const NDX = 0x00C6; // pending byte count
+        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.
+            const drainStart = Date.now();
+            while (Date.now() - drainStart < totalTimeoutMs) {
+                const ndx = await facade.readMemory(NDX, 1);
+                if ((ndx[0] ?? 0) === 0) {
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollMs));
+            }
+        }
+    }
+    async viceExitMonitor() {
+        await this.withViceMonitor((client) => client.exitMonitor());
+    }
+    async viceKeyboardFeed(text) {
+        await this.withViceMonitor((client) => client.keyboardFeed(text));
+    }
+    async viceMemSet(address, bytes) {
+        const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        await this.withViceMonitor((client) => client.memSet(address, buf));
+    }
+    async viceMemGet(address, length) {
+        const end = (address + length - 1) & 0xffff;
+        return this.withViceMonitor((client) => client.memGet(address, end));
+    }
+    async viceNuclearReset() {
+        const backend = await this.requireViceBackend();
+        await backend.nuclearReset();
+    }
     async viceCheckpointList() {
         return this.withViceMonitor((client) => client.checkpointList());
     }
@@ -1621,17 +1707,27 @@ export class C64Client {
         const lower = trimmed.toLowerCase();
         let radix = 10;
         let literal = lower;
+        let pattern;
         if (lower.startsWith("$")) {
             radix = 16;
             literal = lower.slice(1);
+            pattern = /^[0-9a-f]+$/;
         }
         else if (lower.startsWith("0x")) {
             radix = 16;
             literal = lower.slice(2);
+            pattern = /^[0-9a-f]+$/;
         }
         else if (lower.startsWith("%")) {
             radix = 2;
             literal = lower.slice(1);
+            pattern = /^[01]+$/;
+        }
+        else {
+            pattern = /^[0-9]+$/;
+        }
+        if (!pattern.test(literal)) {
+            throw new Error(`Unable to parse numeric value "${value}"`);
         }
         const parsed = Number.parseInt(literal, radix);
         if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
@@ -1665,6 +1761,9 @@ export class C64Client {
         if (cleaned.length % 2 !== 0) {
             throw new Error("Hex string must contain an even number of characters");
         }
+        if (!/^[0-9a-f]+$/.test(cleaned)) {
+            throw new Error("Hex string contains non-hexadecimal characters");
+        }
         return Buffer.from(cleaned, "hex");
     }
     hzToSidFrequency(hz, system = "PAL") {

package/dist/device.js

@@ -339,15 +339,15 @@ export class ViceBackend {
                 extraArgs: this.extraArgs,
             });
         }
-        const handle = await startViceProcess({
+        const handle = await startViceProcess(buildManagedViceProcessOptions({
             binary: this.exe,
             directory: this.directory,
             host: this.host,
             port: this.port,
             warp: this.warp,
             visible: this.visible,
-            extraArgs: this.extraArgs.length > 0 ? this.extraArgs : undefined,
-        });
+            extraArgs: this.extraArgs,
+        }));
         this.lastProcessStart = Date.now();
         if (this.debugEnabled) {
             console.error("[vice-backend] VICE process started", { pid: handle.process.pid });
@@ -378,6 +378,7 @@ 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", () => {
             for (const [, handle] of ViceBackend.supervisors) {
                 handle.stop().catch(() => { });
@@ -579,6 +580,31 @@ export class ViceBackend {
             return { success: false, details };
         }
     }
+    async nuclearReset() {
+        const poweroffResult = await this.poweroff();
+        if (!poweroffResult.success) {
+            return poweroffResult;
+        }
+        if (!this.manageProcess) {
+            return {
+                success: false,
+                details: {
+                    code: "UNSUPPORTED",
+                    message: "VICE nuclear reset requires a managed process; unmanaged instances can only be powered off.",
+                },
+            };
+        }
+        try {
+            await this.ensureProcess();
+            return { success: true };
+        }
+        catch (error) {
+            const details = error instanceof Error
+                ? { message: error.message }
+                : error;
+            return { success: false, details };
+        }
+    }
     async menuButton() { throw unsupported("menuButton"); }
     async debugregRead() { throw unsupported("debugregRead"); }
     async debugregWrite(_v) { throw unsupported("debugregWrite"); }
@@ -838,12 +864,26 @@ function resolveViceLaunch(options, dependencies = {}) {
         }),
     };
 }
+function buildManagedViceProcessOptions(input) {
+    return {
+        binary: input.binary,
+        directory: input.directory,
+        host: input.host,
+        port: input.port,
+        warp: input.warp,
+        visible: input.visible,
+        extraArgs: input.extraArgs.length > 0 ? input.extraArgs : undefined,
+    };
+}
 export function __resolveViceBinaryForTests(options, findBinary) {
     return resolveViceBinary(options, findBinary ?? which);
 }
 export function __resolveViceLaunchForTests(options, dependencies) {
     return resolveViceLaunch(options, dependencies);
 }
+export function __buildViceProcessOptionsForTests(input) {
+    return buildManagedViceProcessOptions(input);
+}
 export async function createFacade(logger, options) {
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
     if (options?.preferredC64uBaseUrl) {

package/dist/rag/indexer.js

@@ -474,20 +474,30 @@ export async function buildAllIndexes({ model, embeddingsDir: overrideDir, basic
     repoMetadataCache.clear();
     const embeddingsDir = resolveEmbeddingsDir(overrideDir);
     const paths = embeddingIndexPaths(embeddingsDir);
-    // Collect all markdown files under doc/ recursively, plus any explicitly provided RAG_DOC_FILES
+    // Production indexing defaults to the repo docs tree. Tests and other callers can
+    // override that set explicitly, including passing an empty array to opt out.
     const docCandidates = [];
-    try {
-        const mdFiles = await collectFiles(DOC_ROOT, [".md"]);
-        for (const f of mdFiles) {
+    if (docFiles !== undefined) {
+        for (const f of docFiles) {
             if (!shouldExcludeDocFile(f)) {
                 docCandidates.push(f);
             }
         }
     }
-    catch { }
-    for (const f of ENV_DOC_FILES) {
-        if (!shouldExcludeDocFile(f)) {
-            docCandidates.push(f);
+    else {
+        try {
+            const mdFiles = await collectFiles(DOC_ROOT, [".md"]);
+            for (const f of mdFiles) {
+                if (!shouldExcludeDocFile(f)) {
+                    docCandidates.push(f);
+                }
+            }
+        }
+        catch { }
+        for (const f of ENV_DOC_FILES) {
+            if (!shouldExcludeDocFile(f)) {
+                docCandidates.push(f);
+            }
         }
     }
     // De-duplicate

package/dist/sidwaveCompiler.js

@@ -6,7 +6,7 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
-import { assemblyToPrg } from "./assemblyConverter.js";
+import { assemblyToPrg } from "./tools/translation/assembler.js";
 import { midiToHz, noteNameToMidi } from "./sidwave.js";
 /**
  * Small SIDWAVE to PRG compiler: generates a 50/60Hz player that writes SID registers from a precomputed frame table.

package/dist/tools/debug.js

@@ -57,6 +57,7 @@ const createCheckpointArgsSchema = objectSchema({
         stopOnHit: optionalSchema(booleanSchema({ description: "Pause execution when hit (default true).", default: true })),
         enabled: optionalSchema(booleanSchema({ description: "Whether the checkpoint is enabled (default true).", default: true })),
         temporary: optionalSchema(booleanSchema({ description: "Automatically remove after first hit.", default: false })),
+        label: optionalSchema(stringSchema({ description: "Optional human-readable label stored in-process.", maxLength: 64 })),
         operations: optionalSchema(objectSchema({
             description: "Checkpoint operation filters.",
             properties: {
@@ -147,6 +148,42 @@ const stepReturnArgsSchema = objectSchema({
     required: ["op"],
     additionalProperties: false,
 });
+const getMonitorStateArgsSchema = objectSchema({
+    description: "Read CPU registers and return the current monitor state.",
+    properties: {
+        op: literalSchema("get_monitor_state"),
+        memspace: memspaceSchema,
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
+const waitForStateArgsSchema = objectSchema({
+    description: "Poll CPU registers until PC equals expectedPC or timeout elapses.",
+    properties: {
+        op: literalSchema("wait_for_state"),
+        expectedPC: optionalSchema(stringSchema({ description: "Target PC address to wait for (e.g. $0810).", minLength: 1 })),
+        timeoutMs: optionalSchema(numberSchema({ description: "Maximum wait time in milliseconds.", integer: true, minimum: 1, maximum: 60000, default: 5000 })),
+        pollMs: optionalSchema(numberSchema({ description: "Poll interval in milliseconds.", integer: true, minimum: 10, maximum: 1000, default: 100 })),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
+const nuclearResetArgsSchema = objectSchema({
+    description: "Kill and restart the VICE process (managed instances only).",
+    properties: {
+        op: literalSchema("nuclear_reset"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
+const continueExecutionArgsSchema = objectSchema({
+    description: "Exit the Binary Monitor and resume CPU execution (BM 0xAA Exit).",
+    properties: {
+        op: literalSchema("continue_execution"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
 const debugOperationSchemas = [
     listCheckpointsArgsSchema,
     getCheckpointArgsSchema,
@@ -159,14 +196,19 @@ const debugOperationSchemas = [
     setRegistersArgsSchema,
     stepArgsSchema,
     stepReturnArgsSchema,
+    getMonitorStateArgsSchema,
+    waitForStateArgsSchema,
+    nuclearResetArgsSchema,
+    continueExecutionArgsSchema,
 ];
+const checkpointLabels = new Map();
 const debugOperationHandlers = {
     list_checkpoints: async (_args, ctx) => {
         try {
             listCheckpointsArgsSchema.parse(_args);
             ctx.logger.info("Listing VICE checkpoints");
             const checkpoints = await ctx.client.viceCheckpointList();
-            return jsonResult({ checkpoints: checkpoints.map(formatCheckpoint) }, { success: true, count: checkpoints.length });
+            return jsonResult({ checkpoints: checkpoints.map((cp) => formatCheckpoint(cp, checkpointLabels.get(cp.id))) }, { success: true, count: checkpoints.length });
         }
         catch (error) {
             return handleToolError(error);
@@ -176,7 +218,7 @@ const debugOperationHandlers = {
         try {
             const parsed = getCheckpointArgsSchema.parse(args);
             const checkpoint = await ctx.client.viceCheckpointGet(parsed.id);
-            return jsonResult({ checkpoint: formatCheckpoint(checkpoint) }, { success: true });
+            return jsonResult({ checkpoint: formatCheckpoint(checkpoint, checkpointLabels.get(checkpoint.id)) }, { success: true });
         }
         catch (error) {
             return handleToolError(error);
@@ -201,8 +243,11 @@ const debugOperationHandlers = {
                 },
                 memspace: normaliseMemspace(parsed.memspace),
             });
-            ctx.logger.info("Created VICE checkpoint", { id: created.id, start: formatAddress(created.start) });
-            return jsonResult({ checkpoint: formatCheckpoint(created) }, { success: true, id: created.id });
+            if (parsed.label) {
+                checkpointLabels.set(created.id, parsed.label);
+            }
+            ctx.logger.info("Created VICE checkpoint", { id: created.id, start: formatAddress(created.start), label: parsed.label });
+            return jsonResult({ checkpoint: formatCheckpoint(created, checkpointLabels.get(created.id)) }, { success: true, id: created.id });
         }
         catch (error) {
             return handleToolError(error);
@@ -212,6 +257,7 @@ const debugOperationHandlers = {
         try {
             const parsed = deleteCheckpointArgsSchema.parse(args);
             await ctx.client.viceCheckpointDelete(parsed.id);
+            checkpointLabels.delete(parsed.id);
             ctx.logger.info("Deleted VICE checkpoint", { id: parsed.id });
             return textResult(`Deleted checkpoint ${parsed.id}.`, { success: true, id: parsed.id });
         }
@@ -345,6 +391,87 @@ const debugOperationHandlers = {
             return handleToolError(error);
         }
     },
+    get_monitor_state: async (args, ctx) => {
+        try {
+            const parsed = getMonitorStateArgsSchema.parse(args);
+            const memspace = normaliseMemspace(parsed.memspace);
+            const [metadata, values] = await Promise.all([
+                ctx.client.viceRegistersAvailable(memspace),
+                ctx.client.viceRegistersGet(memspace),
+            ]);
+            const metadataById = new Map(metadata.map((m) => [m.id, m]));
+            const registers = values.map((v) => {
+                const meta = metadataById.get(v.id);
+                return { id: v.id, name: meta?.name, bits: meta?.bits, size: v.size, value: v.value };
+            });
+            const pc = registers.find((r) => r.name?.toUpperCase() === "PC");
+            ctx.logger.info("Read monitor state", { memspace, pc: pc ? formatAddress(pc.value) : "unknown" });
+            return jsonResult({ memspace, registers, pc: pc ? formatAddress(pc.value) : undefined }, { success: true, memspace, count: registers.length });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    wait_for_state: async (args, ctx) => {
+        try {
+            const parsed = waitForStateArgsSchema.parse(args);
+            const timeoutMs = parsed.timeoutMs ?? 5000;
+            const pollMs = parsed.pollMs ?? 100;
+            const targetPC = parsed.expectedPC ? parseAddress(parsed.expectedPC, "expectedPC") : undefined;
+            const metadata = await ctx.client.viceRegistersAvailable(0);
+            const metadataById = new Map(metadata.map((m) => [m.id, m]));
+            const pcId = metadata.find((m) => m.name.toUpperCase() === "PC")?.id;
+            const deadline = Date.now() + timeoutMs;
+            let values = [];
+            let currentPC;
+            while (Date.now() < deadline) {
+                values = await ctx.client.viceRegistersGet(0);
+                currentPC = pcId !== undefined ? values.find((v) => v.id === pcId)?.value : undefined;
+                if (targetPC === undefined || currentPC === targetPC) {
+                    break;
+                }
+                await new Promise((res) => setTimeout(res, pollMs));
+            }
+            const matched = targetPC === undefined || currentPC === targetPC;
+            const regs = values.map((v) => {
+                const meta = metadataById.get(v.id);
+                return { id: v.id, name: meta?.name, bits: meta?.bits, size: v.size, value: v.value };
+            });
+            ctx.logger.info("wait_for_state settled", { matched, pc: currentPC !== undefined ? formatAddress(currentPC) : "unknown" });
+            return jsonResult({
+                matched,
+                timedOut: !matched,
+                pc: currentPC !== undefined ? formatAddress(currentPC) : undefined,
+                registers: regs,
+            }, { success: true, matched });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    nuclear_reset: async (args, ctx) => {
+        try {
+            nuclearResetArgsSchema.parse(args);
+            ctx.logger.info("Performing nuclear reset of VICE process");
+            await ctx.client.viceNuclearReset();
+            checkpointLabels.clear();
+            return textResult("VICE process stopped and restarted.", { success: true });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    continue_execution: async (args, ctx) => {
+        try {
+            continueExecutionArgsSchema.parse(args);
+            await ctx.client.viceExitMonitor();
+            ctx.logger.info("Exited Binary Monitor — CPU resumed");
+            return textResult("Execution resumed.", { success: true });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
 };
 const debugOperationDispatcher = createOperationDispatcher("c64_debug", debugOperationHandlers);
 export const debugModuleGroup = defineToolModule({
@@ -384,6 +511,31 @@ export const debugModuleGroup = defineToolModule({
                     description: "Read CPU registers from memspace 0 (default).",
                     arguments: { op: "get_registers" },
                 },
+                {
+                    name: "Create labelled breakpoint",
+                    description: "Set a breakpoint at $0810 with a descriptive label.",
+                    arguments: { op: "create_checkpoint", address: "$0810", label: "entry_point" },
+                },
+                {
+                    name: "Get monitor state",
+                    description: "Read current CPU state including all registers and PC.",
+                    arguments: { op: "get_monitor_state" },
+                },
+                {
+                    name: "Wait for PC",
+                    description: "Poll until PC reaches $0810 or 5 s elapses.",
+                    arguments: { op: "wait_for_state", expectedPC: "$0810", timeoutMs: 5000 },
+                },
+                {
+                    name: "Nuclear reset",
+                    description: "Kill and restart the VICE process, clearing all state.",
+                    arguments: { op: "nuclear_reset" },
+                },
+                {
+                    name: "Continue execution",
+                    description: "Exit the BM monitor and let the CPU run freely.",
+                    arguments: { op: "continue_execution" },
+                },
             ],
             execute: debugOperationDispatcher,
         },
@@ -395,9 +547,10 @@ function handleToolError(error) {
     }
     return unknownErrorResult(error);
 }
-function formatCheckpoint(checkpoint) {
+function formatCheckpoint(checkpoint, label) {
     return {
         id: checkpoint.id,
+        ...(label ? { label } : {}),
         start: formatAddress(checkpoint.start),
         end: formatAddress(checkpoint.end),
         enabled: checkpoint.enabled,