@gmickel/gno 0.3.0

package/src/llm/nodeLlamaCpp/rerank.ts

@@ -0,0 +1,94 @@
+/**
+ * Rerank port implementation using node-llama-cpp.
+ *
+ * @module src/llm/nodeLlamaCpp/rerank
+ */
+
+import { inferenceFailedError } from '../errors';
+import type { LlmResult, RerankPort, RerankScore } from '../types';
+import type { ModelManager } from './lifecycle';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+type LlamaModel = Awaited<
+  ReturnType<
+    Awaited<ReturnType<typeof import('node-llama-cpp').getLlama>>['loadModel']
+  >
+>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class NodeLlamaCppRerank implements RerankPort {
+  private readonly manager: ModelManager;
+  readonly modelUri: string;
+  private readonly modelPath: string;
+
+  constructor(manager: ModelManager, modelUri: string, modelPath: string) {
+    this.manager = manager;
+    this.modelUri = modelUri;
+    this.modelPath = modelPath;
+  }
+
+  async rerank(
+    query: string,
+    documents: string[]
+  ): Promise<LlmResult<RerankScore[]>> {
+    if (documents.length === 0) {
+      return { ok: true, value: [] };
+    }
+
+    const model = await this.manager.loadModel(
+      this.modelPath,
+      this.modelUri,
+      'rerank'
+    );
+    if (!model.ok) {
+      return model;
+    }
+
+    // Build index map for O(1) lookups (handles duplicates correctly)
+    const indexMap = new Map<string, number[]>();
+    for (let i = 0; i < documents.length; i += 1) {
+      const doc = documents[i] as string; // Guaranteed by loop bounds
+      const indices = indexMap.get(doc) ?? [];
+      indices.push(i);
+      indexMap.set(doc, indices);
+    }
+
+    const llamaModel = model.value.model as LlamaModel;
+    const context = await llamaModel.createRankingContext();
+
+    try {
+      const ranked = await context.rankAndSort(query, documents);
+
+      // Convert to RerankScore format with O(1) index lookup
+      const scores: RerankScore[] = ranked.map((item, rank) => {
+        const indices = indexMap.get(item.document) ?? [];
+        // Shift to handle duplicates (each duplicate gets next index)
+        const index = indices.shift() ?? -1;
+        return {
+          index,
+          score: item.score,
+          rank: rank + 1,
+        };
+      });
+
+      return { ok: true, value: scores };
+    } catch (e) {
+      return { ok: false, error: inferenceFailedError(this.modelUri, e) };
+    } finally {
+      await context.dispose().catch(() => {
+        // Ignore disposal errors
+      });
+    }
+  }
+
+  async dispose(): Promise<void> {
+    // Rerank doesn't hold persistent context
+    // Model cleanup is handled by ModelManager
+  }
+}

package/src/llm/registry.ts

@@ -0,0 +1,86 @@
+/**
+ * Model preset registry.
+ * Resolves active preset and model URIs from config.
+ *
+ * @module src/llm/registry
+ */
+
+import type { Config, ModelConfig, ModelPreset } from '../config/types';
+import { DEFAULT_MODEL_PRESETS } from '../config/types';
+import type { ModelType } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get model config with defaults.
+ */
+export function getModelConfig(config: Config): ModelConfig {
+  return {
+    activePreset: config.models?.activePreset ?? 'balanced',
+    presets: config.models?.presets ?? DEFAULT_MODEL_PRESETS,
+    loadTimeout: config.models?.loadTimeout ?? 60_000,
+    inferenceTimeout: config.models?.inferenceTimeout ?? 30_000,
+    warmModelTtl: config.models?.warmModelTtl ?? 300_000,
+  };
+}
+
+/**
+ * Get the active preset from config.
+ * Falls back to first preset if active not found.
+ */
+export function getActivePreset(config: Config): ModelPreset {
+  const modelConfig = getModelConfig(config);
+  const presetId = modelConfig.activePreset;
+  const preset = modelConfig.presets.find((p) => p.id === presetId);
+
+  if (preset) {
+    return preset;
+  }
+
+  // Fallback to first preset
+  const fallback = modelConfig.presets[0];
+  if (fallback) {
+    return fallback;
+  }
+
+  // Return built-in default (guaranteed to exist)
+  const builtIn = DEFAULT_MODEL_PRESETS[0];
+  if (!builtIn) {
+    throw new Error('No default model presets configured');
+  }
+  return builtIn;
+}
+
+/**
+ * Resolve a model URI for a given type.
+ * Uses override if provided, otherwise from active preset.
+ */
+export function resolveModelUri(
+  config: Config,
+  type: ModelType,
+  override?: string
+): string {
+  if (override) {
+    return override;
+  }
+  const preset = getActivePreset(config);
+  return preset[type];
+}
+
+/**
+ * List all available presets.
+ */
+export function listPresets(config: Config): ModelPreset[] {
+  const modelConfig = getModelConfig(config);
+  return modelConfig.presets;
+}
+
+/**
+ * Get a specific preset by ID.
+ */
+export function getPreset(config: Config, id: string): ModelPreset | undefined {
+  const modelConfig = getModelConfig(config);
+  return modelConfig.presets.find((p) => p.id === id);
+}

package/src/llm/types.ts

@@ -0,0 +1,129 @@
+/**
+ * LLM subsystem types.
+ * Port interfaces for embedding, generation, and reranking.
+ *
+ * @module src/llm/types
+ */
+
+import type { LlmError } from './errors';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Result Type
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type LlmResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: LlmError };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Model Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ModelType = 'embed' | 'rerank' | 'gen';
+
+/** Model URI format: hf:org/repo/file.gguf or file:/path */
+export type ModelUri = string;
+
+// ModelPreset is defined in config/types.ts (source of truth)
+// Re-exported from index.ts for convenience
+
+export interface ModelCacheEntry {
+  uri: ModelUri;
+  type: ModelType;
+  path: string;
+  size: number;
+  checksum: string;
+  cachedAt: string;
+}
+
+export interface ModelStatus {
+  uri: ModelUri;
+  cached: boolean;
+  path: string | null;
+  size?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generation Parameters
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GenParams {
+  /** Temperature (0 = deterministic). Default: 0 */
+  temperature?: number;
+  /** Random seed for reproducibility. Default: 42 */
+  seed?: number;
+  /** Max tokens to generate. Default: 256 */
+  maxTokens?: number;
+  /** Stop sequences */
+  stop?: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rerank Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RerankScore {
+  /** Original index in input array */
+  index: number;
+  /** Relevance score (higher = more relevant) */
+  score: number;
+  /** Rank position (1 = best) */
+  rank: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Port Interfaces
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EmbeddingPort {
+  readonly modelUri: string;
+  /** Initialize the embedding context (loads model). Call before dimensions(). */
+  init(): Promise<LlmResult<void>>;
+  embed(text: string): Promise<LlmResult<number[]>>;
+  embedBatch(texts: string[]): Promise<LlmResult<number[][]>>;
+  /** Returns embedding dimensions. Must call init() first. */
+  dimensions(): number;
+  dispose(): Promise<void>;
+}
+
+export interface GenerationPort {
+  readonly modelUri: string;
+  generate(prompt: string, params?: GenParams): Promise<LlmResult<string>>;
+  dispose(): Promise<void>;
+}
+
+export interface RerankPort {
+  readonly modelUri: string;
+  rerank(query: string, documents: string[]): Promise<LlmResult<RerankScore[]>>;
+  dispose(): Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Loaded Model (internal)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LoadedModel {
+  uri: ModelUri;
+  type: ModelType;
+  model: unknown; // LlamaModel from node-llama-cpp
+  loadedAt: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ModelConfig is defined in config/types.ts (source of truth)
+// Re-exported from index.ts for convenience
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Progress Callback
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DownloadProgress {
+  downloadedBytes: number;
+  totalBytes: number;
+  percent: number;
+}
+
+export type ProgressCallback = (progress: DownloadProgress) => void;

package/src/mcp/resources/index.ts

@@ -0,0 +1,151 @@
+/**
+ * MCP resource registration for gno:// URIs.
+ *
+ * @module src/mcp/resources
+ */
+
+import { join as pathJoin } from 'node:path';
+import {
+  type McpServer,
+  ResourceTemplate,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { buildUri, parseUri, URI_PREFIX } from '../../app/constants';
+import type { DocumentRow } from '../../store/types';
+import type { ToolContext } from '../server';
+
+/**
+ * Format document content with header comment and line numbers.
+ */
+function formatResourceContent(
+  doc: DocumentRow,
+  content: string,
+  ctx: ToolContext
+): string {
+  // Find collection for absPath
+  const uriParsed = parseUri(doc.uri);
+  let absPath = doc.relPath;
+  if (uriParsed) {
+    const collection = ctx.collections.find(
+      (c) => c.name === uriParsed.collection
+    );
+    if (collection) {
+      absPath = pathJoin(collection.path, doc.relPath);
+    }
+  }
+
+  // Header comment per spec (includes language if available)
+  const langLine = doc.languageHint
+    ? `\n     language: ${doc.languageHint}`
+    : '';
+  const header = `<!-- ${doc.uri}
+     docid: ${doc.docid}
+     source: ${absPath}
+     mime: ${doc.sourceMime}${langLine}
+-->
+
+`;
+
+  // Line numbers per spec (default ON for agent friendliness)
+  const lines = content.split('\n');
+  const numbered = lines.map((line, i) => `${i + 1}: ${line}`).join('\n');
+
+  return header + numbered;
+}
+
+/**
+ * Register gno:// resources with the MCP server.
+ */
+export function registerResources(server: McpServer, ctx: ToolContext): void {
+  // Resource template for gno://{collection}/{path} URIs
+  const template = new ResourceTemplate(`${URI_PREFIX}{collection}/{+path}`, {
+    list: async () => {
+      // List all documents as resources
+      const listResult = await ctx.store.listDocuments();
+      if (!listResult.ok) {
+        return { resources: [] };
+      }
+
+      return {
+        resources: listResult.value.map((doc) => ({
+          uri: doc.uri,
+          name: doc.relPath,
+          mimeType: doc.sourceMime || 'text/markdown',
+          description: doc.title ?? undefined,
+        })),
+      };
+    },
+  });
+
+  // Register the template-based resource handler
+  server.resource('gno-document', template, {}, async (uri, _variables) => {
+    // Check shutdown before acquiring mutex
+    if (ctx.isShuttingDown()) {
+      throw new Error('Server is shutting down');
+    }
+
+    // Serialize resource reads same as tools (prevent concurrent DB access + shutdown race)
+    const release = await ctx.toolMutex.acquire();
+    try {
+      // Use parseUri for proper URL decoding (handles %20, etc.)
+      const parsed = parseUri(uri.href);
+      if (!parsed) {
+        throw new Error(`Invalid gno:// URI: ${uri.href}`);
+      }
+
+      const { collection, path } = parsed;
+
+      // Validate collection exists
+      const collectionExists = ctx.collections.some(
+        (c) => c.name === collection
+      );
+      if (!collectionExists) {
+        throw new Error(`Collection not found: ${collection}`);
+      }
+
+      // Look up document (path is properly decoded by parseUri)
+      const docResult = await ctx.store.getDocument(collection, path);
+      if (!docResult.ok) {
+        throw new Error(
+          `Failed to lookup document: ${docResult.error.message}`
+        );
+      }
+
+      const doc = docResult.value;
+      if (!doc) {
+        throw new Error(`Document not found: ${uri.href}`);
+      }
+
+      // Get content
+      if (!doc.mirrorHash) {
+        throw new Error(`Document has no indexed content: ${uri.href}`);
+      }
+
+      const contentResult = await ctx.store.getContent(doc.mirrorHash);
+      if (!contentResult.ok) {
+        throw new Error(
+          `Failed to read content: ${contentResult.error.message}`
+        );
+      }
+
+      const content = contentResult.value ?? '';
+
+      // Format with header and line numbers
+      const formattedContent = formatResourceContent(doc, content, ctx);
+
+      // Build canonical URI
+      const canonicalUri = buildUri(collection, path);
+
+      return {
+        contents: [
+          {
+            uri: canonicalUri,
+            mimeType: 'text/markdown',
+            text: formattedContent,
+          },
+        ],
+      };
+    } finally {
+      release();
+    }
+  });
+}

package/src/mcp/server.ts

@@ -0,0 +1,229 @@
+/**
+ * MCP Server implementation for GNO.
+ * Exposes search, retrieval, and status tools over stdio transport.
+ *
+ * @module src/mcp/server
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { MCP_SERVER_NAME, VERSION } from '../app/constants';
+import type { Collection, Config } from '../config/types';
+import type { SqliteAdapter } from '../store/sqlite/adapter';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Simple Promise Mutex (avoids async-mutex dependency)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Mutex {
+  #locked = false;
+  readonly #queue: Array<() => void> = [];
+
+  acquire(): Promise<() => void> {
+    return new Promise((resolve) => {
+      const tryAcquire = () => {
+        if (this.#locked) {
+          this.#queue.push(tryAcquire);
+        } else {
+          this.#locked = true;
+          resolve(() => this.#release());
+        }
+      };
+      tryAcquire();
+    });
+  }
+
+  #release(): void {
+    this.#locked = false;
+    const next = this.#queue.shift();
+    if (next) {
+      next();
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Context
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ToolContext {
+  store: SqliteAdapter;
+  config: Config;
+  collections: Collection[];
+  actualConfigPath: string;
+  toolMutex: Mutex;
+  isShuttingDown: () => boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Server Options
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface McpServerOptions {
+  indexName?: string;
+  configPath?: string;
+  verbose?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Server Lifecycle
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function startMcpServer(options: McpServerOptions): Promise<void> {
+  // ========================================
+  // STDOUT PURITY GUARD (CRITICAL)
+  // ========================================
+  // Wrap stdout to catch accidental writes during init
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  let protocolMode = false;
+
+  // Stdout wrapper - redirect to stderr during init
+  // biome-ignore lint/suspicious/noExplicitAny: overloaded write signature
+  (process.stdout as any).write = (
+    chunk: string | Uint8Array,
+    encodingOrCb?: BufferEncoding | ((err?: Error | null) => void),
+    cb?: (err?: Error | null) => void
+  ): boolean => {
+    if (!protocolMode) {
+      // During init, redirect to stderr
+      if (typeof encodingOrCb === 'function') {
+        return process.stderr.write(chunk, encodingOrCb);
+      }
+      return process.stderr.write(chunk, encodingOrCb, cb);
+    }
+    // After transport connected, allow JSON-RPC only
+    if (typeof encodingOrCb === 'function') {
+      return originalStdoutWrite(chunk, encodingOrCb);
+    }
+    return originalStdoutWrite(chunk, encodingOrCb, cb);
+  };
+
+  // Lazy import to avoid pulling in all deps on --help
+  const { initStore } = await import('../cli/commands/shared.js');
+
+  // Open DB once with index/config threading
+  const init = await initStore({
+    indexName: options.indexName,
+    configPath: options.configPath,
+  });
+
+  if (!init.ok) {
+    console.error('Failed to initialize:', init.error);
+    process.exit(1);
+  }
+
+  const { store, config, collections, actualConfigPath } = init;
+
+  // Create MCP server
+  const server = new McpServer(
+    {
+      name: MCP_SERVER_NAME,
+      version: VERSION,
+    },
+    {
+      capabilities: {
+        tools: { listChanged: false },
+        resources: { subscribe: false, listChanged: false },
+      },
+    }
+  );
+
+  // Sequential execution mutex
+  const toolMutex = new Mutex();
+
+  // Shutdown state
+  let shuttingDown = false;
+
+  // Tool context (passed to all handlers)
+  const ctx: ToolContext = {
+    store,
+    config,
+    collections,
+    actualConfigPath,
+    toolMutex,
+    isShuttingDown: () => shuttingDown,
+  };
+
+  // Register tools (T10.2)
+  const { registerTools } = await import('./tools/index.js');
+  registerTools(server, ctx);
+
+  // Register resources (T10.3)
+  const { registerResources } = await import('./resources/index.js');
+  registerResources(server, ctx);
+
+  if (options.verbose) {
+    console.error(
+      `[MCP] Loaded ${ctx.collections.length} collections from ${ctx.actualConfigPath}`
+    );
+  }
+
+  // ========================================
+  // GRACEFUL SHUTDOWN (ordered)
+  // ========================================
+  const shutdown = async () => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+
+    console.error('[MCP] Shutting down...');
+
+    // 1. Wait for current handler (no timeout - correctness over speed)
+    // If we timeout and close DB while tool is running, we risk corruption
+    const release = await toolMutex.acquire();
+    release();
+
+    // 2. Close MCP server/transport (flush buffers, clean disconnect)
+    try {
+      await server.close();
+    } catch {
+      // Best-effort - server may already be closed
+    }
+
+    // 3. Close DB (safe now - no tool is running)
+    await store.close();
+
+    // 4. Exit
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  // ========================================
+  // CONSOLE REDIRECT (CRITICAL for stdout purity)
+  // ========================================
+  // Redirect console.log/info/debug/warn to stderr to prevent JSON-RPC corruption
+  // Save originals (prefixed with _ to indicate intentionally unused)
+  const _origLog = console.log;
+  const _origInfo = console.info;
+  const _origDebug = console.debug;
+  const _origWarn = console.warn;
+  console.log = (...args: unknown[]) => console.error('[log]', ...args);
+  console.info = (...args: unknown[]) => console.error('[info]', ...args);
+  console.debug = (...args: unknown[]) => console.error('[debug]', ...args);
+  console.warn = (...args: unknown[]) => console.error('[warn]', ...args);
+
+  // Connect transport
+  const transport = new StdioServerTransport();
+  protocolMode = true; // Enable stdout for JSON-RPC
+
+  await server.connect(transport);
+
+  console.error(`[MCP] ${MCP_SERVER_NAME} v${VERSION} ready on stdio`);
+
+  // Block forever until shutdown signal or stdin closes
+  // This prevents the CLI from exiting after startMcpServer() returns
+  await new Promise<void>((resolve) => {
+    process.stdin.on('end', () => {
+      console.error('[MCP] stdin ended');
+      resolve();
+    });
+    process.stdin.on('close', () => {
+      console.error('[MCP] stdin closed');
+      resolve();
+    });
+    // Also resolve on SIGTERM/SIGINT (already handled by shutdown())
+  });
+}