@pruddiman/hem 0.0.1-beta-5671db0

package/dist/providers/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Provider abstraction layer type definitions for Hem.
+ *
+ * Defines the {@link Provider} interface that all LLM provider
+ * implementations must satisfy, the {@link ProviderConfig} configuration
+ * type, and the {@link SseEvent} type used by the SSE relay.
+ *
+ * Aligns with Dispatch's `ProviderInstance` pattern:
+ *   - `createSession()` — create an isolated session, returns session ID
+ *   - `prompt(sessionId, text)` — send a prompt and wait for completion
+ *   - `cleanup()` — tear down the provider
+ *
+ * Also exposes low-level `session` and `event` properties for agents that
+ * need direct session control (OrganizationAgent, CrossRefAgent, etc.).
+ */
+import type { SseEvent } from "../session.js";
+import type { ModelSelection, AgentPermissionConfig } from "../types.js";
+export type { SseEvent };
+/**
+ * Configuration for initializing an LLM provider.
+ *
+ * Combines model selection, destination path for scoped file permissions,
+ * and optional per-agent permission overrides. Provider implementations
+ * translate these into provider-specific server or client configuration.
+ */
+export interface ProviderConfig {
+    /** The resolved model to use (provider ID + model ID). */
+    model: ModelSelection;
+    /**
+     * Absolute path to the destination directory for generated documentation.
+     * Used by providers that scope file-write permissions to a specific directory.
+     */
+    destinationPath: string;
+    /**
+     * Optional per-agent permission overrides.
+     * When provided, the provider applies these permission scopes to its
+     * underlying session engine. The key is the agent name.
+     */
+    agentPermissions?: Record<string, AgentPermissionConfig>;
+    /**
+     * Optional verbose logging callback.
+     * Providers should call this for diagnostic output when set.
+     */
+    verbose?: (msg: string) => void;
+    /**
+     * Absolute path to the `.hem/search-index.db` file.
+     * When set, the `hem-search` MCP tool is registered and available
+     * to doc/org/xref agents for on-demand doc search.
+     */
+    searchDbPath?: string;
+}
+/**
+ * Core provider interface that all LLM provider implementations must satisfy.
+ *
+ * Aligns with Dispatch's `ProviderInstance` pattern — providers expose
+ * `createSession()`, `prompt()`, and `cleanup()` for the common case, plus
+ * low-level `session` and `event` properties for agents that need direct
+ * session control (e.g., OrganizationAgent's broadcast relay).
+ *
+ * Providers are constructed and initialized via `static async create()`.
+ * Callers receive an already-initialized provider and never call
+ * `initialize()` through the interface.
+ */
+export interface Provider {
+    /** Human-readable provider name (e.g. "copilot", "opencode"). */
+    readonly name: string;
+    /**
+     * Full model identifier (e.g. "anthropic/claude-sonnet-4"), if known.
+     * May be undefined until after the first session is created.
+     */
+    readonly model?: string;
+    /**
+     * Create a new isolated session for a single task.
+     * Returns an opaque session identifier.
+     */
+    createSession(): Promise<string>;
+    /**
+     * Send a prompt to an existing session and wait for the agent to finish.
+     * Returns the agent's text response, or null if no response was produced.
+     *
+     * @param sessionId - The session ID returned by `createSession()`.
+     * @param text      - The prompt text to send.
+     * @param options   - Optional: `agent` selects the permission profile
+     *                    (OpenCode only; ignored by Copilot provider).
+     */
+    prompt(sessionId: string, text: string, options?: {
+        agent?: string;
+    }): Promise<string | null>;
+    /**
+     * Tear down the provider — stop servers, release resources.
+     * Safe to call multiple times.
+     */
+    cleanup(): Promise<void>;
+    readonly session: {
+        /**
+         * Fire-and-forget prompt — does not wait for the session to become idle.
+         * Used by OrganizationAgent to relay broadcast messages concurrently.
+         */
+        promptAsync(options: {
+            path: {
+                id: string;
+            };
+            body: {
+                parts: Array<{
+                    type: "text";
+                    text: string;
+                }>;
+                agent?: string;
+            };
+        }): Promise<{
+            data?: void;
+            error?: unknown;
+        }>;
+        /**
+         * Abort any in-progress work in the session (best-effort).
+         * Called before `delete()` to ensure the session is idle.
+         */
+        abort(options: {
+            path: {
+                id: string;
+            };
+        }): Promise<{
+            data?: boolean;
+            error?: unknown;
+        }>;
+        /**
+         * Delete/destroy the session and release its resources.
+         */
+        delete(options: {
+            path: {
+                id: string;
+            };
+        }): Promise<{
+            data?: boolean;
+            error?: unknown;
+        }>;
+    };
+    readonly event: {
+        /**
+         * Subscribe to SSE events from the provider.
+         *
+         * Returns an async generator that yields events. Callers iterate
+         * the stream until they receive a terminal event or break.
+         *
+         * Used by OrganizationAgent and CrossRefAgent to intercept broadcast
+         * tool calls and child session creation events.
+         */
+        subscribe(options?: Record<string, unknown>): Promise<{
+            stream: AsyncGenerator<SseEvent, void, unknown>;
+        }>;
+    };
+    /**
+     * Returns the configuration used to initialize this provider.
+     */
+    readonly config: ProviderConfig;
+}

package/dist/providers/types.js

@@ -0,0 +1,16 @@
+/**
+ * Provider abstraction layer type definitions for Hem.
+ *
+ * Defines the {@link Provider} interface that all LLM provider
+ * implementations must satisfy, the {@link ProviderConfig} configuration
+ * type, and the {@link SseEvent} type used by the SSE relay.
+ *
+ * Aligns with Dispatch's `ProviderInstance` pattern:
+ *   - `createSession()` — create an isolated session, returns session ID
+ *   - `prompt(sessionId, text)` — send a prompt and wait for completion
+ *   - `cleanup()` — tear down the provider
+ *
+ * Also exposes low-level `session` and `event` properties for agents that
+ * need direct session control (OrganizationAgent, CrossRefAgent, etc.).
+ */
+export {};

package/dist/resources.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Resource-aware concurrency limits.
+ *
+ * OpenCode runs as a single server process with multiple sessions sharing
+ * memory (~500 MB per session). Sessions are CPU-intensive.
+ * This module inspects system resources at runtime to compute a safe upper
+ * bound on the number of concurrent sessions Hem should run.
+ *
+ * Rules:
+ *   - Memory: 1 session per 500 MB of **free** system memory.
+ *   - CPU:    1 session per CPU core.
+ *   - Floor:  at least {@link CONCURRENCY_FLOOR} regardless of resources.
+ *   - Effective limit: `max(floor, min(cpuCount, floor(freeMem_MB / 500)))`.
+ *
+ * The floor exists because when using cloud-hosted LLMs the local memory and
+ * CPU are not the bottleneck; overly conservative limits would serialize work
+ * that can safely run in parallel. Use `--concurrency 1` to restrict when
+ * running a local model on a constrained machine.
+ *
+ * The user's `--concurrency` flag (if provided) is clamped to this ceiling.
+ */
+/**
+ * File count above which Hem activates multi-agent scaling.
+ *
+ * When a project has more files than this threshold, exploration and
+ * documentation phases distribute work across multiple agents per group.
+ */
+export declare const LARGE_PROJECT_THRESHOLD = 200;
+/**
+ * Compute the maximum safe concurrency based on system resources.
+ *
+ * @param userRequested - Optional user-provided `--concurrency` value.
+ *                        When supplied the result is clamped to the resource
+ *                        ceiling; when omitted the resource ceiling itself is
+ *                        returned.
+ * @returns The effective concurrency (always ≥ 1).
+ */
+export declare function computeMaxConcurrency(userRequested?: number): number;
+/**
+ * Return a human-readable summary of the resource snapshot used for
+ * concurrency decisions.  Useful for verbose / debug logging.
+ */
+export declare function describeResourceLimits(userRequested?: number): string;
+/**
+ * Compute the effective number of agents to run per group.
+ *
+ * For small projects (≤ {@link LARGE_PROJECT_THRESHOLD} files) this returns 1
+ * (single-agent-per-group, the current default).
+ *
+ * For larger projects the count scales linearly from
+ * {@link MIN_AGENTS_PER_GROUP} to {@link MAX_AGENTS_PER_GROUP} based on file
+ * count, then is clamped to the resource ceiling so the machine is not
+ * over-committed.
+ *
+ * @param fileCount       - Total number of source files in the project.
+ * @param resourceCeiling - Maximum concurrent sessions the system can sustain.
+ *                          Defaults to {@link computeMaxConcurrency}().
+ * @returns Agents per group — 1 for small projects, 4-8 for large ones.
+ */
+export declare function computeAgentsPerGroup(fileCount: number, resourceCeiling?: number): number;
+/**
+ * Compute the effective number of parallel organization workers.
+ *
+ * Scales linearly from {@link MIN_ORG_WORKERS} (4) to {@link MAX_ORG_WORKERS}
+ * (7) based on the number of documentation files, then clamps to the resource
+ * ceiling so the machine is not over-committed.
+ *
+ * The scaling range is 9–50 files (9 is the minimum for parallel mode,
+ * 50 files reaches the maximum worker count).
+ *
+ * @param fileCount       - Number of documentation files to organize.
+ * @param resourceCeiling - Maximum concurrent sessions the system can sustain.
+ *                          Defaults to {@link computeMaxConcurrency}().
+ * @returns Worker count — 4 to 7, clamped to resource ceiling (but always ≥ 1).
+ */
+export declare function computeOrgWorkers(fileCount: number, resourceCeiling?: number): number;

package/dist/resources.js

@@ -0,0 +1,151 @@
+/**
+ * Resource-aware concurrency limits.
+ *
+ * OpenCode runs as a single server process with multiple sessions sharing
+ * memory (~500 MB per session). Sessions are CPU-intensive.
+ * This module inspects system resources at runtime to compute a safe upper
+ * bound on the number of concurrent sessions Hem should run.
+ *
+ * Rules:
+ *   - Memory: 1 session per 500 MB of **free** system memory.
+ *   - CPU:    1 session per CPU core.
+ *   - Floor:  at least {@link CONCURRENCY_FLOOR} regardless of resources.
+ *   - Effective limit: `max(floor, min(cpuCount, floor(freeMem_MB / 500)))`.
+ *
+ * The floor exists because when using cloud-hosted LLMs the local memory and
+ * CPU are not the bottleneck; overly conservative limits would serialize work
+ * that can safely run in parallel. Use `--concurrency 1` to restrict when
+ * running a local model on a constrained machine.
+ *
+ * The user's `--concurrency` flag (if provided) is clamped to this ceiling.
+ */
+import { freemem, cpus } from "node:os";
+/** Bytes of free memory required per concurrent session. */
+const BYTES_PER_SESSION = 500 * 1024 * 1024; // 500 MB
+/** CPU cores required per concurrent session. */
+const CORES_PER_SESSION = 1;
+/**
+ * Minimum concurrency regardless of available system resources.
+ * Prevents over-serialization when using cloud-hosted LLMs where local
+ * memory and CPU are not the throughput bottleneck.
+ */
+const CONCURRENCY_FLOOR = 4;
+// ── Large-project scaling ───────────────────────────────────────────────
+/**
+ * File count above which Hem activates multi-agent scaling.
+ *
+ * When a project has more files than this threshold, exploration and
+ * documentation phases distribute work across multiple agents per group.
+ */
+export const LARGE_PROJECT_THRESHOLD = 200;
+/** Minimum agents per group when multi-agent scaling is active. */
+const MIN_AGENTS_PER_GROUP = 4;
+/** Maximum agents per group when multi-agent scaling is active. */
+const MAX_AGENTS_PER_GROUP = 8;
+/**
+ * Compute the maximum safe concurrency based on system resources.
+ *
+ * @param userRequested - Optional user-provided `--concurrency` value.
+ *                        When supplied the result is clamped to the resource
+ *                        ceiling; when omitted the resource ceiling itself is
+ *                        returned.
+ * @returns The effective concurrency (always ≥ 1).
+ */
+export function computeMaxConcurrency(userRequested) {
+    const maxByMemory = Math.max(1, Math.floor(freemem() / BYTES_PER_SESSION));
+    const maxByCpu = Math.max(1, Math.floor(cpus().length / CORES_PER_SESSION));
+    const resourceLimit = Math.max(CONCURRENCY_FLOOR, Math.min(maxByMemory, maxByCpu));
+    if (userRequested != null && userRequested > 0) {
+        return Math.min(userRequested, resourceLimit);
+    }
+    return resourceLimit;
+}
+/**
+ * Return a human-readable summary of the resource snapshot used for
+ * concurrency decisions.  Useful for verbose / debug logging.
+ */
+export function describeResourceLimits(userRequested) {
+    const freeGiB = (freemem() / (1024 * 1024 * 1024)).toFixed(1);
+    const cpuCount = cpus().length;
+    const maxByMemory = Math.max(1, Math.floor(freemem() / BYTES_PER_SESSION));
+    const maxByCpu = Math.max(1, Math.floor(cpuCount / CORES_PER_SESSION));
+    const effective = computeMaxConcurrency(userRequested);
+    const resourceFloor = effective === CONCURRENCY_FLOOR && Math.min(maxByMemory, maxByCpu) < CONCURRENCY_FLOOR
+        ? ` (floor=${CONCURRENCY_FLOOR})`
+        : "";
+    const parts = [
+        `free_mem=${freeGiB}GB (limit ${maxByMemory})`,
+        `cpus=${cpuCount} (limit ${maxByCpu})`,
+        `effective=${effective}${resourceFloor}`,
+    ];
+    if (userRequested != null && userRequested > effective) {
+        parts.push(`user_requested=${userRequested} (clamped)`);
+    }
+    return parts.join(", ");
+}
+// ── Multi-agent scaling ─────────────────────────────────────────────────
+/**
+ * Compute the effective number of agents to run per group.
+ *
+ * For small projects (≤ {@link LARGE_PROJECT_THRESHOLD} files) this returns 1
+ * (single-agent-per-group, the current default).
+ *
+ * For larger projects the count scales linearly from
+ * {@link MIN_AGENTS_PER_GROUP} to {@link MAX_AGENTS_PER_GROUP} based on file
+ * count, then is clamped to the resource ceiling so the machine is not
+ * over-committed.
+ *
+ * @param fileCount       - Total number of source files in the project.
+ * @param resourceCeiling - Maximum concurrent sessions the system can sustain.
+ *                          Defaults to {@link computeMaxConcurrency}().
+ * @returns Agents per group — 1 for small projects, 4-8 for large ones.
+ */
+export function computeAgentsPerGroup(fileCount, resourceCeiling) {
+    if (fileCount <= LARGE_PROJECT_THRESHOLD)
+        return 1;
+    const ceiling = resourceCeiling != null && resourceCeiling > 0
+        ? resourceCeiling
+        : computeMaxConcurrency();
+    // Linear interpolation: 4 at threshold, 8 at 5× threshold (1000 files).
+    const span = LARGE_PROJECT_THRESHOLD * 4; // 800 files of range
+    const ratio = Math.min(1, (fileCount - LARGE_PROJECT_THRESHOLD) / span);
+    const desired = Math.round(MIN_AGENTS_PER_GROUP + ratio * (MAX_AGENTS_PER_GROUP - MIN_AGENTS_PER_GROUP));
+    // Clamp to resource ceiling, but always return at least MIN_AGENTS_PER_GROUP.
+    return Math.max(MIN_AGENTS_PER_GROUP, Math.min(desired, ceiling));
+}
+// ── Organization worker scaling ─────────────────────────────────────────
+/** Minimum org workers when parallel mode is active. */
+const MIN_ORG_WORKERS = 4;
+/** Maximum org workers when parallel mode is active. */
+const MAX_ORG_WORKERS = 7;
+/**
+ * Compute the effective number of parallel organization workers.
+ *
+ * Scales linearly from {@link MIN_ORG_WORKERS} (4) to {@link MAX_ORG_WORKERS}
+ * (7) based on the number of documentation files, then clamps to the resource
+ * ceiling so the machine is not over-committed.
+ *
+ * The scaling range is 9–50 files (9 is the minimum for parallel mode,
+ * 50 files reaches the maximum worker count).
+ *
+ * @param fileCount       - Number of documentation files to organize.
+ * @param resourceCeiling - Maximum concurrent sessions the system can sustain.
+ *                          Defaults to {@link computeMaxConcurrency}().
+ * @returns Worker count — 4 to 7, clamped to resource ceiling (but always ≥ 1).
+ */
+export function computeOrgWorkers(fileCount, resourceCeiling) {
+    const ceiling = resourceCeiling != null && resourceCeiling > 0
+        ? resourceCeiling
+        : computeMaxConcurrency();
+    // Below parallel threshold, caller should use single-agent path;
+    // but if called, return 1 as a safe fallback.
+    if (fileCount <= 8)
+        return 1;
+    // Linear interpolation: 4 workers at 9 files, 7 workers at 50 files.
+    const scaleStart = 9;
+    const scaleEnd = 50;
+    const span = scaleEnd - scaleStart;
+    const ratio = Math.min(1, Math.max(0, (fileCount - scaleStart) / span));
+    const desired = Math.round(MIN_ORG_WORKERS + ratio * (MAX_ORG_WORKERS - MIN_ORG_WORKERS));
+    return Math.max(1, Math.min(desired, ceiling));
+}

package/dist/search-index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SQLite-backed search index for existing documentation files.
+ *
+ * Provides:
+ *  - Full-text search (FTS5 with porter stemmer) over doc content
+ *  - Incremental updates via SHA-256 hash comparison (re-index only changed docs)
+ *  - Source-file → doc-file mapping for targeted regeneration
+ *
+ * Stored in `.hem/search-index.db` alongside the grouping cache.
+ *
+ * Architecture:
+ *   - `doc_meta`: tracks path → content_hash for incremental update decisions
+ *   - `doc_fts`: FTS5 virtual table for ranked keyword search
+ *   - `source_doc_map`: many-to-many map from source code files to doc files
+ *
+ * The main process opens the index read-write to build/update it.
+ * The optional `hem-search` MCP server opens it read-only for agent queries.
+ */
+export interface SearchResult {
+    path: string;
+    snippet: string;
+}
+export declare class SearchIndex {
+    private readonly db;
+    private constructor();
+    /**
+     * Open (or create) the SQLite index at the given path.
+     * The parent directory is created if it does not exist.
+     *
+     * @param dbPath   - Absolute path to the `.db` file.
+     * @param readonly - When `true`, open in read-only mode (for MCP server).
+     */
+    static open(dbPath: string, readonly?: boolean): SearchIndex;
+    /**
+     * Upsert a document into the index.
+     *
+     * Computes SHA-256 of `content`. If the stored hash matches, skips the write
+     * and returns `false`. Otherwise (re)indexes and returns `true`.
+     */
+    upsertDoc(path: string, content: string): boolean;
+    /**
+     * Remove a document from the index and its source mappings.
+     */
+    removeDoc(path: string): void;
+    /**
+     * Full-text search over indexed doc content.
+     *
+     * Returns up to `limit` results ranked by BM25 relevance, each with a
+     * short snippet highlighting matching terms.
+     *
+     * Returns an empty array if the query is blank or produces no results.
+     */
+    search(query: string, limit?: number): SearchResult[];
+    /**
+     * Replace the source-file → doc-file mappings for a given doc.
+     *
+     * Any previously recorded source paths for `docPath` are removed first.
+     */
+    setSourceMappings(docPath: string, sourcePaths: string[]): void;
+    /**
+     * Returns the paths of all docs that cover a given source file.
+     */
+    getDocsForSource(sourcePath: string): string[];
+    /**
+     * Returns a map of all indexed paths to their stored content hashes.
+     * Used during startup to determine which docs are stale or deleted.
+     */
+    getAllHashes(): Map<string, string>;
+    /** Close the underlying database connection. */
+    close(): void;
+}

package/dist/search-index.js

@@ -0,0 +1,187 @@
+/**
+ * SQLite-backed search index for existing documentation files.
+ *
+ * Provides:
+ *  - Full-text search (FTS5 with porter stemmer) over doc content
+ *  - Incremental updates via SHA-256 hash comparison (re-index only changed docs)
+ *  - Source-file → doc-file mapping for targeted regeneration
+ *
+ * Stored in `.hem/search-index.db` alongside the grouping cache.
+ *
+ * Architecture:
+ *   - `doc_meta`: tracks path → content_hash for incremental update decisions
+ *   - `doc_fts`: FTS5 virtual table for ranked keyword search
+ *   - `source_doc_map`: many-to-many map from source code files to doc files
+ *
+ * The main process opens the index read-write to build/update it.
+ * The optional `hem-search` MCP server opens it read-only for agent queries.
+ */
+import Database from "better-sqlite3";
+import { createHash } from "node:crypto";
+import { mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+// ── Schema DDL ────────────────────────────────────────────────────────
+const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+
+CREATE TABLE IF NOT EXISTS doc_meta (
+  path         TEXT PRIMARY KEY,
+  content_hash TEXT NOT NULL,
+  indexed_at   INTEGER NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS doc_fts USING fts5(
+  path UNINDEXED,
+  content,
+  tokenize = 'porter ascii'
+);
+
+CREATE TABLE IF NOT EXISTS source_doc_map (
+  source_path TEXT NOT NULL,
+  doc_path    TEXT NOT NULL,
+  PRIMARY KEY (source_path, doc_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sdm_doc ON source_doc_map(doc_path);
+`;
+export class SearchIndex {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Open (or create) the SQLite index at the given path.
+     * The parent directory is created if it does not exist.
+     *
+     * @param dbPath   - Absolute path to the `.db` file.
+     * @param readonly - When `true`, open in read-only mode (for MCP server).
+     */
+    static open(dbPath, readonly = false) {
+        if (!readonly) {
+            const dir = dirname(dbPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+        }
+        const db = new Database(dbPath, { readonly });
+        if (!readonly) {
+            // Apply schema (idempotent)
+            db.exec(SCHEMA_SQL);
+        }
+        return new SearchIndex(db);
+    }
+    /**
+     * Upsert a document into the index.
+     *
+     * Computes SHA-256 of `content`. If the stored hash matches, skips the write
+     * and returns `false`. Otherwise (re)indexes and returns `true`.
+     */
+    upsertDoc(path, content) {
+        const hash = sha256(content);
+        const existing = this.db
+            .prepare("SELECT content_hash FROM doc_meta WHERE path = ?")
+            .get(path);
+        if (existing?.content_hash === hash) {
+            return false;
+        }
+        const deleteFts = this.db.prepare("DELETE FROM doc_fts WHERE path = ?");
+        const insertFts = this.db.prepare("INSERT INTO doc_fts(path, content) VALUES (?, ?)");
+        const upsertMeta = this.db.prepare("INSERT INTO doc_meta(path, content_hash, indexed_at) VALUES (?, ?, ?) " +
+            "ON CONFLICT(path) DO UPDATE SET content_hash = excluded.content_hash, indexed_at = excluded.indexed_at");
+        this.db.transaction(() => {
+            deleteFts.run(path);
+            insertFts.run(path, content);
+            upsertMeta.run(path, hash, Date.now());
+        })();
+        return true;
+    }
+    /**
+     * Remove a document from the index and its source mappings.
+     */
+    removeDoc(path) {
+        this.db.prepare("DELETE FROM doc_fts WHERE path = ?").run(path);
+        this.db.prepare("DELETE FROM doc_meta WHERE path = ?").run(path);
+        this.db.prepare("DELETE FROM source_doc_map WHERE doc_path = ?").run(path);
+    }
+    /**
+     * Full-text search over indexed doc content.
+     *
+     * Returns up to `limit` results ranked by BM25 relevance, each with a
+     * short snippet highlighting matching terms.
+     *
+     * Returns an empty array if the query is blank or produces no results.
+     */
+    search(query, limit = 5) {
+        const trimmed = query.trim();
+        if (!trimmed)
+            return [];
+        // Build a safe FTS5 query: extract alphanumeric words and join with spaces.
+        // FTS5 treats space-separated words as implicit AND, so each word must
+        // appear in the document. Quoting the whole query as a phrase would require
+        // exact adjacency, which is too strict for our use case.
+        const words = trimmed
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((w) => w.length > 1);
+        if (words.length === 0)
+            return [];
+        const safeQuery = words.join(" ");
+        try {
+            const rows = this.db
+                .prepare(`SELECT path,
+                  snippet(doc_fts, 1, '<b>', '</b>', '…', 24) AS snippet
+           FROM doc_fts
+           WHERE doc_fts MATCH ?
+           ORDER BY rank
+           LIMIT ?`)
+                .all(safeQuery, limit);
+            return rows.map((r) => ({ path: r.path, snippet: r.snippet }));
+        }
+        catch {
+            // FTS5 syntax error (e.g., query is just punctuation) — return nothing
+            return [];
+        }
+    }
+    /**
+     * Replace the source-file → doc-file mappings for a given doc.
+     *
+     * Any previously recorded source paths for `docPath` are removed first.
+     */
+    setSourceMappings(docPath, sourcePaths) {
+        const deleteExisting = this.db.prepare("DELETE FROM source_doc_map WHERE doc_path = ?");
+        const insert = this.db.prepare("INSERT OR IGNORE INTO source_doc_map(source_path, doc_path) VALUES (?, ?)");
+        this.db.transaction((paths) => {
+            deleteExisting.run(docPath);
+            for (const sp of paths) {
+                insert.run(sp, docPath);
+            }
+        })(sourcePaths);
+    }
+    /**
+     * Returns the paths of all docs that cover a given source file.
+     */
+    getDocsForSource(sourcePath) {
+        const rows = this.db
+            .prepare("SELECT doc_path FROM source_doc_map WHERE source_path = ?")
+            .all(sourcePath);
+        return rows.map((r) => r.doc_path);
+    }
+    /**
+     * Returns a map of all indexed paths to their stored content hashes.
+     * Used during startup to determine which docs are stale or deleted.
+     */
+    getAllHashes() {
+        const rows = this.db
+            .prepare("SELECT path, content_hash FROM doc_meta")
+            .all();
+        return new Map(rows.map((r) => [r.path, r.content_hash]));
+    }
+    /** Close the underlying database connection. */
+    close() {
+        this.db.close();
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+function sha256(input) {
+    return createHash("sha256").update(input, "utf-8").digest("hex");
+}

package/dist/search-mcp.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Standalone stdio-based MCP server exposing the Hem doc search index.
+ *
+ * Exposes two tools:
+ *   - `search_docs({ query, limit? })` — FTS5 keyword search over indexed docs
+ *   - `get_docs_for_source({ source_path })` — find docs covering a source file
+ *
+ * Receives the SQLite DB path as the first CLI argument:
+ *   node dist/search-mcp.js /path/to/.hem/search-index.db
+ *
+ * Opens the DB in read-only mode. Multiple agent processes may connect
+ * simultaneously; SQLite WAL mode handles concurrent reads safely.
+ *
+ * Registered in OpenCode via config.mcp as:
+ *   { type: "local", command: ["node", "dist/search-mcp.js", dbPath], enabled: true }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SearchIndex } from "./search-index.js";
+/**
+ * Build the hem-search MCP server bound to the given SearchIndex.
+ * Exported for tests; the CLI bootstrap below wires it up to a stdio
+ * transport with a real read-only SQLite-backed index.
+ */
+export declare function createSearchMcpServer(index: SearchIndex): McpServer;