c64bridge 0.9.0 → 0.9.1

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/basicTokenizer.js";
+import { assemblyToPrg } from "./tools/assember.js";
 import { screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
 import { createAllFacades, createFacade } from "./device.js";
@@ -1492,6 +1492,80 @@ 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) {
+        const facade = await this.facadePromise;
+        const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        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());
     }

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/assember.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/{assemblyConverter.js → tools/assember.js}

@@ -77,6 +77,9 @@ const DIRECTIVE_ALIASES = {
 };
 const RELATIVE_ONLY = new Set(["BCC", "BCS", "BEQ", "BMI", "BNE", "BPL", "BVC", "BVS"]);
 export function assemblyToPrg(source, options) {
+    return assemblyToPrgDetailed(source, options).prg;
+}
+export function assemblyToPrgDetailed(source, options) {
     const normalized = normalizeSource(source);
     const loadAddress = options?.loadAddress ?? DEFAULT_LOAD_ADDRESS;
     const rootFile = options?.fileName ?? "(input)";
@@ -86,7 +89,7 @@ export function assemblyToPrg(source, options) {
     const assembler = new Assembler(statements, loadAddress);
     assembler.runPass(0);
     assembler.runPass(1);
-    return assembler.buildPrg();
+    return { prg: assembler.buildPrg(), symbols: assembler.getSymbols() };
 }
 function normalizeSource(input) {
     return input.replace(/\r\n?/g, "\n");
@@ -608,6 +611,9 @@ class SymbolTable {
         }
         return this.globals.get(label);
     }
+    allGlobals() {
+        return this.globals;
+    }
     ensureLocalScope(scope) {
         if (!this.locals.has(scope)) {
             this.locals.set(scope, new Map());
@@ -658,6 +664,9 @@ class Assembler {
         header.writeUInt16LE(start, 0);
         return Buffer.concat([header, Buffer.from(body)]);
     }
+    getSymbols() {
+        return this.symbolTable.allGlobals();
+    }
     processLine(line, pass) {
         for (const label of line.labels) {
             if (pass === 0) {

package/dist/{basicConverter.js → tools/basicTokenizer.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 { asciiToPetscii, encodeStringWithNames } from "./petscii.js";
+import { asciiToPetscii, encodeStringWithNames } from "../petscii.js";
 const DEFAULT_START_ADDRESS = 0x0801;
 const REM_TOKEN = 0x8f;
 const TOKEN_TABLE = buildTokenTable();

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,