c64bridge 0.5.0

package/scripts/generate-changelog.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Generate or extend CHANGELOG.md from commit messages since the last tag,
+ * following a Conventional Commits-like format.
+ *
+ * Groups by:
+ *  - feat      → Features
+ *  - fix       → Bug Fixes
+ *  - perf      → Performance
+ *  - refactor  → Refactoring
+ *  - docs      → Documentation
+ *  - test      → Tests
+ *  - build/ci/chore → Chores
+ *  - other     → Other
+ *
+ * Usage: node scripts/generate-changelog.mjs [version]
+ * - version is optional; when provided, it's used as the new release header.
+ */
+import { execSync } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+const run = (cmd) => execSync(cmd, { encoding: 'utf8' }).trim();
+
+const nowDate = new Date().toISOString().slice(0, 10);
+const root = process.cwd();
+
+function getLastTag() {
+  try {
+    return run('git describe --tags --abbrev=0');
+  } catch {
+    return '';
+  }
+}
+
+function getCommits(range) {
+  // Subject and short SHA; filter out merge commits later
+  const format = `%s|%h`;
+  const cmd = range ? `git log --pretty=format:"${format}" ${range}` : `git log --pretty=format:"${format}"`;
+  const out = run(cmd);
+  if (!out) return [];
+  return out.split('\n').map((line) => {
+    const [subject, sha] = line.split('|');
+    return { subject, sha };
+  });
+}
+
+function classify(subject) {
+  // Conventional commits: type(scope)!: desc
+  // Extract type and optional scope
+  const m = subject.match(/^([a-zA-Z]+)(\([^\)]+\))?(!)?:\s+(.*)$/);
+  if (!m) return { group: 'other', entry: subject };
+  const [, type,, bang, desc] = m; // scope ignored in output line beyond description
+  const map = {
+    feat: 'Features',
+    fix: 'Bug Fixes',
+    perf: 'Performance',
+    refactor: 'Refactoring',
+    docs: 'Documentation',
+    test: 'Tests',
+    build: 'Chores',
+    ci: 'Chores',
+    chore: 'Chores'
+  };
+  const group = map[type.toLowerCase()] || 'Other';
+  const breaking = Boolean(bang);
+  return { group, entry: desc + (breaking ? ' (BREAKING)' : '') };
+}
+
+function renderSection(version, date, groups) {
+  const order = ['Features', 'Bug Fixes', 'Performance', 'Refactoring', 'Documentation', 'Tests', 'Chores', 'Other'];
+  let out = `\n## ${version} - ${date}\n\n`;
+  let any = false;
+  for (const name of order) {
+    const items = groups[name] || [];
+    if (items.length === 0) continue;
+    any = true;
+    out += `### ${name}\n\n`;
+    for (const it of items) {
+      out += `- ${it.text}\n`;
+    }
+    out += '\n';
+  }
+  if (!any) {
+    out += '- No notable changes in this release.\n\n';
+  }
+  return out;
+}
+
+async function main() {
+  const version = process.argv[2] || '';
+  const lastTag = getLastTag();
+  const range = lastTag ? `${lastTag}..HEAD` : '';
+  const rawCommits = getCommits(range)
+    .filter((c) => c.subject && !/^Merge\s/.test(c.subject));
+
+  const groups = {};
+  for (const c of rawCommits) {
+    const { group, entry } = classify(c.subject);
+    const line = `${entry} (${c.sha})`;
+    if (!groups[group]) groups[group] = [];
+    groups[group].push({ text: line });
+  }
+
+  // Load or create CHANGELOG.md
+  const changelogPath = path.join(root, 'CHANGELOG.md');
+  const exists = existsSync(changelogPath);
+  const existing = exists ? await readFile(changelogPath, 'utf8') : '# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n';
+
+  const headerVersion = version || run('node -p "require(\'./package.json\').version"');
+  const section = renderSection(headerVersion, nowDate, groups);
+
+  // Prepend the new section after a top-level title if present
+  let updated;
+  const titleMatch = existing.match(/^#\s+Changelog\s*\n/);
+  if (titleMatch) {
+    const idx = titleMatch[0].length;
+    updated = existing.slice(0, idx) + section + existing.slice(idx);
+  } else {
+    updated = section + existing;
+  }
+
+  await writeFile(changelogPath, updated);
+  console.log(`CHANGELOG.md updated for ${headerVersion} (since ${lastTag || 'repo start'}).`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/postbuild.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Normalize the compiled output layout after TypeScript build.
+ *
+ * - Move everything from dist/src/* to dist/*
+ * - Remove the now-empty dist/src directory
+ *
+ * This keeps the published package tree leaner (single index.js location)
+ * while still allowing TypeScript to compile with include patterns.
+ */
+import { readdir, rename, rm, stat, mkdir, copyFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const distRoot = path.resolve('dist');
+const distSrc = path.join(distRoot, 'src');
+
+async function main() {
+  try {
+    const stats = await stat(distSrc);
+    if (!stats.isDirectory()) {
+      return;
+    }
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return; // nothing to do
+    }
+    throw err;
+  }
+
+  const entries = await readdir(distSrc, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(distSrc, entry.name);
+    const to = path.join(distRoot, entry.name);
+    // Remove any existing destination to allow rename.
+    await rm(to, { recursive: true, force: true });
+    await rename(from, to);
+  }
+
+  await rm(distSrc, { recursive: true, force: true });
+
+  // Ensure RAG static assets (CSV/JSON) are available under dist/rag for runtime tools
+  // Source-of-truth lives under src/rag/*. Copy selected assets if present.
+  const projectRoot = path.resolve('.');
+  const ragSrcDir = path.join(projectRoot, 'src', 'rag');
+  const ragDistDir = path.join(distRoot, 'rag');
+  try {
+    await mkdir(ragDistDir, { recursive: true });
+    const assets = ['sources.csv', 'discover.config.json'];
+    for (const file of assets) {
+      const srcPath = path.join(ragSrcDir, file);
+      const dstPath = path.join(ragDistDir, file);
+      try {
+        // Best-effort copy; skip if source asset does not exist.
+        await copyFile(srcPath, dstPath);
+      } catch {}
+    }
+  } catch {}
+
+  // Ensure compiled generated client is available at runtime import path (../generated/*)
+  await syncGeneratedRuntimeArtifacts();
+}
+
+main().catch((error) => {
+  console.error('[postbuild] Failed to normalize dist layout:', error);
+  process.exitCode = 1;
+});
+
+async function syncGeneratedRuntimeArtifacts() {
+  const distGenerated = path.join(distRoot, 'generated');
+  try {
+    const stats = await stat(distGenerated);
+    if (!stats.isDirectory()) return;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return;
+    throw err;
+  }
+
+  const projectRoot = path.resolve('.');
+  const runtimeGenerated = path.join(projectRoot, 'generated');
+
+  await copyGenerated(distGenerated, runtimeGenerated);
+  // Remove the dist/generated copy to avoid duplicate payload in packages
+  await rm(distGenerated, { recursive: true, force: true });
+}
+
+async function copyGenerated(srcDir, dstDir) {
+  await mkdir(dstDir, { recursive: true });
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(srcDir, entry.name);
+    const to = path.join(dstDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyGenerated(from, to);
+    } else if (entry.isFile()) {
+      // Preserve timestamps to avoid unnecessary rebuild churn; overwrite existing files.
+      await mkdir(path.dirname(to), { recursive: true });
+      await copyFile(from, to);
+    }
+  }
+}

package/scripts/prepare-release.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const run = (command, options = {}) => {
+  execSync(command, { stdio: 'inherit', ...options });
+};
+
+const updateJsonFile = async (relativePath, updater) => {
+  const filePath = path.resolve(relativePath);
+  const raw = await readFile(filePath, 'utf8');
+  const data = JSON.parse(raw);
+  const updated = await updater(data);
+  await writeFile(filePath, JSON.stringify(updated, null, 2) + '\n');
+};
+
+const usage = `Usage: npm run release:prepare -- <new-version|major|minor|patch>
+
+Examples:
+  npm run release:prepare -- 0.2.0
+  npm run release:prepare -- minor`;
+
+const arg = process.argv[2];
+if (!arg) {
+  console.error('Error: missing version argument.');
+  console.error(usage);
+  process.exit(1);
+}
+
+try {
+  run(`npm version ${arg} --no-git-tag-version`);
+} catch (error) {
+  console.error('npm version failed.');
+  process.exit(error.status || 1);
+}
+
+const pkgRaw = await readFile(path.resolve('package.json'), 'utf8');
+const pkg = JSON.parse(pkgRaw);
+const newVersion = pkg.version;
+
+await updateJsonFile('mcp.json', async (data) => ({
+  ...data,
+  version: newVersion,
+}));
+
+// Manifest generation removed (runtime discovery via MCP stdio)
+
+// Update CHANGELOG.md from commits since last tag using Conventional Commits subjects.
+try {
+  run(`node scripts/generate-changelog.mjs ${newVersion}`);
+} catch (e) {
+  console.warn('WARN: Failed to generate CHANGELOG.md. You can run it manually: npm run changelog:generate');
+}
+
+console.log(`Release metadata updated to ${newVersion}.`);
+console.log('Next steps: commit the changes, open a PR, and tag the merged commit.');

package/scripts/rag-rebuild.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { stat } from 'node:fs/promises';
+
+async function fileExists(p) {
+  try {
+    const s = await stat(p);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const projectRoot = path.resolve(here, '..');
+  const distEmbeddings = path.join(projectRoot, 'dist', 'rag', 'embeddings.js');
+  const distIndexer = path.join(projectRoot, 'dist', 'rag', 'indexer.js');
+
+  let LocalMiniHashEmbedding;
+  let buildAllIndexes;
+
+  if (await fileExists(distEmbeddings) && await fileExists(distIndexer)) {
+    const em = await import(pathToFileURL(distEmbeddings).href);
+    const ix = await import(pathToFileURL(distIndexer).href);
+    LocalMiniHashEmbedding = em.LocalMiniHashEmbedding;
+    buildAllIndexes = ix.buildAllIndexes;
+  } else {
+    // Fall back to TypeScript sources via ts-node when available
+    try {
+      await import('./register-ts-node.mjs');
+      const em = await import(pathToFileURL(path.join(projectRoot, 'src', 'rag', 'embeddings.ts')).href);
+      const ix = await import(pathToFileURL(path.join(projectRoot, 'src', 'rag', 'indexer.ts')).href);
+      LocalMiniHashEmbedding = em.LocalMiniHashEmbedding;
+      buildAllIndexes = ix.buildAllIndexes;
+    } catch (err) {
+      console.error('[rag-rebuild] Unable to load RAG modules from dist or src:', err);
+      process.exit(1);
+      return;
+    }
+  }
+
+  const dim = Number(process.env.RAG_EMBED_DIM ?? 384);
+  const model = new LocalMiniHashEmbedding(dim);
+  await buildAllIndexes({ model });
+  process.stdout.write('Rebuilt RAG embeddings.\n');
+}
+
+main().catch((error) => {
+  console.error('Failed to rebuild embeddings', error);
+  process.exit(1);
+});

package/scripts/register-ts-node.mjs

@@ -0,0 +1,6 @@
+import { register } from "node:module";
+
+// Register ts-node ESM loader using the recommended `register` API to avoid
+// the experimental loader warning shown during CI runs.
+const projectRootUrl = new URL("../", import.meta.url);
+register("ts-node/esm", projectRootUrl);

package/scripts/run-mcp-check.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Start a mock C64U server, point MCP at it, then launch MCP for a short time.
+# Usage: scripts/run-mcp-check.sh [local|npm] [duration_seconds]
+# - local: runs the local build (dist/index.js)
+# - npm:   runs the published package via npx (c64bridge)
+
+MODE="${1:-local}"
+DURATION="${2:-5}"
+LOGFILE="${LOGFILE:-mcp-server-$(date +%Y%m%d-%H%M%S).log}"
+
+ROOT_DIR=$(cd "$(dirname "$0")/.." && pwd)
+TMPDIR=$(mktemp -d)
+MOCK_INFO="$TMPDIR/mock-info.json"
+CFG_FILE="$TMPDIR/.c64bridge.json"
+
+cleanup() {
+  set +e
+  [[ -n "${MCP_PID:-}" ]] && kill -TERM "$MCP_PID" 2>/dev/null || true
+  [[ -n "${MOCK_PID:-}" ]] && kill -TERM "$MOCK_PID" 2>/dev/null || true
+  wait "$MCP_PID" 2>/dev/null || true
+  wait "$MOCK_PID" 2>/dev/null || true
+  rm -rf "$TMPDIR" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# 1) Start mock server and wait for baseUrl
+node "$ROOT_DIR/scripts/start-mock.mjs" "$MOCK_INFO" &
+MOCK_PID=$!
+
+for i in {1..50}; do
+  [[ -f "$MOCK_INFO" ]] && break
+  sleep 0.1
+done
+
+if [[ ! -f "$MOCK_INFO" ]]; then
+  echo "ERROR: mock info file was not created." >&2
+  exit 1
+fi
+
+BASE_URL=$(node -e "const fs=require('fs'); const p=process.argv[1]; const j=JSON.parse(fs.readFileSync(p,'utf8')); console.log(j.baseUrl || '');" "$MOCK_INFO")
+if [[ -z "$BASE_URL" ]]; then
+  echo "ERROR: mock baseUrl not found." >&2
+  exit 1
+fi
+
+HOST_VALUE=$(node -e "const { URL } = require('url'); const u = new URL(process.argv[1]); console.log(u.hostname);" "$BASE_URL")
+PORT_VALUE=$(node -e "const { URL } = require('url'); const u = new URL(process.argv[1]); console.log(u.port ? Number(u.port) : 80);" "$BASE_URL")
+
+# 2) Write MCP config pointing to mock
+cat >"$CFG_FILE" <<EOF
+{
+  "c64u": {
+    "host": "$HOST_VALUE",
+    "port": $PORT_VALUE
+  }
+}
+EOF
+export C64BRIDGE_CONFIG="$CFG_FILE"
+
+# 3) If local mode, verify package contents (spot checks, no duplicates)
+if [[ "$MODE" == "local" ]]; then
+  (cd "$ROOT_DIR" && node scripts/check-package.mjs)
+fi
+
+echo "==> Starting MCP server in '$MODE' mode for $DURATION seconds..."
+echo "==> Logs will be written to: $(realpath "$LOGFILE")"
+
+if [[ "$MODE" == "local" ]]; then
+  (cd "$ROOT_DIR" && npm run build)
+  VERSION=$(node -p "require('$ROOT_DIR/package.json').version")
+  echo "==> Running local build version $VERSION"
+  (cd "$ROOT_DIR" && node dist/index.js) 2>&1 | tee "$LOGFILE" &
+  MCP_PID=$!
+elif [[ "$MODE" == "npm" ]]; then
+  VERSION=$(npm view c64bridge version --silent || echo "unknown")
+  echo "==> Downloading c64bridge@$VERSION from npm registry..."
+  C64BRIDGE_CONFIG="$CFG_FILE" npx --yes c64bridge 2>&1 | tee "$LOGFILE" &
+  MCP_PID=$!
+else
+  echo "Usage: $0 [local|npm] [duration_seconds]" >&2
+  exit 1
+fi
+
+sleep "$DURATION"
+
+# Request graceful shutdown and collect exit
+if kill -TERM "$MCP_PID" 2>/dev/null; then
+  echo "==> Graceful shutdown requested."
+else
+  echo "==> Server already stopped."
+fi
+wait "$MCP_PID" 2>/dev/null || true
+
+# 4) Verify connectivity log
+if grep -q "Connectivity check succeeded" "$LOGFILE"; then
+  echo "==> Connectivity to mock confirmed: $BASE_URL"
+else
+  echo "ERROR: Connectivity check did not succeed. See logs: $LOGFILE" >&2
+  exit 1
+fi
+
+echo "==> Run complete. Logs saved to: $(realpath "$LOGFILE")"

package/scripts/run-tests.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DEFAULT_TARGET = "mock";
+
+let target = DEFAULT_TARGET;
+let explicitBaseUrl = null;
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const registerSpec = pathToFileURL(path.join(repoRoot, "scripts", "register-ts-node.mjs")).href;
+const nodeArgs = ["--import", registerSpec, "--test"];
+
+for (const arg of process.argv.slice(2)) {
+  if (arg === "--mock") {
+    target = "mock";
+    continue;
+  }
+
+  if (arg === "--real") {
+    target = "real";
+    continue;
+  }
+
+  if (arg.startsWith("--target=")) {
+    target = arg.split("=", 2)[1] ?? DEFAULT_TARGET;
+    continue;
+  }
+
+  if (arg.startsWith("--base-url=")) {
+    explicitBaseUrl = arg.split("=", 2)[1] ?? null;
+    continue;
+  }
+
+  nodeArgs.push(arg);
+}
+const defaultEmbeddingsDir = path.join(repoRoot, "artifacts", "test-embeddings");
+if (!fs.existsSync(defaultEmbeddingsDir)) {
+  fs.mkdirSync(defaultEmbeddingsDir, { recursive: true });
+}
+
+const env = {
+  ...process.env,
+  C64_TEST_TARGET: target,
+};
+
+if (!env.RAG_EMBEDDINGS_DIR) {
+  env.RAG_EMBEDDINGS_DIR = defaultEmbeddingsDir;
+}
+
+if (!env.NODE_TEST_DISABLE_WORKER_THREADS) {
+  env.NODE_TEST_DISABLE_WORKER_THREADS = "1";
+}
+
+if (explicitBaseUrl) {
+  env.C64_TEST_BASE_URL = explicitBaseUrl;
+}
+
+if (target === "real" && !env.C64_TEST_BASE_URL) {
+  env.C64_TEST_BASE_URL = resolveBaseUrlFromConfig() ?? "http://c64u";
+}
+
+const child = spawn(process.execPath, nodeArgs, {
+  stdio: "inherit",
+  env,
+});
+
+child.on("close", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+function resolveBaseUrlFromConfig() {
+  const configPathEnv = process.env.C64BRIDGE_CONFIG;
+  const homeConfig = os.homedir() ? path.join(os.homedir(), ".c64bridge.json") : null;
+  const repoConfig = path.join(repoRoot, ".c64bridge.json");
+
+  const candidates = [];
+  if (configPathEnv) candidates.push(configPathEnv);
+  if (homeConfig) candidates.push(homeConfig);
+  candidates.push(repoConfig);
+
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try {
+      const raw = JSON.parse(fs.readFileSync(candidate, "utf8"));
+      const baseUrl = resolveBaseUrlFromJson(raw);
+      if (baseUrl) return baseUrl;
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error) {
+        if (error.code === "ENOENT") continue;
+      }
+      // surface malformed JSON to aid debugging
+      console.warn(`[run-tests] Failed to read config at ${candidate}:`, error);
+    }
+  }
+  return null;
+}
+
+function resolveBaseUrlFromJson(raw) {
+  if (!raw || typeof raw !== "object") return null;
+
+  const c64u = raw.c64u && typeof raw.c64u === "object" ? raw.c64u : null;
+  if (c64u) {
+    const base = normaliseBaseUrlFromString(c64u.baseUrl);
+    if (base) return base;
+
+    const hostEntry = firstDefined(
+      stringIfSet(c64u.host),
+      stringIfSet(c64u.hostname),
+    );
+
+    const parsed = parseEndpoint(hostEntry);
+    const port = firstDefined(numberIfPort(c64u.port), parsed.port, DEFAULT_PORT);
+    if (parsed.hostname) {
+      return buildBaseUrl(parsed.hostname, port);
+    }
+  }
+
+  const legacyBase = normaliseBaseUrlFromString(raw.baseUrl);
+  if (legacyBase) return legacyBase;
+
+  const legacyHost = stringIfSet(raw.c64_host) ?? stringIfSet(raw.c64_ip);
+  if (legacyHost) {
+    const parsed = parseEndpoint(legacyHost);
+    const port = firstDefined(parsed.port, DEFAULT_PORT);
+    const hostname = parsed.hostname ?? legacyHost;
+    return buildBaseUrl(hostname, port);
+  }
+
+  return null;
+}
+
+function stringIfSet(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function numberIfPort(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value.trim());
+    if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) {
+      return parsed;
+    }
+  }
+  return null;
+}
+
+function normaliseBaseUrlFromString(value) {
+  const input = stringIfSet(value);
+  if (!input) return null;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
+    return `http://${input}`;
+  }
+  return input.replace(/\/+$/, "");
+}
+
+function parseEndpoint(value) {
+  const input = stringIfSet(value);
+  if (!input) return {};
+  try {
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(input);
+    const url = new URL(hasScheme ? input : `http://${input}`);
+    const hostname = url.hostname || undefined;
+    const port = url.port ? numberIfPort(url.port) : undefined;
+    return { hostname, port };
+  } catch {
+    return {};
+  }
+}
+
+const DEFAULT_PORT = 80;
+
+function buildBaseUrl(host, port) {
+  const normalizedPort = Number.isInteger(port) && port > 0 ? port : DEFAULT_PORT;
+  const hostPart = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  const suffix = normalizedPort === DEFAULT_PORT ? "" : `:${normalizedPort}`;
+  return `http://${hostPart}${suffix}`;
+}
+
+function firstDefined(...values) {
+  for (const value of values) {
+    if (value !== undefined && value !== null) {
+      return value;
+    }
+  }
+  return undefined;
+}