c64bridge 1.0.4 → 1.0.6

package/mcp/tools.json

@@ -66,7 +66,7 @@
                     "properties": {
                       "type": {
                         "type": "string",
-                        "description": "Assertion type",
+                        "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                         "enum": [
                           "screen_contains",
                           "memory_equals",
@@ -468,7 +468,7 @@
                           "properties": {
                             "type": {
                               "type": "string",
-                              "description": "Assertion type",
+                              "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                               "enum": [
                                 "screen_contains",
                                 "memory_equals",
@@ -2872,8 +2872,9 @@
           },
           "name": {
             "type": "string",
-            "description": "Unique task name",
-            "minLength": 1
+            "description": "Unique task name (letters, digits, spaces, '_', '-', '.'; must not start with '.' or a space).",
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_. -]*$"
           },
           "operation": {
             "type": "string",
@@ -3114,8 +3115,9 @@
               "properties": {
                 "name": {
                   "type": "string",
-                  "description": "Unique task name",
-                  "minLength": 1
+                  "description": "Unique task name (letters, digits, spaces, '_', '-', '.'; must not start with '.' or a space).",
+                  "minLength": 1,
+                  "pattern": "^[A-Za-z0-9_][A-Za-z0-9_. -]*$"
                 },
                 "operation": {
                   "type": "string",
@@ -4481,7 +4483,7 @@
               "integer",
               "null"
             ],
-            "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+            "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
             "minimum": 1,
             "maximum": 255
           },
@@ -4783,7 +4785,7 @@
                     "integer",
                     "null"
                   ],
-                  "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+                  "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
                   "minimum": 1,
                   "maximum": 255
                 },
@@ -4947,6 +4949,10 @@
           "vice"
         ],
         "operationPlatforms": {
+          "unmount": [
+            "c64u",
+            "u2"
+          ],
           "file_info": [
             "c64u",
             "u2"
@@ -8073,7 +8079,7 @@
           },
           "name": {
             "type": "string",
-            "description": "VICE resource name (example: SidEngine, C64Model).",
+            "description": "VICE resource name (example: SidEngine, SidModel).",
             "minLength": 1,
             "maxLength": 64,
             "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -8108,7 +8114,7 @@
                 },
                 "name": {
                   "type": "string",
-                  "description": "VICE resource name (example: SidEngine, C64Model).",
+                  "description": "VICE resource name (example: SidEngine, SidModel).",
                   "minLength": 1,
                   "maxLength": 64,
                   "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -8138,7 +8144,7 @@
                 },
                 "name": {
                   "type": "string",
-                  "description": "VICE resource name (example: SidEngine, C64Model).",
+                  "description": "VICE resource name (example: SidEngine, SidModel).",
                   "minLength": 1,
                   "maxLength": 64,
                   "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -8390,7 +8396,7 @@
         "required": [
           "op"
         ],
-        "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
+        "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
         "additionalProperties": false,
         "x-c64bridge-operations": [
           {
@@ -8486,7 +8492,7 @@
           },
           {
             "op": "joystick",
-            "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+            "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
             "required": [
               "port",
               "controls",
@@ -8497,7 +8503,7 @@
             ],
             "inputSchema": {
               "type": "object",
-              "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+              "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
               "properties": {
                 "op": {
                   "const": "joystick"

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "entry": "dist/index.js",
   "type": "stdio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "mcpName": "io.github.chrisgleissner/c64bridge",
   "description": "C64 Bridge MCP server for Commodore 64 Ultimate hardware and VICE emulator control",
   "repository": {

package/scripts/mockC64Server.mjs

@@ -250,6 +250,14 @@ function cancelHeartbeatOnWrite(state, address, length) {
 }
 
 function seedReadyPrompt(state) {
+  // After a reset the KERNAL clears screen RAM to spaces and BASIC sets up an
+  // empty program: TXTTAB=$0801, VARTAB/ARYTAB/STREND=$0803, FRETOP/MEMSIZ=$A000
+  // (as read from an Ultimate 64 after machine:reset).
+  state.memory.fill(toScreenCode(" "), 0x0400, 0x0400 + 1000);
+  state.memory.set([0x01, 0x08, 0x03, 0x08, 0x03, 0x08, 0x03, 0x08, 0x00, 0xa0], 0x2b);
+  state.memory.set([0x00, 0xa0], 0x37);
+  state.memory.set([0x00, 0x00], 0x0801);
+
   const text = "READY.";
   const buffer = new Uint8Array(text.length + 1);
   for (let i = 0; i < text.length; i += 1) {
@@ -259,6 +267,26 @@ function seedReadyPrompt(state) {
   state.memory.set(buffer, 0x0400);
 }
 
+/**
+ * BASIC LINKPRG ($A533): walk the line chain from $0801 and rewrite each link
+ * pointer to the byte after the line's terminating zero. Stops at a zero link
+ * high byte, as the ROM does; the step limit only guards the mock.
+ */
+function relinkBasicProgram(memory) {
+  let line = 0x0801;
+  for (let steps = 0; steps < 0x10000 && line < 0xfffb; steps += 1) {
+    if (memory[line + 1] === 0) return;
+    let y = 4;
+    do {
+      y += 1;
+    } while (line + y < 0xffff && memory[line + y] !== 0);
+    const next = line + y + 1;
+    memory[line] = next & 0xff;
+    memory[line + 1] = (next >> 8) & 0xff;
+    line = next;
+  }
+}
+
 export async function startMockC64Server(options = {}) {
   const state = createInitialState();
   const streamRuntime = createStreamRuntime();
@@ -269,9 +297,14 @@ export async function startMockC64Server(options = {}) {
   // seed memory with READY prompt at $0400 using screen codes
   seedReadyPrompt(state);
 
+  // Firmware drive ids (route_drives.h DriveToSubsys): a and b are the
+  // emulated drives, softiec the IEC file system; anything else is rejected.
+  const FIRMWARE_DRIVE_BUS_IDS = { a: 8, b: 9, softiec: 11 };
+
   function ensureDriveState(id) {
     if (!state.drives[id]) {
       state.drives[id] = {
+        busId: FIRMWARE_DRIVE_BUS_IDS[id] ?? null,
         mountedImage: null,
         mode: "1541",
         power: "off",
@@ -282,14 +315,20 @@ export async function startMockC64Server(options = {}) {
     return state.drives[id];
   }
 
-  ensureDriveState("drive8");
+  function seedDrives() {
+    ensureDriveState("a");
+    ensureDriveState("b");
+    ensureDriveState("softiec");
+  }
+
+  seedDrives();
 
   function resetState() {
     stopAllStreams();
     const fresh = createInitialState();
     Object.assign(state, fresh);
     seedReadyPrompt(state);
-    ensureDriveState("drive8");
+    seedDrives();
   }
 
   function stopAllStreams() {
@@ -401,18 +440,32 @@ export async function startMockC64Server(options = {}) {
     }
 
     if (method === "GET" && url === "/v1/drives") {
-      const drives = {};
-      for (const [driveId, driveState] of Object.entries(state.drives)) {
-        drives[driveId] = {
-          enabled: driveState.power !== "off",
-          power: driveState.power,
-          mode: driveState.mode,
-          // Mirror the real firmware's DriveInfo shape (image_path is a
-          // plain string), not the internal mount-params object.
-          image_path: driveState.mountedImage?.image ?? null,
-          type: driveState.mountedImage?.type ?? driveState.mode ?? null,
+      // Firmware shape (route_drives.cc drive_info, IecInterface::info): a list
+      // of single-key objects. Power is `enabled`; the mounted image is split
+      // into its directory (image_path) and file name (image_file). The soft
+      // IEC drive is listed as "IEC Drive" although its route id is softiec,
+      // and the printer is listed but is not a drive.
+      const splitImage = (image) => {
+        if (!image) return { image_file: "", image_path: "" };
+        const slash = image.lastIndexOf("/");
+        return { image_file: image.slice(slash + 1), image_path: slash > 0 ? image.slice(0, slash) : "/" };
+      };
+      const drives = ["a", "b"].map((driveId) => {
+        const driveState = state.drives[driveId];
+        return {
+          [driveId]: {
+            enabled: driveState.power !== "off",
+            bus_id: driveState.busId,
+            type: driveState.mode,
+            rom: `${driveState.mode}.rom`,
+            ...splitImage(driveState.mountedImage?.image),
+          },
         };
-      }
+      });
+      drives.push(
+        { "IEC Drive": { bus_id: state.drives.softiec.busId, enabled: state.drives.softiec.power !== "off", type: "DOS emulation", last_error: "00, OK, 00, 00", partitions: [{ id: 1, path: "/Temp/" }] } },
+        { "Printer Emulation": { bus_id: 4, enabled: false } },
+      );
       sendJson(res, { drives });
       return;
     }
@@ -526,11 +579,20 @@ export async function startMockC64Server(options = {}) {
       state.lastLoadedPrg = prg;
       state.loadCount += 1;
 
-      // Mirror real firmware: place the PRG body at its embedded load
-      // address without starting it (no RUN, no BASIC pointer changes).
+      // Mirror Ultimate 64 firmware 3.15: the PRG body is placed at its
+      // embedded load address without starting it, and, as after a BASIC
+      // LOAD, VARTAB/ARYTAB/STREND are set to the end address and the BASIC
+      // program at $0801 is relinked (which rewrites raw code at $0801).
       if (prg.length >= 2) {
         const loadAddress = prg.readUInt16LE(0);
-        state.memory.set(prg.subarray(2), loadAddress);
+        const body = prg.subarray(2);
+        state.memory.set(body.subarray(0, 0x10000 - loadAddress), loadAddress);
+        const endAddress = Math.min(0xffff, loadAddress + body.length);
+        for (const pointer of [0x2d, 0x2f, 0x31]) {
+          state.memory[pointer] = endAddress & 0xff;
+          state.memory[pointer + 1] = endAddress >> 8;
+        }
+        relinkBasicProgram(state.memory);
       }
 
       sendJson(res, { result: "ok", bytes: prg.length });
@@ -564,9 +626,22 @@ export async function startMockC64Server(options = {}) {
           }
 
           const attachment = Buffer.concat(chunks);
+          // Like the firmware, a multipart upload is a list of files in part
+          // order: the SID first, optional song lengths second. A text field
+          // (for example a JSON-serialised Buffer) is not a SID upload.
+          const contentType = String(req.headers["content-type"] ?? "");
+          const files = contentType.startsWith("multipart/form-data")
+            ? [...(await new Response(attachment, { headers: { "content-type": contentType } }).formData()).values()]
+            : null;
+          if (files && (files.length === 0 || files.some((part) => typeof part === "string"))) {
+            sendJson(res, { errors: ["Upload of file failed."] }, 400);
+            return;
+          }
+          const sid = files ? Buffer.from(await files[0].arrayBuffer()) : attachment;
+          const songlengths = files?.[1] ? Buffer.from(await files[1].arrayBuffer()) : null;
           state.sidAttachmentCount += 1;
-          state.lastSidAttachment = { songnr, bytes: attachment.length };
-          sendJson(res, { result: "sidplay_attachment", bytes: attachment.length, songnr });
+          state.lastSidAttachment = { songnr, bytes: sid.length, sid, songlengths };
+          sendJson(res, { result: "sidplay_attachment", bytes: sid.length, songnr });
           return;
         }
       }
@@ -610,7 +685,21 @@ export async function startMockC64Server(options = {}) {
       const lengthValue = routeUrl.searchParams.get("length") ?? "256";
       const address = parseNumeric(addressValue);
       const length = Math.max(0, parseNumeric(lengthValue, 10));
-      const bytes = readMemoryWithHeartbeat(state, address, length);
+      // Same checks as the firmware (route_machine.cc readmem).
+      if (length < 1 || length > 65536) {
+        sendJson(res, { errors: ["Invalid length"] }, 400);
+        return;
+      }
+      if (address + length > 65536) {
+        sendJson(res, { errors: ["Memory read exceeds location $FFFF"] }, 400);
+        return;
+      }
+      const bytes = Uint8Array.from(readMemoryWithHeartbeat(state, address, length));
+      // SID registers $D400-$D418 are write-only; the Ultimate 64 reads them as $00.
+      for (let i = 0; i < bytes.length; i += 1) {
+        const target = address + i;
+        if (target >= 0xd400 && target <= 0xd418) bytes[i] = 0;
+      }
 
       const accept = String(req.headers["accept"] || "");
       if (accept.includes("application/octet-stream")) {
@@ -816,8 +905,12 @@ export async function startMockC64Server(options = {}) {
       if (routeUrl) {
         const match = /^\/v1\/drives\/([^:]+):(mount|remove|reset|on|off|load_rom|set_mode)$/.exec(routeUrl.pathname);
         if (match) {
-          const driveId = decodeURIComponent(match[1]);
+          const driveId = decodeURIComponent(match[1]).toLowerCase();
           const action = match[2];
+          if (!Object.hasOwn(FIRMWARE_DRIVE_BUS_IDS, driveId)) {
+            sendJson(res, { errors: [`Invalid Drive '${decodeURIComponent(match[1])}'`] }, 400);
+            return;
+          }
           const driveState = ensureDriveState(driveId);
 
           const respond = (payload) => {

package/scripts/run-coverage.mjs

@@ -98,7 +98,10 @@ export async function main() {
     legOutputs.push(legPath);
   }
 
-  const finalReport = mergeReports(await Promise.all(legOutputs.map(readReport)));
+  const finalReport = await dropNonCodeLines(
+    mergeReports(await Promise.all(legOutputs.map(readReport))),
+    (relativePath) => fs.readFile(path.join(repoRoot, relativePath), "utf8"),
+  );
   const finalPath = path.join(coverageDir, "lcov.info");
   await fs.writeFile(finalPath, serializeReport(finalReport), "utf8");
 
@@ -265,6 +268,33 @@ function parseReport(text) {
   return report;
 }
 
+/**
+ * Bun's LCOV output lists blank and comment-only lines inside executed
+ * functions as executable lines that were never hit. Drop them, using each
+ * file's source, so coverage counts only code.
+ */
+export async function dropNonCodeLines(report, readSource) {
+  const result = new Map();
+  for (const [filePath, record] of report.entries()) {
+    let sourceLines;
+    try {
+      sourceLines = (await readSource(filePath)).split(/\r?\n/);
+    } catch {
+      result.set(filePath, record);
+      continue;
+    }
+    const lines = new Map();
+    for (const [lineNo, hits] of record.lines.entries()) {
+      const text = (sourceLines[lineNo - 1] ?? "").trim();
+      const isComment = text.startsWith("//") || text.startsWith("/*") || text.startsWith("*");
+      if (text === "" || isComment) continue;
+      lines.set(lineNo, hits);
+    }
+    result.set(filePath, { ...record, lines });
+  }
+  return result;
+}
+
 function mergeReports(reports) {
   const merged = new Map();
   for (const report of reports) {

package/scripts/update-readme.ts

@@ -485,8 +485,9 @@ export async function updateReadme(): Promise<boolean> {
   const generatedDocs = `\n\n${buildDocumentation()}\n\n`;
   const generatedEnv = `\n\n${buildEnvironmentDocumentation()}\n\n`;
   const nextReadme = readme
-    .replace(docsPattern, `${START_MARKER}${generatedDocs}${END_MARKER}`)
-    .replace(envPattern, `${ENV_START_MARKER}${generatedEnv}${ENV_END_MARKER}`);
+    // Replacement functions, not strings: generated text such as "$1E" must not be read as "$1".
+    .replace(docsPattern, () => `${START_MARKER}${generatedDocs}${END_MARKER}`)
+    .replace(envPattern, () => `${ENV_START_MARKER}${generatedEnv}${ENV_END_MARKER}`);
 
   if (nextReadme === readme) {
     return false;

package/server.json

@@ -8,12 +8,12 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/chrisgleissner/c64bridge",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "c64bridge",
-      "version": "1.0.4",
+      "version": "1.0.6",
       "transport": {
         "type": "stdio"
       },