c64bridge 0.5.0

package/scripts/sid2wav.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SID="${1:?Usage: sid2wav.sh <file.sid> [out.wav] [ntsc|pal] [limitCycles]}"
+OUT="${2:-${SID%.sid}.wav}"
+MODE="${3:-ntsc}"
+CYCLES="${4:-120000000}"
+
+case "${MODE}" in
+  pal|ntsc) ;;
+  *)
+    echo "Unsupported mode: ${MODE} (expected pal or ntsc)" >&2
+    exit 1
+    ;;
+esac
+
+PAL_CLOCK=985248
+NTSC_CLOCK=1022727
+
+if [[ "${CYCLES}" -le 0 ]]; then
+  echo "limitCycles must be positive" >&2
+  exit 1
+fi
+
+if [[ ! -f "${SID}" ]]; then
+  echo "SID file not found: ${SID}" >&2
+  exit 1
+fi
+
+if ! command -v sidplayfp >/dev/null 2>&1; then
+  echo "sidplayfp not found; attempting automatic installation" >&2
+  if command -v apt-get >/dev/null 2>&1; then
+    if command -v sudo >/dev/null 2>&1; then
+      sudo -n apt-get update -y || true
+      sudo -n apt-get install -y sidplayfp || true
+    else
+      apt-get update -y || true
+      apt-get install -y sidplayfp || true
+    fi
+  elif command -v brew >/dev/null 2>&1; then
+    brew install sidplayfp || true
+  elif command -v dnf >/dev/null 2>&1; then
+    if command -v sudo >/dev/null 2>&1; then
+      sudo -n dnf install -y sidplayfp || true
+    else
+      dnf install -y sidplayfp || true
+    fi
+  elif command -v pacman >/dev/null 2>&1; then
+    if command -v sudo >/dev/null 2>&1; then
+      sudo -n pacman -Sy --noconfirm sidplayfp || true
+    else
+      pacman -Sy --noconfirm sidplayfp || true
+    fi
+  elif command -v choco >/dev/null 2>&1; then
+    choco install sidplayfp -y || true
+  elif command -v winget >/dev/null 2>&1; then
+    winget install --id=SIDTools.sidplayfp -e --source winget || true
+  else
+    echo "Unable to auto-install sidplayfp; please install it manually." >&2
+    exit 127
+  fi
+
+  if ! command -v sidplayfp >/dev/null 2>&1; then
+    echo "sidplayfp is still missing after installation attempt." >&2
+    exit 127
+  fi
+fi
+
+clock=${PAL_CLOCK}
+sidplay_opts=( )
+
+if [[ "${MODE}" == "ntsc" ]]; then
+  clock=${NTSC_CLOCK}
+  sidplay_opts+=(-vn) # NTSC clock
+else
+  sidplay_opts+=(-vp) # PAL clock
+fi
+
+# Convert cycle limit to playback duration in seconds (round up) using Node.js
+duration_seconds=$(node -e 'const cycles=Number(process.argv[1]);const clock=Number(process.argv[2]);if(!Number.isFinite(cycles)||!Number.isFinite(clock)||cycles<=0||clock<=0){process.exit(1);}const seconds=Math.max(1, Math.ceil(cycles/clock));process.stdout.write(String(seconds));' "${CYCLES}" "${clock}")
+
+if [[ -z "${duration_seconds}" ]]; then
+  echo "Failed to compute playback duration from cycle limit." >&2
+  exit 1
+fi
+
+sidplay_opts+=(
+  -f44100             # 44.1 kHz sample rate
+  -p16                # 16-bit signed PCM
+  -t"${duration_seconds}"  # playback duration in seconds
+  -w"${OUT}"          # output WAV path
+)
+
+exec sidplayfp "${sidplay_opts[@]}" "${SID}"

package/scripts/smoke-run.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MODE=${1:-local}
+DURATION=${2:-5}
+LOGFILE=${LOGFILE:-"mcp-server-$(date +%Y%m%d-%H%M%S).log"}
+PACKAGE_DIR=${PACKAGE_DIR:-}
+
+mkdir -p "$(dirname "$LOGFILE")"
+: >"$LOGFILE"
+LOGFILE=$(realpath "$LOGFILE")
+
+echo "==> Starting MCP server in '$MODE' mode for ${DURATION}s"
+echo "==> Logs: $LOGFILE"
+
+STATUS=0
+
+set +e
+case "$MODE" in
+  local)
+    if [[ -z "$PACKAGE_DIR" ]]; then
+      echo "PACKAGE_DIR environment variable must be set for local mode" >&2
+      exit 1
+    fi
+    if [[ ! -d "$PACKAGE_DIR" ]]; then
+      echo "PACKAGE_DIR '$PACKAGE_DIR' does not exist" >&2
+      exit 1
+    fi
+    (
+      cd "$PACKAGE_DIR" || exit 1
+  timeout --signal=TERM "$DURATION" node dist/index.js
+    ) 2>&1 | tee "$LOGFILE"
+    STATUS=${PIPESTATUS[0]}
+    ;;
+  npm)
+    if [[ -z "$PACKAGE_DIR" ]]; then
+      echo "PACKAGE_DIR environment variable must be set for npm mode" >&2
+      exit 1
+    fi
+    if [[ ! -d "$PACKAGE_DIR" ]]; then
+      echo "PACKAGE_DIR '$PACKAGE_DIR' does not exist" >&2
+      exit 1
+    fi
+    (
+      cd "$PACKAGE_DIR" || exit 1
+      timeout --signal=TERM "$DURATION" node dist/index.js
+    ) 2>&1 | tee "$LOGFILE"
+    STATUS=${PIPESTATUS[0]}
+    ;;
+  *)
+    echo "Usage: $0 [local|npm] [duration_seconds]" >&2
+    exit 1
+    ;;
+esac
+set -e
+
+if [[ $STATUS -eq 124 ]]; then
+  echo "==> Timeout reached after ${DURATION}s (expected)."
+elif [[ $STATUS -ne 0 ]]; then
+  echo "==> MCP server exited with status $STATUS"
+  exit $STATUS
+fi
+
+echo "==> Run complete"
+echo "==> Logs stored at: $LOGFILE"

package/scripts/start-mock-c64.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// CI helper: writes the mock C64 base URL (plain text) for workflow callers and blocks until killed.
+import { writeFileSync } from 'node:fs';
+import process from 'node:process';
+import path from 'node:path';
+
+async function main() {
+  const outputArg = process.argv[2];
+  const resolvePath = (maybePath) => {
+    if (!maybePath) {
+      return null;
+    }
+    if (path.isAbsolute(maybePath)) {
+      return maybePath;
+    }
+    return path.resolve(process.cwd(), maybePath);
+  };
+  const outputFile = resolvePath(outputArg);
+
+  const moduleUrl = new URL('../test/mockC64Server.mjs', import.meta.url);
+  const { startMockC64Server } = await import(moduleUrl.href);
+  const server = await startMockC64Server();
+  const baseUrl = server.baseUrl;
+  console.log(`[mock-c64] listening at ${baseUrl}`);
+  if (outputFile) {
+    writeFileSync(outputFile, baseUrl, 'utf8');
+  }
+
+  const shutdown = async (signal) => {
+    console.log(`[mock-c64] received ${signal ?? 'signal'}, shutting down`);
+    try {
+      await server.close();
+    } finally {
+      process.exit(0);
+    }
+  };
+
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+
+  await new Promise(() => {});
+}
+
+main().catch((error) => {
+  console.error('[mock-c64] failed to start mock server:', error);
+  process.exit(1);
+});

package/scripts/start-mock.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Local smoke-test helper: writes mock server info JSON for run-mcp-check.sh and keeps it alive.
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Reuse the existing mock server implementation from tests
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+const { startMockC64Server } = await import(path.join(root, 'test', 'mockC64Server.mjs'));
+
+const outPath = process.argv[2];
+if (!outPath) {
+  console.error('Usage: start-mock.mjs <out-json-path>');
+  process.exit(1);
+}
+
+const mock = await startMockC64Server();
+await writeFile(outPath, JSON.stringify({ baseUrl: mock.baseUrl }, null, 2) + '\n', 'utf8');
+
+// Keep process alive until terminated; forward signals to close
+const onExit = async () => {
+  try { await mock.close(); } catch {}
+  process.exit(0);
+};
+process.on('SIGTERM', onExit);
+process.on('SIGINT', onExit);
+
+// Idle forever
+setInterval(() => {}, 1 << 30).unref();

package/scripts/start.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Flexible launcher for the MCP server.
+ *
+ * - Prefer running the TypeScript sources via ts-node when they are available
+ *   (local development workflow).
+ * - Fall back to the compiled JavaScript in dist/ when the package is
+ *   consumed from npm, where the sources and dev dependencies are omitted.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { stat } from 'node:fs/promises';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(here, '..');
+
+async function fileExists(filePath) {
+  try {
+    const stats = await stat(filePath);
+    return stats.isFile();
+  } catch (error) {
+    const err = error;
+    if (err && typeof err === 'object' && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function isModuleNotFound(error) {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const err = error;
+  if (err.code === 'ERR_MODULE_NOT_FOUND') {
+    return true;
+  }
+  const message = typeof err.message === 'string' ? err.message : '';
+  return message.includes('Cannot find module');
+}
+
+async function launch() {
+  const srcEntry = path.resolve(projectRoot, 'src/index.ts');
+  const distEntry = path.resolve(projectRoot, 'dist/index.js');
+
+  if (await fileExists(srcEntry)) {
+    try {
+      await import('./register-ts-node.mjs');
+      await import(pathToFileURL(srcEntry).href);
+      return;
+    } catch (error) {
+      if (isModuleNotFound(error)) {
+        console.warn('[start] ts-node not available; falling back to compiled output.');
+      } else {
+        console.error('[start] Failed to launch TypeScript sources:', error);
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+
+  if (await fileExists(distEntry)) {
+    await import(pathToFileURL(distEntry).href);
+    return;
+  }
+
+  console.error('[start] Unable to locate server entry point: dist/index.js or src/index.ts.');
+  console.error('[start] Build the project with `npm run build` or install dev dependencies for ts-node.');
+  process.exitCode = 1;
+}
+
+await launch();

package/scripts/update-readme.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describeToolModules } from "../src/tools/registry.js";
+import { listKnowledgeResources } from "../src/rag/knowledgeIndex.js";
+import { createPromptRegistry } from "../src/prompts/registry.js";
+
+const START_MARKER = "<!-- AUTO-GENERATED:MCP-DOCS-START -->";
+const END_MARKER = "<!-- AUTO-GENERATED:MCP-DOCS-END -->";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..");
+const README_PATH = join(PROJECT_ROOT, "README.md");
+
+function titleCase(input: string): string {
+  return input
+    .split(/[\s_-]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function escapeCell(value: string): string {
+  return value.replace(/\|/g, "\\|").replace(/\r?\n|\r/g, " ").trim();
+}
+
+function formatTags(tags: readonly string[]): string {
+  if (!tags.length) {
+    return "—";
+  }
+  return tags.map((tag) => `\`${tag}\``).join(", ");
+}
+
+function renderTable(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+  const headerLine = `| ${headers.join(" | ")} |`;
+  const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+  const body = rows.map((row) => `| ${row.join(" | ")} |`).join("\n");
+  return [headerLine, separator, body].filter(Boolean).join("\n");
+}
+
+function renderToolsSection(): string[] {
+  const modules = describeToolModules();
+  const lines: string[] = ["### Tools", ""];
+
+  for (const module of modules) {
+    lines.push(`#### ${titleCase(module.domain)}`);
+    if (module.summary) {
+      lines.push(`> ${module.summary}`);
+    }
+    if (module.workflowHints.length) {
+      lines.push("");
+      lines.push("**Workflow hints:**");
+      for (const hint of module.workflowHints) {
+        lines.push(`- ${hint}`);
+      }
+    }
+    if (module.defaultTags.length) {
+      lines.push("");
+      lines.push(`**Default tags:** ${module.defaultTags.map((tag) => `\`${tag}\``).join(", ")}`);
+    }
+
+    const rows = module.tools
+      .slice()
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((tool) => [
+        `\`${tool.name}\``,
+        escapeCell(tool.description),
+        formatTags(tool.metadata.tags),
+      ]);
+
+    lines.push("");
+    if (rows.length) {
+      lines.push(renderTable(["Name", "Description", "Tags"], rows));
+    } else {
+      lines.push("_No tools registered._");
+    }
+    lines.push("");
+  }
+
+  return lines;
+}
+
+function renderResourcesSection(): string[] {
+  const resources = listKnowledgeResources()
+    .slice()
+    .sort((a, b) => {
+      const bundleOrder = a.metadata.bundle.order - b.metadata.bundle.order;
+      if (bundleOrder !== 0) {
+        return bundleOrder;
+      }
+      return a.metadata.order - b.metadata.order;
+    });
+
+  const rows = resources.map((resource) => [
+    `\`${resource.uri}\``,
+    escapeCell(resource.metadata.summary || resource.description),
+  ]);
+
+  return [
+    "### Resources",
+    "",
+    rows.length ? renderTable(["Name", "Summary"], rows) : "_No resources registered._",
+    "",
+  ];
+}
+
+function renderPromptsSection(): string[] {
+  const promptRegistry = createPromptRegistry();
+  const prompts = promptRegistry
+    .list()
+    .slice()
+    .sort((a, b) => a.descriptor.name.localeCompare(b.descriptor.name));
+
+  const rows = prompts.map((entry) => [
+    `\`${entry.descriptor.name}\``,
+    escapeCell(entry.descriptor.description),
+  ]);
+
+  return [
+    "### Prompts",
+    "",
+    rows.length ? renderTable(["Name", "Description"], rows) : "_No prompts registered._",
+    "",
+  ];
+}
+
+function buildDocumentation(): string {
+  const sections = [renderToolsSection(), renderResourcesSection(), renderPromptsSection()];
+  return sections.flat().join("\n").trim();
+}
+
+async function updateReadme(): Promise<boolean> {
+  const readme = await readFile(README_PATH, "utf8");
+  const pattern = new RegExp(
+    `${START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([\\s\\S]*?)${END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!pattern.test(readme)) {
+    throw new Error(
+      `Could not find auto-generated section markers (${START_MARKER} / ${END_MARKER}) in README.md`,
+    );
+  }
+
+  const generated = `\n\n${buildDocumentation()}\n\n`;
+  const nextReadme = readme.replace(pattern, `${START_MARKER}${generated}${END_MARKER}`);
+
+  if (nextReadme === readme) {
+    return false;
+  }
+
+  await writeFile(README_PATH, nextReadme, "utf8");
+  return true;
+}
+
+try {
+  const updated = await updateReadme();
+  if (updated) {
+    console.error("README.md updated with MCP documentation.");
+  }
+} catch (error) {
+  console.error("Failed to update README.md:", error);
+  process.exitCode = 1;
+}

package/scripts/verify-package.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import crypto from 'node:crypto';
+
+function usage() {
+  console.error('Usage: node scripts/verify-package.mjs <package-dir>');
+  process.exit(1);
+}
+
+const dirArg = process.argv[2];
+if (!dirArg) {
+  usage();
+}
+
+const packageDir = resolve(process.cwd(), dirArg);
+
+function ensureExists(relPath, type = 'file') {
+  const fullPath = resolve(packageDir, relPath);
+  try {
+    const stats = statSync(fullPath);
+    if (type === 'file' && !stats.isFile()) {
+      console.error(`Expected file at ${relPath}, found other type`);
+      process.exit(1);
+    }
+    if (type === 'dir' && !stats.isDirectory()) {
+      console.error(`Expected directory at ${relPath}, found other type`);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Missing required ${type} at ${relPath}:`, error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+function assertSpotChecks() {
+  const files = [
+    'package.json',
+    'mcp.json',
+    'README.md',
+    'LICENSE',
+    'dist/index.js',
+    'dist/c64Client.js',
+    'dist/rag/sources.csv',
+    'dist/rag/discover.config.json',
+    'generated/c64/index.js',
+    'scripts/cli.js',
+    'scripts/start.mjs',
+    'scripts/register-ts-node.mjs',
+  ];
+  const dirs = [
+    'doc',
+    'data',
+    'dist/rag',
+  ];
+
+  files.forEach((file) => ensureExists(file, 'file'));
+  dirs.forEach((dir) => ensureExists(dir, 'dir'));
+
+  const embeddings = readdirSync(resolve(packageDir, 'data')).filter((name) => name.startsWith('embeddings_') && name.endsWith('.json'));
+  if (embeddings.length === 0) {
+    console.error('Expected embeddings JSON files under data/, none found');
+    process.exit(1);
+  }
+}
+
+function detectDuplicates() {
+  const hashes = new Map();
+  const duplicates = [];
+
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const rel = relative(packageDir, fullPath);
+        const data = readFileSync(fullPath);
+        const hash = crypto.createHash('sha256').update(data).digest('hex');
+        if (hashes.has(hash)) {
+          duplicates.push([hashes.get(hash), rel]);
+        } else {
+          hashes.set(hash, rel);
+        }
+      }
+    }
+  };
+
+  walk(packageDir);
+
+  if (duplicates.length > 0) {
+    console.error('Duplicate files detected in package (identical content):');
+    for (const [first, dup] of duplicates) {
+      console.error(` - ${first} == ${dup}`);
+    }
+    process.exit(1);
+  }
+}
+
+function showSourcesCsvPreview() {
+  const csvPath = resolve(packageDir, 'dist/rag/sources.csv');
+  try {
+    const preview = readFileSync(csvPath, 'utf8').split('\n').slice(0, 5).join('\n');
+    console.log('Preview dist/rag/sources.csv:');
+    console.log(preview);
+  } catch (error) {
+    console.error('Failed to read dist/rag/sources.csv:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+function logPackageContents() {
+  const items = [];
+  const stack = ['.'];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const fullPath = resolve(packageDir, current);
+    const stats = statSync(fullPath);
+    if (stats.isDirectory()) {
+      if (current !== '.') {
+        items.push(`${current}/`);
+      }
+      const children = readdirSync(fullPath)
+        .map((name) => (current === '.' ? name : `${current}/${name}`))
+        .sort()
+        .reverse();
+      for (const child of children) {
+        stack.push(child);
+      }
+    } else if (stats.isFile()) {
+      items.push(current);
+    }
+  }
+
+  items.sort((a, b) => a.localeCompare(b));
+  console.log('Package file listing:');
+  for (const entry of items) {
+    console.log(` - ${entry}`);
+  }
+}
+
+assertSpotChecks();
+detectDuplicates();
+showSourcesCsvPreview();
+logPackageContents();
+
+console.log('Package verification succeeded.');