c64bridge 0.7.4 → 0.8.0

package/scripts/generate-mcp-interface.ts

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { accessSync, constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import {
+  LATEST_PROTOCOL_VERSION,
+  ListPromptsResultSchema,
+  ListResourcesResultSchema,
+  ListToolsResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { startMockC64Server } from "./mockC64Server.mjs";
+import { getMcpProjectMetadata } from "../src/mcp/metadata.js";
+
+type JsonObject = Record<string, unknown>;
+
+interface ToolDescriptorLike {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+  readonly metadata?: {
+    readonly examples?: readonly {
+      readonly name?: string;
+      readonly description?: string;
+      readonly arguments?: Record<string, unknown>;
+    }[];
+  };
+}
+
+interface GenerateOptions {
+  readonly outputDir?: string;
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+const DEFAULT_OUTPUT_DIR = path.join(PROJECT_ROOT, "mcp");
+
+function fileExists(filePath: string): boolean {
+  try {
+    accessSync(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveBunExecutable(): string {
+  if (typeof Bun !== "undefined") {
+    return process.execPath;
+  }
+  const candidates = [
+    process.env.BUN_BIN,
+    process.env.C64BRIDGE_TEST_BUN_BIN,
+    process.env.C64BRIDGE_BUN_BIN,
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && candidate.trim().length > 0) {
+      return candidate.trim();
+    }
+  }
+
+  return "bun";
+}
+
+function resolveNodeExecutable(): string {
+  const candidates = [
+    process.env.C64BRIDGE_TEST_NODE_BIN,
+    process.env.C64BRIDGE_NODE_BIN,
+    process.env.NODE_BINARY,
+    process.env.NODE_EXEC_PATH,
+    process.env.npm_node_execpath,
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && candidate.trim().length > 0) {
+      return candidate.trim();
+    }
+  }
+
+  return typeof Bun !== "undefined" ? "node" : process.execPath;
+}
+
+function resolveServerProcess(): { command: string; args: string[] } {
+  const sourceEntrypoint = path.join(PROJECT_ROOT, "src", "mcp-server.ts");
+  const distEntrypoint = path.join(PROJECT_ROOT, "dist", "mcp-server.js");
+
+  if (typeof Bun !== "undefined" && fileExists(sourceEntrypoint)) {
+    return { command: process.execPath, args: [sourceEntrypoint] };
+  }
+
+  if (fileExists(distEntrypoint)) {
+    return { command: resolveNodeExecutable(), args: [distEntrypoint] };
+  }
+
+  if (fileExists(sourceEntrypoint)) {
+    return { command: resolveBunExecutable(), args: [sourceEntrypoint] };
+  }
+
+  throw new Error("Unable to locate MCP server entry point (src/mcp-server.ts or dist/mcp-server.js).");
+}
+
+function json(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, json(value), "utf8");
+}
+
+function sanitizeFilename(input: string): string {
+  return input.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+
+function buildProtocolExamples(tools: readonly ToolDescriptorLike[]) {
+  const selectedTool = tools.find((tool) => Array.isArray(tool.metadata?.examples) && tool.metadata.examples.length > 0)
+    ?? tools[0];
+  const selectedExample = selectedTool?.metadata?.examples?.[0];
+
+  return {
+    protocolVersion: LATEST_PROTOCOL_VERSION,
+    examples: {
+      initialize: {
+        description: "Client initialization request sent immediately after connecting to the stdio MCP server.",
+        request: {
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: LATEST_PROTOCOL_VERSION,
+            capabilities: {
+              resources: {},
+              tools: {},
+              prompts: {},
+            },
+            clientInfo: {
+              name: "c64bridge-static-interface-generator",
+              version: "1.0.0",
+            },
+          },
+        },
+      },
+      "tools/list": {
+        description: "Enumerates the full tool catalog and input schemas exposed by the server.",
+        request: {
+          jsonrpc: "2.0",
+          id: 2,
+          method: "tools/list",
+          params: {},
+        },
+      },
+      "tools/call": {
+        description: selectedExample?.description
+          ?? `Invokes the ${selectedTool?.name ?? "tool"} tool with deterministic example arguments.`,
+        request: {
+          jsonrpc: "2.0",
+          id: 3,
+          method: "tools/call",
+          params: {
+            name: selectedTool?.name ?? "c64_program",
+            arguments: selectedExample?.arguments ?? {},
+          },
+        },
+      },
+    },
+  };
+}
+
+async function discoverMcpInterface() {
+  const mockServer = await startMockC64Server();
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "c64bridge-mcp-interface-"));
+  const configPath = path.join(tempDir, "config.json");
+  const serverProcess = resolveServerProcess();
+  const mockUrl = new URL(mockServer.baseUrl);
+  const configPayload = {
+    c64u: {
+      host: mockUrl.hostname,
+      port: mockUrl.port ? Number(mockUrl.port) : 80,
+    },
+  };
+
+  await writeFile(configPath, json(configPayload), "utf8");
+
+  const transport = new StdioClientTransport({
+    command: serverProcess.command,
+    args: serverProcess.args,
+    cwd: PROJECT_ROOT,
+    env: {
+      ...process.env,
+      NODE_ENV: "test",
+      LOG_LEVEL: "error",
+      C64_TEST_TARGET: "mock",
+      C64BRIDGE_CONFIG: configPath,
+    },
+    stderr: "pipe",
+  });
+
+  const client = new Client(
+    { name: "c64bridge-static-interface-generator", version: "1.0.0" },
+    {
+      capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+      },
+    },
+  );
+
+  try {
+    await client.connect(transport);
+
+    const toolsList = await client.request({ method: "tools/list", params: {} }, ListToolsResultSchema);
+    const resourcesList = await client.request({ method: "resources/list", params: {} }, ListResourcesResultSchema);
+    const promptsList = await client.request({ method: "prompts/list", params: {} }, ListPromptsResultSchema);
+
+    return {
+      serverInfo: client.getServerVersion(),
+      capabilities: client.getServerCapabilities(),
+      toolsList,
+      resourcesList,
+      promptsList,
+    };
+  } finally {
+    await client.close().catch(() => undefined);
+    await mockServer.close().catch(() => undefined);
+    await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+export async function generateMcpInterface(options: GenerateOptions = {}): Promise<void> {
+  const outputDir = options.outputDir ? path.resolve(options.outputDir) : DEFAULT_OUTPUT_DIR;
+  const schemasDir = path.join(outputDir, "schemas");
+  const snapshot = await discoverMcpInterface();
+  const projectMetadata = getMcpProjectMetadata();
+
+  await rm(outputDir, { recursive: true, force: true });
+  await mkdir(schemasDir, { recursive: true });
+
+  const serverJson: JsonObject = {
+    name: snapshot.serverInfo?.name ?? projectMetadata.name,
+    version: snapshot.serverInfo?.version ?? projectMetadata.version,
+    description: projectMetadata.description,
+    transports: [...projectMetadata.transports],
+    capabilities: snapshot.capabilities ?? {},
+  };
+
+  if (projectMetadata.repository) {
+    serverJson.repository = projectMetadata.repository;
+  }
+  if (projectMetadata.license) {
+    serverJson.license = projectMetadata.license;
+  }
+
+  await writeJsonFile(path.join(outputDir, "server.json"), serverJson);
+  await writeJsonFile(path.join(outputDir, "tools.json"), snapshot.toolsList);
+  await writeJsonFile(path.join(outputDir, "resources.json"), snapshot.resourcesList);
+  await writeJsonFile(path.join(outputDir, "prompts.json"), snapshot.promptsList);
+  await writeJsonFile(
+    path.join(outputDir, "protocol-examples.json"),
+    buildProtocolExamples((snapshot.toolsList.tools ?? []) as readonly ToolDescriptorLike[]),
+  );
+
+  for (const tool of snapshot.toolsList.tools ?? []) {
+    if (tool.inputSchema === undefined) {
+      continue;
+    }
+    await writeJsonFile(
+      path.join(schemasDir, `${sanitizeFilename(tool.name)}.schema.json`),
+      tool.inputSchema,
+    );
+  }
+}
+
+async function main(): Promise<void> {
+  await generateMcpInterface();
+}
+
+if (import.meta.main) {
+  await main().catch((error) => {
+    console.error("[generate-mcp-interface] Failed:", error);
+    process.exitCode = 1;
+  });
+}

package/scripts/invoke-bun.mjs

@@ -3,13 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
-
-if (process.argv.length < 3) {
-  console.error("Usage: node scripts/invoke-bun.mjs <command> [args...]");
-  process.exit(1);
-}
-
-const bunArgs = process.argv.slice(2);
+import { fileURLToPath } from "node:url";
 
 function resolveBunExecutable() {
   const candidates = [
@@ -41,18 +35,70 @@ function resolveBunExecutable() {
   return "bun";
 }
 
-const bunExecutable = resolveBunExecutable();
-const child = spawn(bunExecutable, bunArgs, {
-  stdio: "inherit",
-  env: {
-    ...process.env,
-  },
-});
-
-child.on("exit", (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
+const BUN_SUBCOMMANDS = new Set([
+  "test",
+  "run",
+  "x",
+  "install",
+  "add",
+  "remove",
+  "update",
+  "pm",
+  "build",
+  "create",
+  "exec",
+  "repl",
+  "help",
+]);
+
+function looksLikeScriptPath(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && !value.startsWith("-")
+    && /\.(?:[cm]?[jt]s|tsx?)$/i.test(value);
+}
+
+export function buildBunArgs(args) {
+  const [firstArg, ...rest] = args;
+  if (!firstArg) {
+    return [];
+  }
+
+  if (BUN_SUBCOMMANDS.has(firstArg) || !looksLikeScriptPath(firstArg)) {
+    return args;
   }
-  process.exit(code ?? 1);
-});
+
+  return ["run", firstArg, ...rest];
+}
+
+function isMainModule(moduleUrl) {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+  return fileURLToPath(moduleUrl) === path.resolve(entry);
+}
+
+if (isMainModule(import.meta.url)) {
+  if (process.argv.length < 3) {
+    console.error("Usage: node scripts/invoke-bun.mjs <command> [args...]");
+    process.exit(1);
+  }
+
+  const rawArgs = process.argv.slice(2);
+  const bunExecutable = resolveBunExecutable();
+  const child = spawn(bunExecutable, buildBunArgs(rawArgs), {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+    },
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}

package/scripts/mockC64Server.mjs

@@ -1,7 +1,15 @@
 import { createServer } from "node:http";
+import dgram from "node:dgram";
 import { once } from "node:events";
 import { Buffer } from "node:buffer";
-import { getChargenGlyphs } from "../dist/chargen.js";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const moduleDir = new URL(".", import.meta.url);
+const distUrl = new URL("../dist/chargen.js", moduleDir);
+const srcUrl = new URL("../src/chargen.js", moduleDir);
+const chargenModuleUrl = existsSync(fileURLToPath(distUrl)) ? distUrl : srcUrl;
+const { getChargenGlyphs } = await import(chargenModuleUrl.href);
 
 function parseNumeric(value, defaultRadix = 16) {
   if (!value) {
@@ -82,6 +90,7 @@ function createInitialState() {
   poweroffs: 0,
     memory: new Uint8Array(0x10000),
     lastWrite: null,
+    writeLog: [],
     lastRequest: null,
     drives: {},
     lastDriveOperation: null,
@@ -104,11 +113,20 @@ function createInitialState() {
   menuToggleCount: 0,
   lastMenuTarget: null,
     streams: {
-      video: { active: false, target: null },
-      audio: { active: false, target: null },
-      debug: { active: false, target: null },
+      video: { active: false, target: null, packetsSent: 0 },
+      audio: { active: false, target: null, packetsSent: 0 },
+      debug: { active: false, target: null, packetsSent: 0 },
     },
     lastStreamAction: null,
+    streamActionLog: [],
+  };
+}
+
+function createStreamRuntime() {
+  return {
+    video: { interval: null, socket: null, sequence: 0, frameNumber: 0, sampleIndex: 0 },
+    audio: { interval: null, socket: null, sequence: 0, frameNumber: 0, sampleIndex: 0 },
+    debug: { interval: null, socket: null, sequence: 0, frameNumber: 0, sampleIndex: 0 },
   };
 }
 
@@ -148,6 +166,7 @@ function seedReadyPrompt(state) {
 
 export async function startMockC64Server(options = {}) {
   const state = createInitialState();
+  const streamRuntime = createStreamRuntime();
   state.networkPassword = typeof options.networkPassword === "string" && options.networkPassword.trim()
     ? options.networkPassword
     : null;
@@ -171,12 +190,72 @@ export async function startMockC64Server(options = {}) {
   ensureDriveState("drive8");
 
   function resetState() {
+    stopAllStreams();
     const fresh = createInitialState();
     Object.assign(state, fresh);
     seedReadyPrompt(state);
     ensureDriveState("drive8");
   }
 
+  function stopAllStreams() {
+    for (const stream of Object.keys(streamRuntime)) {
+      stopStreamEmitter(stream);
+    }
+  }
+
+  function stopStreamEmitter(stream) {
+    const runtime = streamRuntime[stream];
+    if (!runtime) {
+      return;
+    }
+    if (runtime.interval) {
+      clearInterval(runtime.interval);
+      runtime.interval = null;
+    }
+    if (runtime.socket) {
+      runtime.socket.close();
+      runtime.socket = null;
+    }
+  }
+
+  function startStreamEmitter(stream, target) {
+    stopStreamEmitter(stream);
+    if (!target || (stream !== "video" && stream !== "audio")) {
+      return;
+    }
+
+    const runtime = streamRuntime[stream];
+    const { host, port } = parseStreamTarget(target, stream === "video" ? 11000 : 11001);
+    const socket = dgram.createSocket("udp4");
+    runtime.socket = socket;
+
+    if (stream === "video") {
+      const sendFrame = () => {
+        const packets = buildMockVideoFramePackets(runtime.frameNumber, runtime.sequence);
+        runtime.frameNumber = (runtime.frameNumber + 1) & 0xffff;
+        runtime.sequence = (runtime.sequence + packets.length) & 0xffff;
+        for (const packet of packets) {
+          socket.send(packet, port, host);
+          state.streams.video.packetsSent += 1;
+        }
+      };
+      sendFrame();
+      runtime.interval = setInterval(sendFrame, 30);
+      return;
+    }
+
+    const sendAudioPacket = () => {
+      const packet = buildMockAudioPacket(runtime.sequence, runtime.sampleIndex);
+      runtime.sequence = (runtime.sequence + 1) & 0xffff;
+      runtime.sampleIndex += 192;
+      socket.send(packet, port, host);
+      state.streams.audio.packetsSent += 1;
+    };
+
+    sendAudioPacket();
+    runtime.interval = setInterval(sendAudioPacket, 4);
+  }
+
   const server = createServer(async (req, res) => {
     const { method, url } = req;
 
@@ -386,6 +465,7 @@ export async function startMockC64Server(options = {}) {
 
       state.memory.set(bytes, address);
       state.lastWrite = { address, bytes };
+      state.writeLog.push({ address, bytes: Buffer.from(bytes) });
 
       sendJson(res, { result: "wrote", address, length: bytes.length });
       return;
@@ -404,6 +484,7 @@ export async function startMockC64Server(options = {}) {
 
       state.memory.set(bytes, address);
       state.lastWrite = { address, bytes };
+      state.writeLog.push({ address, bytes: Buffer.from(bytes) });
 
       sendJson(res, { result: "wrote", address, length: bytes.length });
       return;
@@ -512,15 +593,19 @@ export async function startMockC64Server(options = {}) {
         if (action === "start" && method === "PUT") {
           const body = await readJson(req);
           const target = routeUrl.searchParams.get("ip") ?? routeUrl.searchParams.get("target") ?? body?.ip ?? body?.target ?? null;
-          state.streams[stream] = { active: true, target };
+          state.streams[stream] = { active: true, target, packetsSent: 0 };
           state.lastStreamAction = { action: "start", stream, target };
+          state.streamActionLog.push({ action: "start", stream, target });
+          startStreamEmitter(stream, target);
           sendJson(res, { result: "started", stream, target });
           return;
         }
 
         if (action === "stop" && method === "PUT") {
-          state.streams[stream] = { active: false, target: null };
+          stopStreamEmitter(stream);
+          state.streams[stream] = { active: false, target: null, packetsSent: state.streams[stream]?.packetsSent ?? 0 };
           state.lastStreamAction = { action: "stop", stream };
+          state.streamActionLog.push({ action: "stop", stream });
           sendJson(res, { result: "stopped", stream });
           return;
         }
@@ -678,9 +763,80 @@ export async function startMockC64Server(options = {}) {
     baseUrl: `http://127.0.0.1:${address.port}`,
     state,
     async close() {
+      stopAllStreams();
       server.close();
       await once(server, "close");
     },
     reset: resetState,
   };
 }
+
+function parseStreamTarget(value, defaultPort) {
+  const trimmed = String(value ?? "").trim();
+  if (!trimmed) {
+    return { host: "127.0.0.1", port: defaultPort };
+  }
+  const separator = trimmed.lastIndexOf(":");
+  if (separator <= 0 || separator === trimmed.length - 1) {
+    return { host: trimmed, port: defaultPort };
+  }
+  const host = trimmed.slice(0, separator);
+  const port = Number.parseInt(trimmed.slice(separator + 1), 10);
+  return {
+    host,
+    port: Number.isFinite(port) && port > 0 && port <= 65535 ? port : defaultPort,
+  };
+}
+
+function buildMockVideoFramePackets(frameNumber, sequenceStart) {
+  const width = 384;
+  const height = 272;
+  const linesPerPacket = 4;
+  const bytesPerLine = width / 2;
+  const packets = [];
+  let sequence = sequenceStart & 0xffff;
+
+  for (let line = 0; line < height; line += linesPerPacket) {
+    const header = Buffer.alloc(12);
+    header.writeUInt16LE(sequence, 0);
+    header.writeUInt16LE(frameNumber & 0xffff, 2);
+    const isLastPacket = line + linesPerPacket >= height;
+    header.writeUInt16LE(isLastPacket ? (line | 0x8000) : line, 4);
+    header.writeUInt16LE(width, 6);
+    header.writeUInt8(linesPerPacket, 8);
+    header.writeUInt8(4, 9);
+    header.writeUInt16LE(0, 10);
+
+    const payload = Buffer.alloc(bytesPerLine * linesPerPacket);
+    let offset = 0;
+    for (let y = 0; y < linesPerPacket; y += 1) {
+      const absoluteLine = line + y;
+      for (let x = 0; x < width; x += 2) {
+        const low = (frameNumber + absoluteLine + x) & 0x0f;
+        const high = (frameNumber + absoluteLine + x + 1) & 0x0f;
+        payload[offset++] = low | (high << 4);
+      }
+    }
+
+    packets.push(Buffer.concat([header, payload]));
+    sequence = (sequence + 1) & 0xffff;
+  }
+
+  return packets;
+}
+
+function buildMockAudioPacket(sequence, sampleIndex) {
+  const header = Buffer.alloc(2);
+  header.writeUInt16LE(sequence & 0xffff, 0);
+
+  const payload = Buffer.alloc(768);
+  for (let index = 0; index < 192; index += 1) {
+    const phase = ((sampleIndex + index) % 256) - 128;
+    const left = phase * 128;
+    const right = -left;
+    payload.writeInt16LE(left, index * 4);
+    payload.writeInt16LE(right, index * 4 + 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}