c64bridge 0.5.0

package/mcp.json

@@ -0,0 +1,106 @@
+{
+  "name": "c64bridge",
+  "version": "0.5.0",
+  "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
+  "entry": "dist/index.js",
+  "type": "stdio",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model context protocol",
+    "openai",
+    "ultimate64",
+    "commodore64",
+    "commodore 64",
+    "c64",
+    "c64u",
+    "sid",
+    "basic",
+    "assembly",
+    "retro",
+    "retrocomputing",
+    "retrogaming",
+    "vintage computing",
+    "hardware integration",
+    "c64 development",
+    "commodore 64 ultimate",
+    "ultimate 64"
+  ],
+  "env": {
+    "LOG_LEVEL": {
+      "description": "Logger verbosity (debug, info, warn, error)",
+      "default": "info"
+    },
+    "C64BRIDGE_CONFIG": {
+      "description": "Path to configuration JSON",
+      "default": "~/.c64bridge.json"
+    },
+    "C64_MODE": {
+      "description": "Select active backend (c64u for Ultimate hardware, vice for emulator)",
+      "default": "c64u"
+    },
+    "RAG_EMBEDDINGS_DIR": {
+      "description": "Directory containing RAG embedding JSON files",
+      "default": "data"
+    },
+    "RAG_REINDEX_INTERVAL_MS": {
+      "description": "Periodic reindex interval in ms (0 disables)",
+      "default": "0"
+    },
+    "RAG_BUILD_ON_START": {
+      "description": "Set to 1 to rebuild embeddings on server start"
+    },
+    "RAG_DOC_FILES": {
+      "description": "Comma-separated extra docs to include in RAG"
+    },
+    "RAG_DISCOVER_FORCE_REFRESH": {
+      "description": "Set to 1 to ignore cached discovery results when fetching external docs"
+    },
+    "GITHUB_TOKEN": {
+      "description": "Personal access token used for optional RAG discovery against GitHub"
+    },
+    "C64_TEST_TARGET": {
+      "description": "Overrides integration tests to hit mock or real hardware (mock|real)"
+    },
+    "VICE_MODE": {
+      "description": "Default video standard for VICE audio capture (ntsc|pal)",
+      "default": "ntsc"
+    },
+    "VICE_LIMIT_CYCLES": {
+      "description": "Maximum CPU cycles to render when VICE generates audio",
+      "default": "120000000"
+    },
+    "VICE_BINARY": {
+      "description": "VICE binary to launch for audio capture",
+      "default": "x64sc"
+    },
+    "VICE_RUN_TIMEOUT_MS": {
+      "description": "Timeout for headless VICE runs in milliseconds",
+      "default": "10000"
+    },
+    "FORCE_XVFB": {
+      "description": "Set to 1 to force xvfb-run when executing VICE",
+      "default": "0"
+    },
+    "SIDPLAY_MODE": {
+      "description": "Default SID playback mode (ntsc|pal)",
+      "default": "ntsc"
+    },
+    "SIDPLAY_LIMIT_CYCLES": {
+      "description": "Maximum CPU cycles to render when sidplayfp generates audio",
+      "default": "120000000"
+    },
+    "SIDPLAY_BINARY": {
+      "description": "sidplayfp binary to launch when generating audio",
+      "default": "sidplayfp"
+    },
+    "SIDPLAYFP_BINARY": {
+      "description": "Legacy alias for SIDPLAY_BINARY (sidplayfp executable name)"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chrisgleissner/c64bridge"
+  },
+  "license": "GPL-2.0-only"
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "c64bridge",
+  "version": "0.5.0",
+  "description": "Local MCP server for controlling a Commodore 64 via Ultimate 64 REST API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "c64bridge": "scripts/cli.js"
+  },
+  "scripts": {
+    "start": "node scripts/start.mjs",
+    "mcp": "node --loader ts-node/esm src/mcp-server.ts",
+    "mcp:build": "npm run build && node dist/mcp-server.js",
+    "build": "tsc -p tsconfig.json && node scripts/postbuild.mjs && node --import ./scripts/register-ts-node.mjs scripts/update-readme.ts",
+    "lint": "npm run check",
+    "test": "node scripts/run-tests.mjs",
+    "coverage": "c8 -r text -r lcov node scripts/run-tests.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "check:run-local": "bash scripts/run-mcp-check.sh local 5",
+    "check:run-npm": "bash scripts/run-mcp-check.sh npm 5",
+    "check": "npm run build && npm test",
+    "build:rag": "node --import ./scripts/register-ts-node.mjs scripts/rag-rebuild.mjs",
+    "api:generate": "npx --yes swagger-typescript-api@12.0.4 -p doc/rest/c64-openapi.yaml -o generated/c64 -n index.ts --axios --single-http-client --module-name-first-tag",
+    "c64:tool": "bash scripts/c64-tool.sh",
+    "rag:rebuild": "node --import ./scripts/register-ts-node.mjs scripts/rag-rebuild.mjs",
+    "rag:fetch": "node scripts/fetch-external-sources.mjs",
+    "rag:discover": "node --import ./scripts/register-ts-node.mjs src/rag/discover.ts",
+    "changelog:generate": "node scripts/generate-changelog.mjs",
+    "release:prepare": "node scripts/prepare-release.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "c64",
+    "commodore-64",
+    "commodore-64-ultimate",
+    "ultimate-64",
+    "retro-computing",
+    "llm"
+  ],
+  "author": "Christian Gleissner",
+  "license": "GPL-2.0-only",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "axios": "^1.7.7",
+    "fastify": "^4.28.1",
+    "meyda": "^5.6.2",
+    "octokit": "^4.0.2",
+    "pitchfinder": "^2.2.0",
+    "reflect-metadata": "^0.1.13",
+    "yaml": "^2.6.0"
+  },
+  "optionalDependencies": {
+    "naudiodon": "^2.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.23",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.5",
+    "c8": "^9.1.0"
+  },
+  "files": [
+    "mcp.json",
+    "AGENTS.md",
+    "LICENSE",
+    "README.md",
+    "dist/**",
+    "data/**",
+    "doc/**",
+    "scripts/**",
+    "generated/**/*.js",
+    ".github/prompts/**"
+  ],
+  "prepack": "npm run build"
+}

package/scripts/c64-cli.mjs

@@ -0,0 +1,142 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, basename, resolve } from "node:path";
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import { basicToPrg } from "../src/basicConverter.ts";
+import { loadConfig } from "../src/config.ts";
+import { C64Client } from "../src/c64Client.ts";
+
+const booleanFlags = new Set(["run"]);
+
+function parseOptions(args) {
+  const options = new Map();
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (!token.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    const key = token.slice(2);
+    if (booleanFlags.has(key)) {
+      options.set(key, true);
+      continue;
+    }
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) {
+      throw new Error(`Missing value for option: --${key}`);
+    }
+    options.set(key, value);
+    i += 1;
+  }
+  return options;
+}
+
+async function ensureOutputPath(path) {
+  await mkdir(dirname(path), { recursive: true });
+}
+
+function resolveOutputPath(inputPath, suppliedOutput) {
+  if (suppliedOutput) {
+    return resolve(process.cwd(), suppliedOutput);
+  }
+  const base = basename(inputPath, extname(inputPath)) || "program";
+  return resolve(process.cwd(), "artifacts", `${base}.prg`);
+}
+
+function printResult(result) {
+  if (!result) {
+    return;
+  }
+  if (result.success) {
+    console.log("C64 responded:", JSON.stringify(result.details, null, 2));
+  } else {
+    console.error("C64 returned an error:", JSON.stringify(result.details, null, 2));
+  }
+}
+
+async function handleConvertBasic(args, { autoRun }) {
+  const options = parseOptions(args);
+  const inputPath = options.get("input");
+  if (!inputPath) {
+    throw new Error("Please provide --input <path-to-basic-file>");
+  }
+
+  const outputPath = resolveOutputPath(inputPath, options.get("output"));
+  const contents = await readFile(resolve(process.cwd(), inputPath), "utf8");
+  const prg = basicToPrg(contents);
+  await ensureOutputPath(outputPath);
+  await writeFile(outputPath, prg);
+  console.log(`PRG written to ${outputPath}`);
+
+  if (autoRun || options.get("run")) {
+    const result = await runPrgOnHardware(prg);
+    printResult(result);
+  }
+}
+
+async function handleRunPrg(args) {
+  const options = parseOptions(args);
+  const inputPath = options.get("input");
+  if (!inputPath) {
+    throw new Error("Please provide --input <path-to-prg-file>");
+  }
+  const prg = await readFile(resolve(process.cwd(), inputPath));
+  const result = await runPrgOnHardware(prg);
+  printResult(result);
+}
+
+async function runPrgOnHardware(prg) {
+  const config = loadConfig();
+  const target = config.baseUrl ?? `http://${config.c64_host}`;
+  const client = new C64Client(target);
+  console.log(`Uploading PRG (${prg.length} bytes) to ${target} ...`);
+  return client.runPrg(prg);
+}
+
+function printHelp() {
+  console.log(`Usage:
+  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs <command> [options]
+
+Commands:
+  convert-basic   Convert a BASIC text file into a PRG. Options: --input <path> [--output <path>] [--run]
+  run-basic       Convert a BASIC text file and immediately run it. Options: --input <path> [--output <path>]
+  run-prg         Upload and run an existing PRG file. Options: --input <path>
+
+Examples:
+  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs convert-basic --input demos/hello.bas
+  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs run-basic --input demos/hello.bas
+  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs run-prg --input artifacts/demo-basic.prg
+`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  try {
+    switch (command) {
+      case "convert-basic":
+        await handleConvertBasic(rest, { autoRun: false });
+        break;
+      case "run-basic":
+        await handleConvertBasic(rest, { autoRun: true });
+        break;
+      case "run-prg":
+        await handleRunPrg(rest);
+        break;
+      default:
+        throw new Error(`Unknown command: ${command}`);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+    } else {
+      console.error(error);
+    }
+    process.exitCode = 1;
+  }
+}
+
+await main();

package/scripts/c64-tool.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+CLI_CMD=(node --import "${REPO_ROOT}/scripts/register-ts-node.mjs" "${REPO_ROOT}/scripts/c64-cli.mjs")
+
+function prompt_path() {
+  local prompt="$1"
+  local value
+  read -r -p "${prompt}: " value
+  echo "${value}"
+}
+
+function run_cli() {
+  echo ""
+  "${CLI_CMD[@]}" "$@"
+  echo ""
+}
+
+function convert_basic() {
+  local input output
+  input=$(prompt_path "Enter path to BASIC source file")
+  output=$(prompt_path "Optional PRG output path (leave blank for default)")
+  if [[ -z "${input}" ]]; then
+    echo "No input provided."
+    return
+  fi
+  if [[ -n "${output}" ]]; then
+    run_cli convert-basic --input "${input}" --output "${output}"
+  else
+    run_cli convert-basic --input "${input}"
+  fi
+}
+
+function convert_and_run() {
+  local input output
+  input=$(prompt_path "Enter path to BASIC source file")
+  output=$(prompt_path "Optional PRG output path (leave blank for default)")
+  if [[ -z "${input}" ]]; then
+    echo "No input provided."
+    return
+  fi
+  if [[ -n "${output}" ]]; then
+    run_cli convert-basic --input "${input}" --output "${output}" --run
+  else
+    run_cli convert-basic --input "${input}" --run
+  fi
+}
+
+function run_existing_prg() {
+  local input
+  input=$(prompt_path "Enter path to PRG file")
+  if [[ -z "${input}" ]]; then
+    echo "No input provided."
+    return
+  fi
+  run_cli run-prg --input "${input}"
+}
+
+function main_menu() {
+  while true; do
+    cat <<'EOF'
+========================================
+C64 Bridge Utility
+  1) Convert BASIC to PRG
+  2) Convert BASIC to PRG and run on C64
+  3) Run existing PRG on C64
+  4) Quit
+========================================
+EOF
+    read -r -p "Select an option: " choice
+    case "${choice}" in
+      1) convert_basic ;;
+      2) convert_and_run ;;
+      3) run_existing_prg ;;
+      4) exit 0 ;;
+      *) echo "Invalid choice: ${choice}" ;;
+    esac
+  done
+}
+
+main_menu

package/scripts/check-package.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { stdio: 'pipe', encoding: 'utf8', ...opts });
+}
+
+async function listPackFiles() {
+  const json = run('npm', ['pack', '--dry-run', '--json'], { cwd: root });
+  const parsed = JSON.parse(json);
+  const files = parsed?.[0]?.files || [];
+  return files.map((f) => f.path);
+}
+
+async function assertIncludes(files, required) {
+  for (const r of required) {
+    if (!files.includes(r)) {
+      throw new Error(`Package missing required file: ${r}`);
+    }
+  }
+}
+
+async function assertNoDuplicates(files) {
+  const seen = new Set();
+  for (const f of files) {
+    const lower = f.toLowerCase();
+    if (seen.has(lower)) {
+      throw new Error(`Duplicate entry in package tarball: ${f}`);
+    }
+    seen.add(lower);
+  }
+}
+
+async function spotCheckTarball(included) {
+  // Also inspect the actual tarball via system tar to double-verify
+  const json = run('npm', ['pack', '--json'], { cwd: root });
+  const parsed = JSON.parse(json);
+  const filename = parsed?.[0]?.filename;
+  if (!filename) throw new Error('npm pack did not return filename');
+
+  const tgzPath = path.resolve(root, filename);
+  const listing = run('tar', ['-tzf', tgzPath], { cwd: root });
+  const lines = listing.split(/\r?\n/).filter(Boolean);
+  const seen = new Set();
+  for (const line of lines) {
+    const p = line.replace(/^package\//, '');
+    const lower = p.toLowerCase();
+    if (seen.has(lower)) {
+      throw new Error(`Duplicate path detected inside tarball: ${p}`);
+    }
+    seen.add(lower);
+  }
+
+  for (const r of included) {
+    if (!seen.has(r.toLowerCase())) {
+      throw new Error(`Tarball missing required file: ${r}`);
+    }
+  }
+
+  await fs.unlink(tgzPath).catch(() => {});
+}
+
+async function main() {
+  const files = await listPackFiles();
+
+  const required = [
+    'README.md',
+    'data/assembly/assembly-spec.md',
+    'data/embeddings_basic.json',
+    'dist/index.js',
+    'dist/rag/discover.config.json',
+    'dist/rag/sources.csv',
+  ];
+
+  await assertIncludes(files, required);
+  await assertNoDuplicates(files);
+  await spotCheckTarball(required);
+
+  console.log('Package checks passed. Required files present and no duplicates found.');
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/scripts/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Lightweight CLI launcher for the compiled server
+// Usage: `npx c64bridge` or after local install `c64bridge`
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const candidates = [
+	'../dist/index.js',
+	'../dist/src/index.js',
+];
+
+async function findEntry() {
+	for (const c of candidates) {
+		const p = path.resolve(here, c);
+		try {
+			const s = await stat(p);
+			if (s.isFile()) return p;
+		} catch {
+			// not found, continue
+		}
+	}
+
+	// Fallback: try reading package.json's main field
+	try {
+		const pkgPath = path.resolve(here, '../package.json');
+		const raw = await readFile(pkgPath, 'utf8');
+		const pkg = JSON.parse(raw);
+		if (pkg && pkg.main) {
+			const mainPath = path.resolve(here, '..', pkg.main);
+			try {
+				const s = await stat(mainPath);
+				if (s.isFile()) return mainPath;
+			} catch {
+				// ignore
+			}
+		}
+	} catch {
+		// ignore
+	}
+
+	return null;
+}
+
+const entry = await findEntry();
+if (!entry) {
+	console.error('Cannot find compiled entrypoint. Expected dist/index.js or dist/src/index.js.');
+	console.error('If you installed from npm, this likely means the published package is missing compiled files.');
+	console.error('Workarounds:');
+	console.error(' - Use a local checkout and run `npm run build` before `node scripts/cli.js`');
+	console.error(' - Or wait for a patched release that includes compiled artifacts.');
+	process.exitCode = 1;
+} else {
+	// import the resolved entry
+	const entryUrl = new URL(`file://${entry}`);
+	await import(entryUrl.href);
+}

package/scripts/fetch-external-sources.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { register } from 'node:module';
+
+async function main() {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const projectRoot = path.resolve(__dirname, '..');
+  const tsNodeLoader = pathToFileURL(path.join(projectRoot, 'node_modules', 'ts-node', 'esm.mjs')).href;
+  register(tsNodeLoader, pathToFileURL(projectRoot));
+  const { fetchFromCsv } = await import('../src/rag/externalFetcher.ts');
+  // Resolve sources.csv from env, dist/rag, or src/rag (in that order)
+  let csvPath = process.env.RAG_SOURCES_CSV;
+  if (!csvPath) {
+    const distCsv = path.join(projectRoot, 'dist', 'rag', 'sources.csv');
+    try {
+      await import('node:fs/promises').then((fs) => fs.access(distCsv)).catch(() => { throw new Error('nope'); });
+      csvPath = distCsv;
+    } catch {
+      csvPath = path.join(projectRoot, 'src', 'rag', 'sources.csv');
+    }
+  }
+  const outDir = process.env.RAG_EXTERNAL_DIR || path.join(projectRoot, 'external');
+  const defaultDepth = Number(process.env.RAG_DEFAULT_DEPTH || 5);
+  const perDomainRps = Number(process.env.RAG_RPS || 5);
+  const maxRequestsPerSeed = Number(process.env.RAG_MAX_REQUESTS || 500);
+
+  const colors = {
+    reset: '\x1b[0m',
+    info: '\x1b[36m',
+    warn: '\x1b[33m',
+    error: '\x1b[31m',
+    start: '\x1b[34m',
+    success: '\x1b[32m',
+  };
+
+  const log = (entry) => {
+    const { level = 'info', event, data } = entry;
+    let color = colors.info;
+    if (event === 'request_start') color = colors.start;
+    else if (event === 'download_success') color = colors.success;
+    else if (level === 'warn') color = colors.warn;
+    else if (level === 'error') color = colors.error;
+    const prefix = event === 'download_success' ? '✅ ' : (event === 'http_error' || level === 'error' || level === 'warn') ? '❌ ' : '';
+    const line = JSON.stringify({ ts: new Date().toISOString(), level, event, data });
+    process.stdout.write(`${color}${prefix}${line}${colors.reset}\n`);
+  };
+
+  const summaries = await fetchFromCsv({
+    csvPath,
+    outDir,
+    defaultDepth,
+    perDomainRps,
+    maxRequestsPerSeed,
+    log,
+  });
+
+  const total = summaries.reduce((a, s) => a + s.visited, 0);
+  const dl = summaries.reduce((a, s) => a + s.downloaded, 0);
+  log({ level: 'info', event: 'session_summary', data: { seeds: summaries.length, totalVisited: total, totalDownloaded: dl } });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});