optave-codegraph 3.13.0

package/src/infrastructure/update-check.ts

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+
+const CACHE_PATH: string =
+  process.env.CODEGRAPH_UPDATE_CACHE_PATH ||
+  path.join(os.homedir(), '.codegraph', 'update-check.json');
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const FETCH_TIMEOUT_MS = 3000;
+const REGISTRY_URL = 'https://registry.npmjs.org/optave-codegraph/latest';
+
+interface UpdateCache {
+  lastCheckedAt: number;
+  latestVersion: string;
+}
+
+/**
+ * Minimal semver comparison. Returns -1, 0, or 1.
+ * Strips pre-release suffixes (e.g. "3.9.3-dev.6" → "3.9.3") before comparing.
+ */
+export function semverCompare(a: string, b: string): -1 | 0 | 1 {
+  const pa = a.replace(/-.*$/, '').split('.').map(Number);
+  const pb = b.replace(/-.*$/, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Load the cached update-check result from disk.
+ * Returns null on missing or corrupt file.
+ */
+function loadCache(cachePath: string = CACHE_PATH): UpdateCache | null {
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data.lastCheckedAt !== 'number' || typeof data.latestVersion !== 'string') {
+      return null;
+    }
+    return data as UpdateCache;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the cache to disk (atomic write via temp + rename).
+ */
+function saveCache(cache: UpdateCache, cachePath: string = CACHE_PATH): void {
+  const dir = path.dirname(cachePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const tmp = `${cachePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(cache), 'utf-8');
+  fs.renameSync(tmp, cachePath);
+}
+
+/**
+ * Collect the full response body from an IncomingMessage stream.
+ * Resolves with the body string, or null on parse/status error.
+ */
+function collectResponseBody(res: import('node:http').IncomingMessage): Promise<string | null> {
+  return new Promise((resolve) => {
+    if (res.statusCode !== 200) {
+      res.resume();
+      resolve(null);
+      return;
+    }
+    let body = '';
+    res.setEncoding('utf-8');
+    res.on('data', (chunk: string) => {
+      body += chunk;
+    });
+    res.on('end', () => {
+      try {
+        const data = JSON.parse(body);
+        resolve(typeof data.version === 'string' ? data.version : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+
+/**
+ * Fetch the latest version string from the npm registry.
+ * Returns the version string or null on failure.
+ */
+function fetchLatestVersion(): Promise<string | null> {
+  return new Promise((resolve) => {
+    const req = https.get(
+      REGISTRY_URL,
+      { timeout: FETCH_TIMEOUT_MS, headers: { Accept: 'application/json' } },
+      (res) => {
+        collectResponseBody(res).then(resolve);
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+interface UpdateResult {
+  current: string;
+  latest: string;
+}
+
+interface CheckForUpdatesOptions {
+  cachePath?: string;
+  _fetchLatest?: () => Promise<string | null>;
+}
+
+/**
+ * Return the latest version from cache if fresh, or fetch it from the registry.
+ * Persists the fetched version to the cache only when a network fetch occurs
+ * (i.e. the cache is stale or missing). Returns the cached value directly
+ * without updating the cache when the cache is still within `CACHE_TTL_MS`.
+ * Returns null when the network fetch fails or the cache is corrupt.
+ */
+async function resolveLatestVersion(
+  cachePath: string,
+  fetchFn: () => Promise<string | null>,
+): Promise<string | null> {
+  const cache = loadCache(cachePath);
+
+  if (cache && Date.now() - cache.lastCheckedAt < CACHE_TTL_MS) {
+    // Cache is fresh — use stored value directly
+    return cache.latestVersion;
+  }
+
+  // Cache is stale or missing — fetch from registry
+  const latest = await fetchFn();
+  if (!latest) return null;
+
+  saveCache({ lastCheckedAt: Date.now(), latestVersion: latest }, cachePath);
+  return latest;
+}
+
+/**
+ * Check whether a newer version of codegraph is available.
+ *
+ * Returns `{ current, latest }` if an update is available, `null` otherwise.
+ * Silently returns null on any error — never affects CLI operation.
+ */
+export async function checkForUpdates(
+  currentVersion: string,
+  options: CheckForUpdatesOptions = {},
+): Promise<UpdateResult | null> {
+  // Suppress in non-interactive / CI contexts
+  if (process.env.CI) return null;
+  if (process.env.NO_UPDATE_CHECK) return null;
+  if (!process.stderr.isTTY) return null;
+  if (currentVersion.includes('-')) return null;
+
+  const cachePath = options.cachePath || CACHE_PATH;
+  const fetchFn = options._fetchLatest || fetchLatestVersion;
+
+  try {
+    const latest = await resolveLatestVersion(cachePath, fetchFn);
+    if (!latest) return null;
+
+    if (semverCompare(currentVersion, latest) < 0) {
+      return { current: currentVersion, latest };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Print a visible update notification box to stderr.
+ */
+export function printUpdateNotification(current: string, latest: string): void {
+  const msg1 = `Update available: ${current} → ${latest}`;
+  const msg2 = 'Run `npm i -g optave-codegraph` to update';
+  const width = Math.max(msg1.length, msg2.length) + 4;
+
+  const top = `┌${'─'.repeat(width)}┐`;
+  const bot = `└${'─'.repeat(width)}┘`;
+  const pad1 = ' '.repeat(width - msg1.length - 2);
+  const pad2 = ' '.repeat(width - msg2.length - 2);
+  const line1 = `│  ${msg1}${pad1}│`;
+  const line2 = `│  ${msg2}${pad2}│`;
+
+  process.stderr.write(`\n${top}\n${line1}\n${line2}\n${bot}\n\n`);
+}

package/src/mcp/index.ts

@@ -0,0 +1,2 @@
+export { startMCPServer } from './server.js';
+export { buildToolList, TOOLS } from './tool-registry.js';

package/src/mcp/middleware.ts

@@ -0,0 +1,38 @@
+/**
+ * MCP middleware helpers — pagination defaults and limits.
+ */
+
+import { getMcpDefaults, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
+
+export { MCP_DEFAULTS, MCP_MAX_LIMIT };
+
+/** Resolved MCP defaults (may include config overrides). Set via initMcpDefaults(). */
+let resolvedDefaults: Record<string, number> = MCP_DEFAULTS;
+
+/**
+ * Initialize MCP defaults from config. Call once at server startup.
+ */
+export function initMcpDefaults(configMcpDefaults?: Record<string, number>): void {
+  resolvedDefaults = getMcpDefaults(configMcpDefaults) as Record<string, number>;
+}
+
+/**
+ * Reset MCP defaults back to the base defaults. Useful for test isolation.
+ */
+export function resetMcpDefaults(): void {
+  resolvedDefaults = MCP_DEFAULTS;
+}
+
+/**
+ * Resolve effective limit for a tool call.
+ */
+export function effectiveLimit(args: { limit?: number }, toolName: string): number {
+  return Math.min(args.limit ?? resolvedDefaults[toolName] ?? 100, MCP_MAX_LIMIT);
+}
+
+/**
+ * Resolve effective offset for a tool call.
+ */
+export function effectiveOffset(args: { offset?: number }): number {
+  return args.offset ?? 0;
+}

package/src/mcp/server.ts

@@ -0,0 +1,259 @@
+/**
+ * MCP (Model Context Protocol) server for codegraph.
+ * Exposes codegraph queries as tools that AI coding assistants can call.
+ *
+ * Requires: npm install @modelcontextprotocol/sdk
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../../package.json') as { version: string };
+
+import { getDatabase } from '../db/better-sqlite3.js';
+import { findDbPath } from '../db/index.js';
+import { loadConfig } from '../infrastructure/config.js';
+import { debug } from '../infrastructure/logger.js';
+import { CodegraphError, ConfigError, toErrorMessage } from '../shared/errors.js';
+import { MCP_MAX_LIMIT } from '../shared/paginate.js';
+import type { CodegraphConfig, MCPServerOptions } from '../types.js';
+import { initMcpDefaults } from './middleware.js';
+import { buildToolList } from './tool-registry.js';
+import { TOOL_HANDLERS } from './tools/index.js';
+import type { McpToolContext } from './types.js';
+
+/**
+ * Module-level guard to register shutdown handlers only once per process.
+ * Because tests use vi.resetModules(), this module-level variable resets
+ * on each re-import — but the process-level flag on `process` persists.
+ */
+let _activeServer: any = null;
+
+export type { McpToolContext };
+
+interface MCPServerOptionsInternal extends MCPServerOptions {
+  config?: CodegraphConfig;
+}
+
+async function loadMCPSdk(): Promise<{
+  Server: unknown;
+  StdioServerTransport: unknown;
+  ListToolsRequestSchema: unknown;
+  CallToolRequestSchema: unknown;
+}> {
+  try {
+    const sdk = await import('@modelcontextprotocol/sdk/server/index.js');
+    const transport = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const types = await import('@modelcontextprotocol/sdk/types.js');
+    return {
+      Server: sdk.Server,
+      StdioServerTransport: transport.StdioServerTransport,
+      ListToolsRequestSchema: types.ListToolsRequestSchema,
+      CallToolRequestSchema: types.CallToolRequestSchema,
+    };
+  } catch (e) {
+    debug(`MCP SDK import failed: ${toErrorMessage(e)}`);
+    throw new ConfigError(
+      'MCP server requires @modelcontextprotocol/sdk.\nInstall it with: npm install @modelcontextprotocol/sdk',
+    );
+  }
+}
+
+function createLazyLoaders(): {
+  getQueries(): Promise<unknown>;
+} {
+  let _queries: unknown;
+  return {
+    async getQueries(): Promise<unknown> {
+      if (!_queries) _queries = await import('../domain/queries.js');
+      return _queries;
+    },
+  };
+}
+
+async function resolveDbPath(
+  customDbPath: string | undefined,
+  args: { repo?: string },
+  allowedRepos?: string[],
+): Promise<string | undefined> {
+  let dbPath = customDbPath || undefined;
+  if (args.repo) {
+    if (allowedRepos && !allowedRepos.includes(args.repo)) {
+      throw new ConfigError(`Repository "${args.repo}" is not in the allowed repos list.`);
+    }
+    const { resolveRepoDbPath } = await import('../infrastructure/registry.js');
+    const resolved = resolveRepoDbPath(args.repo);
+    if (!resolved)
+      throw new ConfigError(
+        `Repository "${args.repo}" not found in registry or its database is missing.`,
+      );
+    dbPath = resolved;
+  }
+  return dbPath;
+}
+
+function validateMultiRepoAccess(multiRepo: boolean, args: { repo?: string }): void {
+  if (!multiRepo && args.repo) {
+    throw new ConfigError(
+      'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
+    );
+  }
+  // Note: the `list_repos` tool is excluded from `enabledToolNames` when
+  // `multiRepo` is false (see `buildToolList`), so any call to it is rejected
+  // earlier in `createCallToolHandler` with an "Unknown tool" error.
+}
+
+/**
+ * Register process-level shutdown and error handlers once per process.
+ * Ensures graceful cleanup when the MCP client disconnects or the transport
+ * encounters broken-pipe errors. Uses a globalThis flag to survive
+ * vi.resetModules() in tests.
+ */
+function registerShutdownHandlers(): void {
+  const g = globalThis as Record<string, unknown>;
+  if (g.__codegraph_shutdown_installed) return;
+  g.__codegraph_shutdown_installed = true;
+
+  const shutdown = async () => {
+    try {
+      await _activeServer?.close();
+    } catch (shutdownErr: unknown) {
+      debug(
+        `MCP shutdown close failed (transport may already be gone): ${toErrorMessage(shutdownErr)}`,
+      );
+    }
+    process.exit(0);
+  };
+  const silentExit = (err: Error & { code?: string }) => {
+    // Only suppress broken-pipe errors from closed stdio transport;
+    // let real bugs surface with a non-zero exit code.
+    if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
+      process.exit(0);
+    }
+    process.stderr.write(`Uncaught exception: ${err.stack ?? err.message}\n`);
+    process.exit(1);
+  };
+  const silentReject = (reason: unknown) => {
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    const code = (err as Error & { code?: string }).code;
+    if (code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED') {
+      process.exit(0);
+    }
+    process.stderr.write(`Unhandled rejection: ${err.stack ?? err.message}\n`);
+    process.exit(1);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  process.on('SIGHUP', shutdown);
+  process.on('uncaughtException', silentExit);
+  process.on('unhandledRejection', silentReject);
+}
+
+function createCallToolHandler(
+  multiRepo: boolean,
+  customDbPath: string | undefined,
+  allowedRepos: string[] | undefined,
+  getQueries: () => Promise<unknown>,
+  enabledToolNames: Set<string>,
+) {
+  return async (request: any) => {
+    const { name, arguments: args } = request.params;
+    try {
+      if (!enabledToolNames.has(name)) {
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+      }
+
+      validateMultiRepoAccess(multiRepo, args);
+
+      const dbPath = await resolveDbPath(customDbPath, args, allowedRepos);
+
+      const toolEntry = TOOL_HANDLERS.get(name);
+      if (!toolEntry) {
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+      }
+
+      const ctx: McpToolContext = {
+        dbPath: dbPath,
+        getQueries,
+        getDatabase,
+        findDbPath,
+        allowedRepos,
+        MCP_MAX_LIMIT,
+      };
+      const result: unknown = await toolEntry.handler(args, ctx);
+      if (result && typeof result === 'object' && 'content' in result) {
+        return result as { content: Array<{ type: string; text: string }> };
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err: unknown) {
+      const code = err instanceof CodegraphError ? err.code : 'UNKNOWN_ERROR';
+      const text =
+        err instanceof CodegraphError
+          ? `[${code}] ${err.message}`
+          : `Error: ${toErrorMessage(err)}`;
+      return { content: [{ type: 'text', text }], isError: true };
+    }
+  };
+}
+
+export async function startMCPServer(
+  customDbPath?: string,
+  options: MCPServerOptionsInternal = {},
+): Promise<void> {
+  const { allowedRepos } = options;
+  const multiRepo = options.multiRepo || !!allowedRepos;
+
+  // Apply config-based MCP page-size overrides
+  const config = options.config || loadConfig();
+  initMcpDefaults(config.mcp?.defaults ? { ...config.mcp.defaults } : undefined);
+  const disabledTools = [...(config.mcp?.disabledTools ?? [])];
+  const enabledTools = buildToolList(multiRepo, disabledTools);
+  const enabledToolNames = new Set(enabledTools.map((tool) => tool.name));
+
+  const { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } =
+    await loadMCPSdk();
+
+  // Connect transport FIRST so the server can receive the client's
+  // `initialize` request while heavy modules (queries, better-sqlite3)
+  // are still loading.  These are lazy-loaded on the first tool call
+  // and cached for subsequent calls.
+  const { getQueries } = createLazyLoaders();
+
+  const server = new (Server as any)(
+    { name: 'codegraph', version: PKG_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: enabledTools,
+  }));
+
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    createCallToolHandler(multiRepo, customDbPath, allowedRepos, getQueries, enabledToolNames),
+  );
+
+  const transport = new (StdioServerTransport as any)();
+
+  // Graceful shutdown — when the client disconnects (e.g. session clear),
+  // close the server cleanly so the process exits without error.
+  // Track the active server at module level so handlers always reference
+  // the latest instance (matters when tests call startMCPServer repeatedly).
+  _activeServer = server;
+
+  registerShutdownHandlers();
+
+  try {
+    await server.connect(transport);
+  } catch (err) {
+    const code = (err as Error & { code?: string }).code;
+    if (code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED') {
+      process.exit(0);
+    }
+    process.stderr.write(
+      `MCP transport connect failed: ${err instanceof Error ? (err.stack ?? err.message) : toErrorMessage(err)}\n`,
+    );
+    process.exit(1);
+  }
+}