c64bridge 0.8.1 → 0.9.1

package/dist/tools/memory.js

@@ -1,8 +1,13 @@
 import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
-import { textResult } from "./responses.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 { resolveAddressSymbol } from "../knowledge.js";
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -79,6 +84,18 @@ function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id;
     return platformId !== "vice";
 }
+export const __memoryHelpersForTests = {
+    toRecord,
+    normaliseFailure,
+    cleanHex,
+    parseUserHex,
+    parseFirmwareHex,
+    formatByte,
+    resolveAddressLabel,
+    resolveLength,
+    supportsMachinePause,
+    stripOperationDiscriminator,
+};
 const readScreenArgsSchema = objectSchema({
     description: "No arguments are required for reading the current screen contents.",
     properties: {},
@@ -171,13 +188,21 @@ async function executeReadMemory(rawArgs, ctx) {
         const detailRecord = toRecord(result.details) ?? {};
         const resolvedAddress = resolveAddressLabel(detailRecord, parsed.address);
         const resolvedLength = resolveLength(detailRecord) ?? parsed.length;
-        return textResult(`Read ${resolvedLength} bytes starting at ${resolvedAddress}.`, {
+        const data = {
             success: true,
             address: resolvedAddress,
             length: resolvedLength,
             hexData: result.data ?? null,
             details: detailRecord,
-        });
+        };
+        const base = textResult(`Read ${resolvedLength} bytes starting at ${resolvedAddress}.`, data);
+        return {
+            ...base,
+            structuredContent: {
+                type: "json",
+                data,
+            },
+        };
     }
     catch (error) {
         if (error instanceof ToolError) {
@@ -344,19 +369,318 @@ async function executeWriteMemory(rawArgs, ctx) {
         return unknownErrorResult(error);
     }
 }
+const disassembleArgsSchema = objectSchema({
+    description: "Parameters for disassembling a block of VICE memory into 6502/6510 instructions.",
+    properties: {
+        address: stringSchema({
+            description: "Start address as $HHHH, decimal, or symbol name.",
+            minLength: 1,
+        }),
+        length: numberSchema({
+            description: "Number of bytes to read and disassemble.",
+            integer: true,
+            minimum: 1,
+            maximum: 4096,
+            default: 64,
+        }),
+        instructionCount: optionalSchema(numberSchema({
+            description: "Stop after this many instructions (overrides length as a termination condition).",
+            integer: true,
+            minimum: 1,
+            maximum: 512,
+        })),
+    },
+    required: ["address"],
+    additionalProperties: false,
+});
+async function executeDisassemble(rawArgs, ctx) {
+    try {
+        const parsed = disassembleArgsSchema.parse(rawArgs ?? {});
+        const length = parsed.length ?? 64;
+        ctx.logger.info("Disassembling VICE memory", { address: parsed.address, length });
+        const address = parseAddressArg(parsed.address, "$.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);
+        const text = formatDisassembly(lines);
+        const addrHex = `$${address.toString(16).toUpperCase().padStart(4, "0")}`;
+        return textResult(`Disassembly of ${lines.length} instructions starting at ${addrHex}:\n\n${text}`, {
+            success: true,
+            address: addrHex,
+            bytesRead: bytes.length,
+            instructionCount: lines.length,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError) {
+            return toolErrorResult(error);
+        }
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared address-parsing helper
+// ---------------------------------------------------------------------------
+function parseAddressArg(raw, fieldPath) {
+    const trimmed = raw.trim();
+    let addr;
+    if (/^\$[0-9A-Fa-f]+$/.test(trimmed)) {
+        addr = parseInt(trimmed.slice(1), 16);
+    }
+    else if (/^0[xX][0-9A-Fa-f]+$/.test(trimmed)) {
+        addr = parseInt(trimmed.slice(2), 16);
+    }
+    else if (/^[0-9]+$/.test(trimmed)) {
+        addr = parseInt(trimmed, 10);
+    }
+    else {
+        const resolved = resolveAddressSymbol(trimmed);
+        if (resolved === undefined) {
+            throw new ToolValidationError(`Unknown address or symbol: ${trimmed}`, { path: fieldPath });
+        }
+        addr = resolved;
+    }
+    if (!Number.isInteger(addr) || addr < 0 || addr > 0xffff) {
+        throw new ToolValidationError("Address must be in range $0000-$FFFF", { path: fieldPath });
+    }
+    return addr;
+}
+function fmtAddr(addr) {
+    return `$${addr.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function validateRangeWithinAddressSpace(start, length, fieldPath) {
+    const end = start + length - 1;
+    if (end > 0xffff) {
+        throw new ToolValidationError(`${fieldPath} range exceeds address space; ${fmtAddr(start)} + ${length} bytes would pass $FFFF.`, { path: fieldPath });
+    }
+}
+// ---------------------------------------------------------------------------
+// copy_memory
+// ---------------------------------------------------------------------------
+const copyMemoryArgsSchema = objectSchema({
+    description: "Copy a region of RAM from one address to another.",
+    properties: {
+        source: stringSchema({ description: "Source start address ($HHHH, decimal, or symbol).", minLength: 1 }),
+        dest: stringSchema({ description: "Destination start address.", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to copy (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+    },
+    required: ["source", "dest", "length"],
+    additionalProperties: false,
+});
+async function executeCopyMemory(rawArgs, ctx) {
+    try {
+        const parsed = copyMemoryArgsSchema.parse(rawArgs ?? {});
+        const src = parseAddressArg(parsed.source, "$.source");
+        const dst = parseAddressArg(parsed.dest, "$.dest");
+        const len = parsed.length;
+        validateRangeWithinAddressSpace(src, len, "$.source");
+        validateRangeWithinAddressSpace(dst, len, "$.dest");
+        ctx.logger.info("Copying memory", { src: fmtAddr(src), dst: fmtAddr(dst), len });
+        const bytes = await ctx.client.readMemoryRaw(src, len);
+        await ctx.client.writeMemoryRaw(dst, bytes);
+        return textResult(`Copied ${bytes.length} bytes from ${fmtAddr(src)} to ${fmtAddr(dst)}.`, {
+            success: true, source: fmtAddr(src), dest: fmtAddr(dst), bytesCopied: bytes.length,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// fill_memory
+// ---------------------------------------------------------------------------
+const fillMemoryArgsSchema = objectSchema({
+    description: "Fill a memory region with a repeating byte pattern.",
+    properties: {
+        address: stringSchema({ description: "Start address ($HHHH, decimal, or symbol).", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to fill (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+        pattern: stringSchema({
+            description: "Hex bytes to repeat, e.g. 'FF' or 'AA 55'. Space-separated or run together.",
+            minLength: 2,
+            pattern: /^[\s0-9A-Fa-f$]+$/,
+        }),
+    },
+    required: ["address", "length", "pattern"],
+    additionalProperties: false,
+});
+async function executeFillMemory(rawArgs, ctx) {
+    try {
+        const parsed = fillMemoryArgsSchema.parse(rawArgs ?? {});
+        const addr = parseAddressArg(parsed.address, "$.address");
+        validateRangeWithinAddressSpace(addr, parsed.length, "$.address");
+        const { bytes: patternBytes } = parseUserHex(parsed.pattern, "$.pattern");
+        if (patternBytes.length === 0)
+            throw new ToolValidationError("Pattern must not be empty", { path: "$.pattern" });
+        const buf = new Uint8Array(parsed.length);
+        for (let i = 0; i < parsed.length; i++)
+            buf[i] = patternBytes[i % patternBytes.length];
+        await ctx.client.writeMemoryRaw(addr, buf);
+        ctx.logger.info("Filled memory", { address: fmtAddr(addr), length: parsed.length, pattern: parsed.pattern });
+        return textResult(`Filled ${parsed.length} bytes at ${fmtAddr(addr)} with pattern ${parsed.pattern.trim()}.`, {
+            success: true, address: fmtAddr(addr), length: parsed.length, pattern: parsed.pattern.trim(),
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// search_memory
+// ---------------------------------------------------------------------------
+const searchMemoryArgsSchema = objectSchema({
+    description: "Search for a byte pattern within a memory range.",
+    properties: {
+        startAddress: stringSchema({ description: "Start of search range ($HHHH, decimal, or symbol).", minLength: 1 }),
+        endAddress: stringSchema({ description: "End of search range (inclusive).", minLength: 1 }),
+        pattern: stringSchema({
+            description: "Hex bytes to find, e.g. 'A9 00' for LDA #$00.",
+            minLength: 2,
+            pattern: /^[\s0-9A-Fa-f$]+$/,
+        }),
+        maxResults: optionalSchema(numberSchema({ description: "Maximum matches to return (default 10).", integer: true, minimum: 1, maximum: 100, default: 10 })),
+    },
+    required: ["startAddress", "endAddress", "pattern"],
+    additionalProperties: false,
+});
+async function executeSearchMemory(rawArgs, ctx) {
+    try {
+        const parsed = searchMemoryArgsSchema.parse(rawArgs ?? {});
+        const start = parseAddressArg(parsed.startAddress, "$.startAddress");
+        const end = parseAddressArg(parsed.endAddress, "$.endAddress");
+        if (end < start)
+            throw new ToolValidationError("endAddress must be ≥ startAddress", { path: "$.endAddress" });
+        const { bytes: needle } = parseUserHex(parsed.pattern, "$.pattern");
+        if (needle.length === 0)
+            throw new ToolValidationError("Pattern must not be empty", { path: "$.pattern" });
+        const maxResults = parsed.maxResults ?? 10;
+        const len = end - start + 1;
+        ctx.logger.info("Searching memory", { start: fmtAddr(start), end: fmtAddr(end), pattern: parsed.pattern });
+        const haystack = await ctx.client.readMemoryRaw(start, len);
+        const matches = [];
+        outer: for (let i = 0; i <= haystack.length - needle.length && matches.length < maxResults; i++) {
+            for (let j = 0; j < needle.length; j++) {
+                if (haystack[i + j] !== needle[j])
+                    continue outer;
+            }
+            matches.push(fmtAddr(start + i));
+        }
+        return jsonResult({ found: matches.length, matches, pattern: parsed.pattern.trim(), range: { start: fmtAddr(start), end: fmtAddr(end) } }, { success: true, found: matches.length });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// compare_memory
+// ---------------------------------------------------------------------------
+const compareMemoryArgsSchema = objectSchema({
+    description: "Compare two memory regions and report differing bytes.",
+    properties: {
+        address1: stringSchema({ description: "First region start address.", minLength: 1 }),
+        address2: stringSchema({ description: "Second region start address.", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to compare (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+        maxDiffs: optionalSchema(numberSchema({ description: "Max differences to report (default 10).", integer: true, minimum: 1, maximum: 200, default: 10 })),
+    },
+    required: ["address1", "address2", "length"],
+    additionalProperties: false,
+});
+async function executeCompareMemory(rawArgs, ctx) {
+    try {
+        const parsed = compareMemoryArgsSchema.parse(rawArgs ?? {});
+        const a1 = parseAddressArg(parsed.address1, "$.address1");
+        const a2 = parseAddressArg(parsed.address2, "$.address2");
+        const len = parsed.length;
+        const maxDiffs = parsed.maxDiffs ?? 10;
+        ctx.logger.info("Comparing memory regions", { a1: fmtAddr(a1), a2: fmtAddr(a2), len });
+        const [r1, r2] = await Promise.all([
+            ctx.client.readMemoryRaw(a1, len),
+            ctx.client.readMemoryRaw(a2, len),
+        ]);
+        const diffs = [];
+        for (let i = 0; i < len && diffs.length < maxDiffs; i++) {
+            if (r1[i] !== r2[i]) {
+                diffs.push({
+                    offset: i,
+                    address1: fmtAddr(a1 + i),
+                    address2: fmtAddr(a2 + i),
+                    value1: formatByte(r1[i] ?? 0),
+                    value2: formatByte(r2[i] ?? 0),
+                });
+            }
+        }
+        const identical = diffs.length === 0;
+        return jsonResult({ identical, diffCount: diffs.length, diffs, region1: fmtAddr(a1), region2: fmtAddr(a2), length: len }, { success: true, identical, diffCount: diffs.length });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// save_memory
+// ---------------------------------------------------------------------------
+const saveMemoryArgsSchema = objectSchema({
+    description: "Dump a memory region to a local file, optionally with a PRG load-address header.",
+    properties: {
+        startAddress: stringSchema({ description: "Start address of region to save.", minLength: 1 }),
+        endAddress: stringSchema({ description: "End address (inclusive).", minLength: 1 }),
+        filePath: stringSchema({ description: "Absolute or relative path for the output file.", minLength: 1 }),
+        asPrg: optionalSchema(booleanSchema({ description: "Prepend a 2-byte little-endian load-address header (PRG format). Default: true.", default: true })),
+    },
+    required: ["startAddress", "endAddress", "filePath"],
+    additionalProperties: false,
+});
+async function executeSaveMemory(rawArgs, ctx) {
+    try {
+        const parsed = saveMemoryArgsSchema.parse(rawArgs ?? {});
+        const start = parseAddressArg(parsed.startAddress, "$.startAddress");
+        const end = parseAddressArg(parsed.endAddress, "$.endAddress");
+        if (end < start)
+            throw new ToolValidationError("endAddress must be ≥ startAddress", { path: "$.endAddress" });
+        const asPrg = parsed.asPrg !== false;
+        const len = end - start + 1;
+        const resolvedPath = path.resolve(parsed.filePath);
+        ctx.logger.info("Saving memory to file", { start: fmtAddr(start), end: fmtAddr(end), filePath: resolvedPath, asPrg });
+        const bytes = await ctx.client.readMemoryRaw(start, len);
+        const header = asPrg ? Buffer.from([start & 0xff, (start >> 8) & 0xff]) : Buffer.alloc(0);
+        await fs.promises.mkdir(path.dirname(resolvedPath), { recursive: true });
+        await fs.promises.writeFile(resolvedPath, Buffer.concat([header, Buffer.from(bytes)]));
+        const fileSize = bytes.length + header.length;
+        return textResult(`Saved ${bytes.length} bytes (${fmtAddr(start)}–${fmtAddr(end)}) to ${resolvedPath}${asPrg ? " (PRG, with load address header)" : ""}.`, { success: true, filePath: resolvedPath, bytesRead: bytes.length, fileSize, asPrg, startAddress: fmtAddr(start), endAddress: fmtAddr(end) });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
 export const memoryOperationHandlers = {
     read: async (args, ctx) => executeReadMemory(stripOperationDiscriminator(args), ctx),
     write: async (args, ctx) => executeWriteMemory(stripOperationDiscriminator(args), ctx),
     read_screen: async (args, ctx) => executeReadScreen(stripOperationDiscriminator(args), ctx),
+    disassemble: async (args, ctx) => executeDisassemble(stripOperationDiscriminator(args), ctx),
+    copy_memory: async (args, ctx) => executeCopyMemory(stripOperationDiscriminator(args), ctx),
+    fill_memory: async (args, ctx) => executeFillMemory(stripOperationDiscriminator(args), ctx),
+    search_memory: async (args, ctx) => executeSearchMemory(stripOperationDiscriminator(args), ctx),
+    compare_memory: async (args, ctx) => executeCompareMemory(stripOperationDiscriminator(args), ctx),
+    save_memory: async (args, ctx) => executeSaveMemory(stripOperationDiscriminator(args), ctx),
 };
+export { disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, };
 export const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",
     supportedPlatforms: ["c64u", "vice"],
     resources: [
-        "c64://context/bootstrap",
-        "c64://specs/basic",
-        "c64://specs/assembly",
+        "c64://guide/bootstrap",
+        "c64://basic/spec",
+        "c64://assembly/6510-spec",
     ],
     prompts: ["memory-debug", "basic-program", "assembly-program"],
     defaultTags: ["memory", "debug"],
@@ -367,10 +691,10 @@ export const memoryModule = defineToolModule({
     tools: [
         {
             name: "read_screen",
-            description: "Read the current text screen (40x25) and return its ASCII representation. For PETSCII details, see c64://specs/basic.",
+            description: "Read the current text screen (40x25) and return its ASCII representation. For PETSCII details, see c64://basic/spec.",
             summary: "Fetches screen RAM, converts from PETSCII, and returns the printable output.",
             inputSchema: readScreenArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap", "c64://specs/basic"],
+            relatedResources: ["c64://guide/bootstrap", "c64://basic/spec"],
             relatedPrompts: ["memory-debug", "basic-program", "assembly-program"],
             tags: ["screen", "memory"],
             prerequisites: [],
@@ -390,10 +714,10 @@ export const memoryModule = defineToolModule({
         },
         {
             name: "read",
-            description: "Read a range of bytes from main memory and return the data as hexadecimal. Consult c64://specs/assembly and docs index.",
+            description: "Read a range of bytes from main memory and return the data as hexadecimal. Consult c64://assembly/6510-spec and docs index.",
             summary: "Resolves symbols, reads memory, and returns a hex dump with addressing metadata.",
             inputSchema: readMemoryArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
+            relatedResources: ["c64://guide/bootstrap", "c64://assembly/6510-spec", "c64://guide/index"],
             relatedPrompts: ["memory-debug", "assembly-program"],
             tags: ["memory", "hex"],
             prerequisites: [],
@@ -414,10 +738,10 @@ export const memoryModule = defineToolModule({
         },
         {
             name: "write",
-            description: "Write a hexadecimal byte sequence into main memory at the specified address. See c64://context/bootstrap for safety rules.",
+            description: "Write a hexadecimal byte sequence into main memory at the specified address. See c64://guide/bootstrap for safety rules.",
             summary: "Resolves symbols, validates hex data, and writes bytes to RAM.",
             inputSchema: writeMemoryArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
+            relatedResources: ["c64://guide/bootstrap", "c64://assembly/6510-spec", "c64://guide/index"],
             relatedPrompts: ["memory-debug", "assembly-program"],
             tags: ["memory", "hex", "write"],
             prerequisites: ["read"],

package/dist/tools/meta/index.js

@@ -28,7 +28,7 @@ const allTools = [
 export const metaModule = defineToolModule({
     domain: "meta",
     summary: "High-level meta tools that orchestrate multiple MCP actions.",
-    resources: ["c64://context/bootstrap", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://assembly/6510-spec"],
     defaultTags: ["meta", "orchestration", "experimental"],
     supportedPlatforms: ["c64u", "vice"],
     workflowHints: [

package/dist/tools/printer.js

@@ -227,13 +227,12 @@ export const printerModule = defineToolModule({
     domain: "printer",
     summary: "Printer workflow helpers for Commodore MPS and Epson FX devices, including prompt templates.",
     resources: [
-        "c64://specs/printer",
-        "c64://docs/printer/guide",
-        "c64://docs/printer/commodore-text",
-        "c64://docs/printer/commodore-bitmap",
-        "c64://docs/printer/epson-text",
-        "c64://docs/printer/epson-bitmap",
-        "c64://docs/printer/prompts",
+        "c64://printer/spec",
+        "c64://printer/commodore/text",
+        "c64://printer/commodore/bitmap",
+        "c64://printer/epson/text",
+        "c64://printer/epson/bitmap",
+        "c64://printer/prompt-guide",
     ],
     prompts: ["printer-job"],
     defaultTags: ["printer"],
@@ -244,10 +243,10 @@ export const printerModule = defineToolModule({
     tools: [
         {
             name: "print_text",
-            description: "Print text on device 4 using Commodore or Epson workflows. See c64://docs/printer/guide.",
+            description: "Print text on device 4 using Commodore or Epson workflows. See c64://printer/spec.",
             summary: "Generates printer BASIC, opens device 4, prints text, and optionally emits a form feed.",
             inputSchema: printTextArgsSchema.jsonSchema,
-            relatedResources: ["c64://docs/printer/guide", "c64://specs/printer"],
+            relatedResources: ["c64://printer/spec"],
             relatedPrompts: ["printer-job"],
             tags: ["text"],
             prerequisites: ["upload_run_basic"],
@@ -304,7 +303,7 @@ export const printerModule = defineToolModule({
             description: "Print a Commodore MPS bit-image row using BIM BASIC helpers.",
             summary: "Generates BASIC that emits Commodore BIM commands for the provided bitmap columns.",
             inputSchema: commodoreBitmapArgsSchema.jsonSchema,
-            relatedResources: ["c64://docs/printer/commodore-bitmap"],
+            relatedResources: ["c64://printer/commodore/bitmap"],
             relatedPrompts: ["printer-job"],
             tags: ["bitmap", "commodore"],
             prerequisites: ["upload_run_basic"],
@@ -364,7 +363,7 @@ export const printerModule = defineToolModule({
             description: "Print an Epson FX bit-image row using ESC/P commands.",
             summary: "Generates BASIC that emits ESC/P graphics commands for Epson printers.",
             inputSchema: epsonBitmapArgsSchema.jsonSchema,
-            relatedResources: ["c64://docs/printer/epson-bitmap"],
+            relatedResources: ["c64://printer/epson/bitmap"],
             relatedPrompts: ["printer-job"],
             tags: ["bitmap", "epson"],
             prerequisites: ["upload_run_basic"],
@@ -425,7 +424,7 @@ export const printerModule = defineToolModule({
             description: "Define custom characters on Commodore MPS printers using DLL mode.",
             summary: "Uploads custom glyph data (11 columns each) for device 4 DLL mode.",
             inputSchema: commodoreDllArgsSchema.jsonSchema,
-            relatedResources: ["c64://docs/printer/commodore-bitmap"],
+            relatedResources: ["c64://printer/commodore/bitmap"],
             relatedPrompts: ["printer-job"],
             tags: ["dll", "commodore"],
             prerequisites: ["upload_run_basic"],