c64bridge 0.9.3 → 1.0.1

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "0.9.3",
+  "version": "1.0.1",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "entry": "dist/index.js",
   "type": "stdio",
@@ -37,7 +37,7 @@
       "default": "~/.c64bridge.json"
     },
     "C64_MODE": {
-      "description": "Select active backend (c64u for Ultimate hardware, vice for emulator)",
+      "description": "Select active backend (c64u/U64 hardware, u2/U2-family cartridge, or vice emulator)",
       "default": "c64u"
     },
     "C64U_HOST": {
@@ -52,6 +52,18 @@
       "description": "Override the C64 Ultimate network password sent as X-Password",
       "default": ""
     },
+    "U2_HOST": {
+      "description": "Override the U2/U2+/U2+L host name or IP address when C64_MODE=u2",
+      "default": ""
+    },
+    "U2_PORT": {
+      "description": "Override the U2-family REST port when C64_MODE=u2",
+      "default": ""
+    },
+    "U2_PASSWORD": {
+      "description": "Override the U2-family network password sent as X-Password when C64_MODE=u2",
+      "default": ""
+    },
     "C64BRIDGE_DIAGNOSTICS_DIR": {
       "description": "Override the directory where persistent MCP diagnostics files are written",
       "default": "~/.c64bridge/diagnostics"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "0.9.3",
+  "version": "1.0.1",
   "mcpName": "io.github.chrisgleissner/c64bridge",
   "description": "C64 Bridge MCP server for Commodore 64 Ultimate hardware and VICE emulator control",
   "repository": {
@@ -38,7 +38,9 @@
     "check": "npm run build && npm test",
     "check:node-compat": "node scripts/check-node-compat.mjs",
     "build:rag": "node scripts/invoke-bun.mjs scripts/rag-rebuild.mjs",
-    "api:generate": "npx --yes swagger-typescript-api@12.0.4 -p doc/c64u/c64-openapi.yaml -o generated/c64 -n index.ts --axios --single-http-client --module-name-first-tag",
+    "api:generate": "npm run api:generate:c64u && npm run api:generate:u2",
+    "api:generate:c64u": "npx --yes swagger-typescript-api@12.0.4 -p doc/c64u/c64-openapi.yaml -o generated/openapi/c64u -n index.ts --axios --single-http-client --module-name-index 0",
+    "api:generate:u2": "npx --yes swagger-typescript-api@12.0.4 -p doc/u2/u2-openapi.yaml -o generated/openapi/u2 -n index.ts --axios --single-http-client --module-name-index 0",
     "c64:tool": "bash scripts/c64-tool.sh",
     "rag:rebuild": "node scripts/invoke-bun.mjs scripts/rag-rebuild.mjs",
     "rag:fetch": "node scripts/fetch-external-sources.mjs",

package/scripts/mockC64Server.mjs

@@ -83,12 +83,18 @@ function sendJson(res, payload = {}, statusCode = 200) {
 function createInitialState() {
   return {
     networkPassword: null,
+    forcedErrors: null,
+    forcedErrorsUrlMatch: null,
+    hangOnMachineInputProbe: false,
     lastPrg: null,
+    lastLoadedPrg: null,
+    loadCount: 0,
     runCount: 0,
     resets: 0,
     reboots: 0,
   poweroffs: 0,
     memory: new Uint8Array(0x10000),
+    heartbeat: null,
     lastWrite: null,
     writeLog: [],
     lastRequest: null,
@@ -112,6 +118,8 @@ function createInitialState() {
     lastConfigAction: null,
   menuToggleCount: 0,
   lastMenuTarget: null,
+    menuScreen: Buffer.from([0x41, 0x01, 0x42, 0x02]),
+    inputState: { keyboard: { inputs: [] }, joysticks: [{ port: 1, inputs: [] }, { port: 2, inputs: [] }] },
     streams: {
       video: { active: false, target: null, packetsSent: 0 },
       audio: { active: false, target: null, packetsSent: 0 },
@@ -154,6 +162,82 @@ function toScreenCode(char) {
   return SCREEN_CODE_LOOKUP.get(char) ?? SCREEN_CODE_LOOKUP.get(" ") ?? 0x20;
 }
 
+const KERNAL_KEYBOARD_NDX_ADDRESS = 0x00c6;
+const KERNAL_KEYBOARD_BUFFER_ADDRESS = 0x0277;
+
+const SYS_COMMAND_PATTERN = /SYS\s*\d+/i;
+const HEARTBEAT_ADDRESS = 0x0400; // Screen-RAM byte the ASM liveness poller watches.
+const HEARTBEAT_GRANULARITY_MS = 10; // Well below the poll interval so consecutive liveness reads always differ.
+const HEARTBEAT_DURATION_MS = 1000; // How long a SYS-triggered program keeps "running".
+
+/**
+ * Nothing in this mock runs 6502 code to drain the KERNAL keyboard buffer
+ * itself, so a client polling NDX ($00C6) waiting for it to return to zero
+ * would otherwise hang forever. Simulate the KERNAL's IRQ-driven drain with
+ * a short delay so injectKeyboardQueue's poll loop behaves realistically.
+ *
+ * When the queued text looks like a typed `SYSnnnnn` command (the trigger
+ * upload_run_asm uses to enter an assembled program), also record a
+ * time-computed "alive" window (consumed by readMemoryWithHeartbeat). This
+ * mock never executes 6502 code, so a liveness poller watching screen RAM
+ * would otherwise see no progression. Recording a descriptor rather than
+ * mutating memory from a background timer is deliberate: nothing advances
+ * asynchronously, so an unrelated later test that merely shares this server
+ * instance can never observe a stray screen-RAM mutation.
+ */
+function simulateKeyboardDrain(state, address) {
+  if (address !== KERNAL_KEYBOARD_NDX_ADDRESS) return;
+  const pending = state.memory[KERNAL_KEYBOARD_NDX_ADDRESS] ?? 0;
+  const queued = pending > 0
+    ? Uint8Array.from(state.memory.subarray(KERNAL_KEYBOARD_BUFFER_ADDRESS, KERNAL_KEYBOARD_BUFFER_ADDRESS + pending))
+    : null;
+  setTimeout(() => {
+    state.memory[KERNAL_KEYBOARD_NDX_ADDRESS] = 0;
+    if (!queued) return;
+    const text = Buffer.from(queued).toString("ascii");
+    if (!SYS_COMMAND_PATTERN.test(text)) return;
+    state.heartbeat = {
+      address: HEARTBEAT_ADDRESS,
+      startedAt: Date.now(),
+      durationMs: HEARTBEAT_DURATION_MS,
+      baseValue: state.memory[HEARTBEAT_ADDRESS] ?? 0,
+    };
+  }, 5);
+}
+
+/**
+ * Serve a screen-RAM read, overlaying a synthetic, monotonically advancing
+ * byte at the heartbeat address while a SYS-triggered "alive" window is open.
+ * The overlay is a pure function of elapsed time applied only to the returned
+ * copy, so it never mutates stored memory and never advances on its own.
+ */
+function readMemoryWithHeartbeat(state, address, length) {
+  const bytes = state.memory.slice(address, address + length);
+  const heartbeat = state.heartbeat;
+  if (!heartbeat) return bytes;
+  const elapsed = Date.now() - heartbeat.startedAt;
+  if (elapsed < 0 || elapsed >= heartbeat.durationMs) return bytes;
+  const offset = heartbeat.address - address;
+  if (offset < 0 || offset >= bytes.length) return bytes;
+  const ticks = Math.floor(elapsed / HEARTBEAT_GRANULARITY_MS);
+  bytes[offset] = (heartbeat.baseValue + ticks) & 0xff;
+  return bytes;
+}
+
+/**
+ * Any explicit write covering the heartbeat address means a client has taken
+ * over screen RAM, so end the simulated "alive" window and let the real stored
+ * bytes show through again. This keeps a lingering heartbeat from corrupting a
+ * later writeMemory/readMemory round-trip in a shared-server test.
+ */
+function cancelHeartbeatOnWrite(state, address, length) {
+  const heartbeat = state.heartbeat;
+  if (!heartbeat) return;
+  if (address <= heartbeat.address && heartbeat.address < address + length) {
+    state.heartbeat = null;
+  }
+}
+
 function seedReadyPrompt(state) {
   const text = "READY.";
   const buffer = new Uint8Array(text.length + 1);
@@ -273,6 +357,20 @@ export async function startMockC64Server(options = {}) {
       return;
     }
 
+    // Test hook: simulate real firmware soft-failures, which answer HTTP 200
+    // with a non-empty `errors` array rather than a non-2xx status. Consumed
+    // once so a single forced failure does not leak into later requests.
+    if (state.forcedErrors && (!state.forcedErrorsUrlMatch || url.includes(state.forcedErrorsUrlMatch))) {
+      const errors = state.forcedErrors;
+      state.forcedErrors = null;
+      state.forcedErrorsUrlMatch = null;
+      // Drain any request body so an unread upload cannot corrupt a reused
+      // keep-alive connection's framing.
+      for await (const _chunk of req) { /* discard */ }
+      sendJson(res, { result: "error", errors });
+      return;
+    }
+
     if (method === "GET" && (url === "/" || url.startsWith("/?"))) {
       sendJson(res, { status: "ok", host: "mock" });
       return;
@@ -295,7 +393,10 @@ export async function startMockC64Server(options = {}) {
           enabled: driveState.power !== "off",
           power: driveState.power,
           mode: driveState.mode,
-          image: driveState.mountedImage,
+          // 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,
         };
       }
       sendJson(res, { drives });
@@ -331,6 +432,49 @@ export async function startMockC64Server(options = {}) {
       return;
     }
 
+    if (method === "GET" && url === "/v1/machine:menu_screen") {
+      res.setHeader("Content-Type", "application/octet-stream");
+      res.end(state.menuScreen);
+      return;
+    }
+
+    if (method === "GET" && url === "/v1/machine:input") {
+      if (state.hangOnMachineInputProbe) {
+        // Test hook: never respond, to prove a caller cannot be blocked on
+        // this probe (HARD01-031). Deliberately does not call res.end().
+        return;
+      }
+      sendJson(res, state.inputState);
+      return;
+    }
+
+    if (method === "POST" && url === "/v1/machine:input") {
+      const batch = await readJson(req);
+      for (const event of batch.events ?? []) {
+        if (event.kind === "release_all") {
+          state.inputState.keyboard.inputs = [];
+          state.inputState.joysticks.forEach((joystick) => { joystick.inputs = []; });
+          continue;
+        }
+        const target = event.kind === "keyboard"
+          ? state.inputState.keyboard
+          : state.inputState.joysticks.find((joystick) => joystick.port === event.port);
+        if (!target) continue;
+        const inputs = new Set(target.inputs);
+        for (const input of event.inputs ?? []) {
+          if (event.transition === "release") inputs.delete(input);
+          else if (event.transition === "press") inputs.add(input);
+          else if (event.transition === "tap") {
+            inputs.add(input);
+            inputs.delete(input);
+          }
+        }
+        target.inputs = [...inputs];
+      }
+      sendJson(res, state.inputState);
+      return;
+    }
+
     if (method === "GET" && url === "/v1/machine:debugreg") {
       sendJson(res, { value: state.debugreg ?? "00" });
       return;
@@ -358,6 +502,27 @@ export async function startMockC64Server(options = {}) {
       return;
     }
 
+    if (method === "POST" && url === "/v1/runners:load_prg") {
+      const chunks = [];
+      for await (const chunk of req) {
+        chunks.push(chunk);
+      }
+
+      const prg = Buffer.concat(chunks);
+      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).
+      if (prg.length >= 2) {
+        const loadAddress = prg.readUInt16LE(0);
+        state.memory.set(prg.subarray(2), loadAddress);
+      }
+
+      sendJson(res, { result: "ok", bytes: prg.length });
+      return;
+    }
+
     if (url.startsWith("/v1/runners:sidplay")) {
       let routeUrl;
       try {
@@ -431,7 +596,7 @@ 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 = state.memory.slice(address, address + length);
+      const bytes = readMemoryWithHeartbeat(state, address, length);
 
       const accept = String(req.headers["accept"] || "");
       if (accept.includes("application/octet-stream")) {
@@ -466,6 +631,8 @@ export async function startMockC64Server(options = {}) {
       state.memory.set(bytes, address);
       state.lastWrite = { address, bytes };
       state.writeLog.push({ address, bytes: Buffer.from(bytes) });
+      cancelHeartbeatOnWrite(state, address, bytes.length);
+      simulateKeyboardDrain(state, address);
 
       sendJson(res, { result: "wrote", address, length: bytes.length });
       return;
@@ -485,6 +652,8 @@ export async function startMockC64Server(options = {}) {
       state.memory.set(bytes, address);
       state.lastWrite = { address, bytes };
       state.writeLog.push({ address, bytes: Buffer.from(bytes) });
+      cancelHeartbeatOnWrite(state, address, bytes.length);
+      simulateKeyboardDrain(state, address);
 
       sendJson(res, { result: "wrote", address, length: bytes.length });
       return;

package/scripts/prepare-release.mjs

@@ -26,8 +26,19 @@ const fileExists = async (relativePath) => {
 };
 
 const getRepositoryMetadata = (repository) => {
-  const url = typeof repository === 'string' ? repository : repository?.url;
-  if (!url) {
+  const rawUrl = typeof repository === 'string' ? repository : repository?.url;
+  if (!rawUrl) {
+    return undefined;
+  }
+
+  let url = rawUrl.trim();
+  if (url.startsWith('git+')) {
+    url = url.slice(4);
+  }
+  if (url.endsWith('.git')) {
+    url = url.slice(0, -4);
+  }
+  if (!/^https?:\/\//.test(url)) {
     return undefined;
   }
 

package/scripts/update-readme.ts

@@ -27,6 +27,7 @@ type ManifestEnvEntry = {
 type EnvCategory =
   | "Server Runtime"
   | "C64 Ultimate"
+  | "U2-family"
   | "VICE Runtime"
   | "VICE Audio Capture"
   | "SID Playback"
@@ -55,6 +56,9 @@ function classifyEnvVariable(name: string): EnvCategory {
   if (name.startsWith("C64U_")) {
     return "C64 Ultimate";
   }
+  if (name.startsWith("U2_")) {
+    return "U2-family";
+  }
   if (name.startsWith("VICE_") || name === "FORCE_XVFB" || name === "DISABLE_XVFB") {
     if (name === "VICE_MODE" || name === "VICE_LIMIT_CYCLES" || name === "VICE_RUN_TIMEOUT_MS") {
       return "VICE Audio Capture";
@@ -79,6 +83,9 @@ function resolveJsonConfigKey(name: string): string {
     C64U_HOST: "c64u.host",
     C64U_PORT: "c64u.port",
     C64U_PASSWORD: "c64u.networkPassword",
+    U2_HOST: "u2.host",
+    U2_PORT: "u2.port",
+    U2_PASSWORD: "u2.networkPassword",
     VICE_BINARY: "vice.exe",
     VICE_DIRECTORY: "vice.directory",
     VICE_HOST: "vice.host",
@@ -104,6 +111,7 @@ export function renderEnvironmentSection(envEntries: Readonly<Record<string, Man
   const orderedCategories: readonly EnvCategory[] = [
     "Server Runtime",
     "C64 Ultimate",
+    "U2-family",
     "VICE Runtime",
     "VICE Audio Capture",
     "SID Playback",
@@ -145,7 +153,6 @@ type GroupedOperation = {
   readonly required: readonly string[];
   readonly optional: readonly string[];
   readonly properties: Readonly<Record<string, JsonSchema | undefined>>;
-  readonly notes: readonly string[];
 };
 
 type GroupedToolInfo = {
@@ -168,6 +175,11 @@ function toTableValue(values: readonly string[]): string {
   return values.join(", ");
 }
 
+function withVerificationNote(description: string, properties: Readonly<Record<string, JsonSchema | undefined>>): string {
+  const supportsVerification = Object.keys(properties).some((name) => name.toLowerCase().startsWith("verify"));
+  return supportsVerification ? `${description} Supports verification.` : description;
+}
+
 function formatInputName(name: string, schema?: JsonSchema): string {
   const defaultSuffix = schema && Object.prototype.hasOwnProperty.call(schema, "default")
     ? `=${JSON.stringify(schema.default)}`
@@ -229,21 +241,12 @@ function collectFromOperationMetadata(schema: JsonSchema): readonly GroupedOpera
       ? entry.optional.filter((name): name is string => typeof name === "string" && name !== "op")
       : Object.keys(properties).filter((name) => name !== "op" && !requiredProps.includes(name));
 
-    const notes: string[] = [];
-    const hasVerificationProperty = Object.keys(properties).some((name) =>
-      name.toLowerCase().startsWith("verify"),
-    );
-    if (hasVerificationProperty) {
-      notes.push("supports verify");
-    }
-
     operations.push({
       op: opName,
-      description: getString(entry.description, `Operation ${opName}`),
+      description: withVerificationNote(getString(entry.description, `Operation ${opName}`), properties),
       required: requiredProps,
       optional: optionalProps,
       properties,
-      notes,
     });
   }
 
@@ -282,21 +285,12 @@ function collectFromVariantList(variants: readonly JsonSchema[]): readonly Group
     const description = getString(typedVariant.description, getString(opSchema?.description, `Operation ${opName}`));
     const requiredProps = ((typedVariant.required as readonly string[] | undefined) ?? []).filter((name) => name !== "op");
 
-    const notes: string[] = [];
-    const hasVerificationProperty = Object.keys(properties).some((name) =>
-      name.toLowerCase().startsWith("verify"),
-    );
-    if (hasVerificationProperty) {
-      notes.push("supports verify");
-    }
-
     operations.push({
       op: opName,
-      description,
+      description: withVerificationNote(description, properties),
       required: requiredProps,
       optional: Object.keys(properties).filter((name) => name !== "op" && !requiredProps.includes(name)),
       properties,
-      notes,
     });
   }
 
@@ -321,18 +315,12 @@ function collectFromFlattenedSchema(schema: JsonSchema): readonly GroupedOperati
   }
 
   const descriptionMap = parseOperationDescriptions(getString(schema.description));
-  const hasVerificationProperty = Object.keys(properties).some((name) =>
-    name !== "op" && name.toLowerCase().startsWith("verify"),
-  );
-  const notes = hasVerificationProperty ? ["supports verify"] : [];
-
   return opNames.map((opName) => ({
     op: opName,
-    description: descriptionMap.get(opName) ?? `Operation ${opName}`,
+    description: withVerificationNote(descriptionMap.get(opName) ?? `Operation ${opName}`, properties),
     required: [] as readonly string[],
     optional: Object.keys(properties).filter((name) => name !== "op"),
     properties,
-    notes,
   }));
 }
 
@@ -391,13 +379,13 @@ export function renderToolsSection(modules: readonly ToolModuleDescriptor[] = de
               escapeCell(operation.description),
               escapeCell(formatInputs(operation.required, operation.properties)),
               escapeCell(formatInputs(operation.optional, operation.properties)),
-              operation.notes.length ? escapeCell(operation.notes.join(", ")) : "—",
               effectivePlatforms.includes("c64u") ? "✅" : "",
+              effectivePlatforms.includes("u2") ? "✅" : "",
               effectivePlatforms.includes("vice") ? "✅" : "",
             ];
           });
 
-        lines.push(renderTable(["Operation", "Description", "Required Inputs", "Optional Inputs", "Notes", "C64U", "VICE"], operationRows));
+        lines.push(renderTable(["Operation", "Description", "Required Inputs", "Optional Inputs", "C64U", "U2", "VICE"], operationRows));
       }
 
       lines.push("");

package/server.json

@@ -4,16 +4,16 @@
   "title": "C64 Bridge",
   "description": "MCP server for Commodore 64 Ultimate hardware and VICE emulator control.",
   "repository": {
-    "url": "git+https://github.com/chrisgleissner/c64bridge.git",
+    "url": "https://github.com/chrisgleissner/c64bridge",
     "source": "github"
   },
   "websiteUrl": "https://github.com/chrisgleissner/c64bridge",
-  "version": "0.9.3",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "c64bridge",
-      "version": "0.9.3",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
       },