c64bridge 0.9.1 → 0.9.3

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 "./tools/basicTokenizer.js";
-import { assemblyToPrg } from "./tools/assember.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();
@@ -48,7 +59,6 @@ export class C64Client {
             }).then((sel) => sel.facade);
             this.allFacades.set("c64u", this.facadePromise);
             this.initPromise = Promise.resolve();
-            void this.primeGreetingDd00Cache(["c64u"]);
             return;
         }
         const allFacadesPromise = createAllFacades(undefined, {
@@ -65,12 +75,6 @@ export class C64Client {
                 this.allFacades.set(secondaryType, Promise.resolve(secondary));
             }
         });
-        void this.initPromise.then(async () => {
-            if (this.allFacades.has("vice")) {
-                await this.prewarmBackends(["vice"]);
-            }
-            void this.primeGreetingDd00Cache();
-        }).catch(() => { });
     }
     async requireViceBackend() {
         const facade = await this.facadePromise;
@@ -481,9 +485,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 +509,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 +1467,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);
@@ -1498,8 +1499,12 @@ export class C64Client {
      * 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);
     }
     /**
@@ -1695,17 +1700,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) {
@@ -1739,6 +1754,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/config.js

@@ -7,6 +7,7 @@ const DEFAULT_CONFIG = {
     c64_host: DEFAULT_HOST,
     baseUrl: buildBaseUrl(DEFAULT_HOST, DEFAULT_PORT),
     c64_port: DEFAULT_PORT,
+    vicePrewarm: false,
 };
 let cachedConfig = null;
 export function loadConfig() {
@@ -35,6 +36,7 @@ export function loadConfig() {
     rawConfig ?? (rawConfig = {});
     // New schema: prefer c64u.{host,port,baseUrl}; keep legacy fields as fallback
     const c64u = rawConfig?.c64u;
+    const vice = rawConfig?.vice;
     const parsedC64uHost = parseEndpoint(configuredString(c64u?.host));
     const parsedC64uHostname = parseEndpoint(configuredString(c64u?.hostname));
     const parsedLegacyHost = parseEndpoint(configuredString(rawConfig?.c64_host));
@@ -73,6 +75,7 @@ export function loadConfig() {
         baseUrl,
         c64_port: port,
         networkPassword: firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(c64u?.networkPassword), configuredString(rawConfig?.networkPassword)),
+        vicePrewarm: firstDefined(configuredBoolean(process.env.VICE_PREWARM), configuredBoolean(vice?.prewarm), configuredBoolean(rawConfig?.vicePrewarm)) ?? false,
     };
     cachedConfig = config;
     return config;
@@ -92,6 +95,25 @@ function configuredPort(value) {
     }
     return undefined;
 }
+function configuredBoolean(value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["1", "true", "yes", "on"].includes(normalized))
+            return true;
+        if (["0", "false", "no", "off"].includes(normalized))
+            return false;
+    }
+    return undefined;
+}
 function normaliseBaseUrl(value) {
     const input = configuredString(value);
     if (!input)

package/dist/mcp-server.js

@@ -60,6 +60,7 @@ async function main() {
     writeDiagnosticEvent("config_loaded", {
         baseUrl,
         hasNetworkPassword: Boolean(config.networkPassword),
+        vicePrewarm: config.vicePrewarm,
     });
     // Initialize C64 client (reuse existing)
     const client = await withDiagnosticSpan("startup", "create_client", { baseUrl }, async () => new C64Client(baseUrl, {
@@ -69,11 +70,22 @@ async function main() {
     const initialBackendType = await withDiagnosticSpan("startup", "resolve_active_backend", {}, () => client.getActiveBackendType());
     setPlatform(initialBackendType);
     writeDiagnosticEvent("platform_initialised", { platform: initialBackendType });
-    void withDiagnosticSpan("startup", "prewarm_backends", { backends: ["vice"] }, () => client.prewarmBackends(["vice"])).then((results) => {
-        writeDiagnosticEvent("backend_prewarm_complete", { results });
-    }).catch((error) => {
-        writeDiagnosticEvent("backend_prewarm_failed", { error });
-    });
+    if (config.vicePrewarm) {
+        const availableBackends = client.getAvailableBackends();
+        if (availableBackends.includes("vice")) {
+            writeDiagnosticEvent("vice_prewarm_start");
+            void client.prewarmBackends(["vice"])
+                .then((result) => {
+                writeDiagnosticEvent("vice_prewarm_complete", { result });
+            })
+                .catch((error) => {
+                writeDiagnosticEvent("vice_prewarm_failed", { error });
+            });
+        }
+        else {
+            writeDiagnosticEvent("vice_prewarm_skipped", { reason: "vice_not_configured" });
+        }
+    }
     const rag = createLazyRagRetriever(() => initRag(), {
         onInitStart() {
             writeDiagnosticEvent("rag_init_start");

package/dist/rag/knowledgeIndex.js

@@ -286,7 +286,14 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.io.cia.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "hardware"],
             },
             {
@@ -298,19 +305,48 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "zero-page"],
             },
+            {
+                uri: RESOURCE_URIS.basic.romRoutines,
+                name: "BASIC ROM Routines Memory Map",
+                description: "Memory-map-style breakdown of BASIC ROM routines, tables, parser helpers, and entry points.",
+                relativePath: "data/basic/rom-routines.md",
+                priority: "reference",
+                summary: "Maps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries.",
+                prompts: ["memory-debug", "assembly-program", "basic-program"],
+                tools: ["read", "verify_and_write_memory"],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.basic.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
+                tags: ["memory", "basic", "rom"],
+            },
             {
                 uri: RESOURCE_URIS.kernal.romRoutines,
-                name: "KERNAL Memory Map",
-                description: "Detailed breakdown of KERNAL ROM routines and entry points.",
-                relativePath: "data/memory/kernal-memory-map.md",
+                name: "KERNAL ROM Routines Memory Map",
+                description: "Memory-map-style breakdown of KERNAL ROM routines, vectors, tables, and entry points.",
+                relativePath: "data/kernal/rom-routines.md",
                 priority: "reference",
-                summary: "Lists KERNAL ROM vectors and service routines for OS-level functionality.",
+                summary: "Maps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "kernal"],
             },
             {
@@ -322,7 +358,12 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read", "debugreg_write"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.io.cia.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["io", "hardware"],
             },
             {
@@ -334,7 +375,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read"],
-                relatedResources: [RESOURCE_URIS.io.spec, RESOURCE_URIS.memory.map],
+                relatedResources: [
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                ],
                 tags: ["io", "hardware"],
             },
         ],

package/dist/rag/resourceUris.js

@@ -10,6 +10,7 @@ export const RESOURCE_URIS = {
     basic: {
         spec: "c64://basic/spec",
         pitfalls: "c64://basic/pitfalls",
+        romRoutines: "c64://basic/rom-routines",
     },
     assembly: {
         spec6510: "c64://assembly/6510-spec",
@@ -80,6 +81,7 @@ export const CANONICAL_KNOWLEDGE_RESOURCE_URIS = Object.freeze([
     RESOURCE_URIS.graphics.spriteCharset.bestPractices,
     RESOURCE_URIS.memory.map,
     RESOURCE_URIS.memory.zeroPageAndWorkspace,
+    RESOURCE_URIS.basic.romRoutines,
     RESOURCE_URIS.kernal.romRoutines,
     RESOURCE_URIS.io.spec,
     RESOURCE_URIS.io.cia.spec,

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 "./tools/assember.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/input.js

@@ -1,4 +1,4 @@
-import { createOperationDispatcher, defineToolModule, } from "./types.js";
+import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "./types.js";
 import { arraySchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { textResult } from "./responses.js";
 import { ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
@@ -285,7 +285,7 @@ export const inputModule = defineToolModule({
     domain: "input",
     summary: "Cross-platform keyboard input plus VICE-only joystick simulation.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://specs/assembly", "c64://specs/memory-map"],
+    resources: ["c64://guide/bootstrap", "c64://memory/map", "c64://io/cia/spec"],
     prompts: [],
     defaultTags: ["input"],
     workflowHints: [
@@ -298,16 +298,14 @@ export const inputModule = defineToolModule({
             name: "c64_input",
             description: "Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).",
             summary: "Types text, taps keys, and simulates joystick movements.",
-            inputSchema: {
-                type: "object",
+            inputSchema: discriminatedUnionSchema({
                 description: "Input operations: write_text, key, joystick.",
-                oneOf: [
+                variants: [
                     writeTextArgsSchema.jsonSchema,
                     keyArgsSchema.jsonSchema,
                     joystickArgsSchema.jsonSchema,
                 ],
-                discriminator: { propertyName: "op" },
-            },
+            }),
             operationPlatforms: { joystick: ["vice"] },
             tags: ["input", "keyboard", "joystick"],
             examples: [

package/dist/tools/memory.js

@@ -5,8 +5,8 @@ import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
-import { disassemble, formatDisassembly } from "./disassembler.js";
-import { getViceSymbols } from "./symbolRegistry.js";
+import { disassemble, formatDisassembly } from "./translation/disassembler.js";
+import { getViceSymbols } from "./translation/symbolRegistry.js";
 import { resolveAddressSymbol } from "../knowledge.js";
 function toRecord(details) {
     if (details && typeof details === "object") {
@@ -39,6 +39,12 @@ function parseHexInternal(value, path) {
     if (cleaned.length === 0) {
         return { bytes: new Uint8Array(), canonical: "$" };
     }
+    if (!/^[0-9A-F]+$/.test(cleaned)) {
+        throw new ToolValidationError("Hex string contains non-hexadecimal characters", {
+            path,
+            details: { value },
+        });
+    }
     const bytes = Uint8Array.from(Buffer.from(cleaned, "hex"));
     return { bytes, canonical: `$${cleaned}` };
 }
@@ -399,6 +405,7 @@ async function executeDisassemble(rawArgs, ctx) {
         const length = parsed.length ?? 64;
         ctx.logger.info("Disassembling VICE memory", { address: parsed.address, length });
         const address = parseAddressArg(parsed.address, "$.address");
+        validateRangeWithinAddressSpace(address, length, "$.address");
         const bytes = await ctx.client.readMemoryRaw(address, length);
         const symbols = ctx.platform?.id === "vice" ? getViceSymbols() : undefined;
         const lines = disassemble(bytes, address, parsed.instructionCount, symbols);
@@ -597,6 +604,8 @@ async function executeCompareMemory(rawArgs, ctx) {
         const a2 = parseAddressArg(parsed.address2, "$.address2");
         const len = parsed.length;
         const maxDiffs = parsed.maxDiffs ?? 10;
+        validateRangeWithinAddressSpace(a1, len, "$.address1");
+        validateRangeWithinAddressSpace(a2, len, "$.address2");
         ctx.logger.info("Comparing memory regions", { a1: fmtAddr(a1), a2: fmtAddr(a2), len });
         const [r1, r2] = await Promise.all([
             ctx.client.readMemoryRaw(a1, len),

package/dist/tools/programRunners.js

@@ -1,12 +1,12 @@
 import fs from "node:fs";
-import { assemblyToPrgDetailed, AssemblyError } from "./assember.js";
-import { basicToPrg } from "./basicTokenizer.js";
+import { assemblyToPrgDetailed, AssemblyError } from "./translation/assembler.js";
+import { basicToPrg } from "./translation/basicTokenizer.js";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
 import { textResult } from "./responses.js";
 import { ToolExecutionError, ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 import { pollForProgramOutcome } from "./pollValidator.js";
-import { clearViceSymbols, setViceSymbols, parseViceSymbolFile } from "./symbolRegistry.js";
+import { clearViceSymbols, setViceSymbols, parseViceSymbolFile } from "./translation/symbolRegistry.js";
 function extractFailureDetails(details) {
     if (details === undefined || details === null) {
         return undefined;

package/dist/tools/responses.js

@@ -1,5 +1,5 @@
 export function textResult(text, metadata) {
-    return {
+    const result = {
         content: [
             {
                 type: "text",
@@ -8,6 +8,19 @@ export function textResult(text, metadata) {
         ],
         metadata,
     };
+    if (metadata !== undefined) {
+        return {
+            ...result,
+            structuredContent: {
+                type: "json",
+                data: {
+                    message: text,
+                    ...metadata,
+                },
+            },
+        };
+    }
+    return result;
 }
 export function jsonResult(data, metadata) {
     const text = typeof data === "string"