@jafreck/lore 0.2.5 → 0.3.0

package/dist/runtime.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @module runtime
+ *
+ * `LoreRuntime` centralises the lifecycle of all long-lived resources that a
+ * Lore session needs: database handles, embedding providers, LSP coordinators,
+ * and file-change refreshers (watcher / poller).
+ *
+ * Both the CLI sub-commands and the MCP server dispatch through a single
+ * runtime instance so that startup, shutdown, and resource ownership are
+ * handled in one place.
+ */
+import type { EmbeddingProvider } from './indexer/embedder.js';
+import type { EffectiveLspSettings } from './indexer/lsp/config.js';
+import type { WalkerConfig } from './indexer/walker.js';
+import { type LoreLogger } from './logger.js';
+/** Immutable bag of settings collected from CLI flags / programmatic callers. */
+export interface RuntimeConfig {
+    /** Path to the Lore SQLite knowledge-base file. */
+    dbPath: string;
+    /** Root directory of the project being indexed. */
+    rootDir: string;
+    /** Walker configuration (globs, extensions, doc filters, etc.). */
+    walkerConfig: WalkerConfig;
+    /** Git branch / ref policy. */
+    branch?: string;
+    /** Embedding model identifier (default resolved internally). */
+    embeddingModel?: string;
+    /** LSP enrichment policy. `null` = disabled. */
+    lsp: EffectiveLspSettings | null;
+    /** Git history ingestion policy. */
+    history: boolean | {
+        depth?: number;
+        all?: boolean;
+    };
+    /** Whether to index dependency declarations (.d.ts, etc.). */
+    indexDependencies: boolean;
+    /** Whether to auto-seed notes from documentation files. */
+    docsAutoNotes: boolean;
+    /** Refresh mode: `'none'` (one-shot), `'watch'`, or `'poll'`. */
+    refreshMode: 'none' | 'watch' | 'poll';
+}
+/** Minimal interface shared by FileWatcher and FilePoller. */
+export interface Refresher {
+    start(): void;
+    stop(): void;
+}
+/**
+ * Owns the lifecycle of all long-lived Lore resources.
+ *
+ * Typical usage:
+ * ```ts
+ * const runtime = new LoreRuntime(config);
+ * await runtime.start();
+ * // ... do work ...
+ * await runtime.shutdown();
+ * ```
+ */
+export declare class LoreRuntime {
+    readonly config: RuntimeConfig;
+    readonly log: LoreLogger;
+    private _embedder;
+    private _refresher;
+    private _started;
+    constructor(config: RuntimeConfig, logger?: LoreLogger);
+    /** The live embedding provider, or `undefined` if embeddings are disabled. */
+    get embedder(): EmbeddingProvider | undefined;
+    /** The live file-change refresher, or `undefined` if refresh mode is `'none'`. */
+    get refresher(): Refresher | undefined;
+    get started(): boolean;
+    /**
+     * Initialise optional long-lived resources (embedder, watcher/poller).
+     *
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    start(): Promise<void>;
+    /**
+     * Gracefully tear down all managed resources.
+     *
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register process-level signal handlers (`SIGINT`, `SIGTERM`) that call
+     * `shutdown()` and exit. Convenience for CLI entry points.
+     */
+    installSignalHandlers(): void;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzD,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,YAAY,EAAE,YAAY,CAAC;IAG3B,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,GAAG,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACjC,oCAAoC;IACpC,OAAO,EAAE,OAAO,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrD,8DAA8D;IAC9D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,WAAW,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CACxC;AAID,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;CACd;AAID;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,UAAU;IAOtD,8EAA8E;IAC9E,IAAI,QAAQ,IAAI,iBAAiB,GAAG,SAAS,CAE5C;IAED,kFAAkF;IAClF,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAID;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA8D5B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB/B;;;OAGG;IACH,qBAAqB,IAAI,IAAI;CAkB9B"}

package/dist/runtime.js

@@ -0,0 +1,153 @@
+/**
+ * @module runtime
+ *
+ * `LoreRuntime` centralises the lifecycle of all long-lived resources that a
+ * Lore session needs: database handles, embedding providers, LSP coordinators,
+ * and file-change refreshers (watcher / poller).
+ *
+ * Both the CLI sub-commands and the MCP server dispatch through a single
+ * runtime instance so that startup, shutdown, and resource ownership are
+ * handled in one place.
+ */
+import { getLogger } from './logger.js';
+// ─── LoreRuntime ──────────────────────────────────────────────────────────────
+/**
+ * Owns the lifecycle of all long-lived Lore resources.
+ *
+ * Typical usage:
+ * ```ts
+ * const runtime = new LoreRuntime(config);
+ * await runtime.start();
+ * // ... do work ...
+ * await runtime.shutdown();
+ * ```
+ */
+export class LoreRuntime {
+    config;
+    log;
+    _embedder = null;
+    _refresher = null;
+    _started = false;
+    constructor(config, logger) {
+        this.config = config;
+        this.log = logger ?? getLogger();
+    }
+    // ─── Accessors ─────────────────────────────────────────────────────────────
+    /** The live embedding provider, or `undefined` if embeddings are disabled. */
+    get embedder() {
+        return this._embedder ?? undefined;
+    }
+    /** The live file-change refresher, or `undefined` if refresh mode is `'none'`. */
+    get refresher() {
+        return this._refresher ?? undefined;
+    }
+    get started() {
+        return this._started;
+    }
+    // ─── Lifecycle ─────────────────────────────────────────────────────────────
+    /**
+     * Initialise optional long-lived resources (embedder, watcher/poller).
+     *
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    async start() {
+        if (this._started)
+            return;
+        this._started = true;
+        // ── Embedder ─────────────────────────────────────────────────────────────
+        if (this.config.embeddingModel) {
+            try {
+                const { SentenceTransformersProvider } = await import('./indexer/embedder.js');
+                const provider = new SentenceTransformersProvider(this.config.embeddingModel);
+                await provider.init();
+                this._embedder = provider;
+                this.log.startup('embedding model loaded', {
+                    embeddingModel: this.config.embeddingModel,
+                    embeddingReady: true,
+                });
+            }
+            catch {
+                this.log.warn('startup', 'embedding model unavailable, continuing without embeddings', { embeddingModel: this.config.embeddingModel });
+            }
+        }
+        // ── Refresher (watch / poll) ─────────────────────────────────────────────
+        if (this.config.refreshMode === 'watch') {
+            const { FileWatcher } = await import('./indexer/watcher.js');
+            const watcher = new FileWatcher(this.config.dbPath, this.config.walkerConfig, {
+                history: this.config.history,
+                indexDependencies: this.config.indexDependencies,
+                lsp: this.config.lsp ?? undefined,
+                embedder: this._embedder ?? undefined,
+            });
+            watcher.start();
+            this._refresher = watcher;
+            this.log.startup('watch mode started', {
+                rootDir: this.config.rootDir,
+                embeddingEnabled: !!this._embedder,
+            });
+            process.stderr.write(JSON.stringify({ level: 'info', source: 'cli', message: 'watch mode started', rootDir: this.config.rootDir, embeddingEnabled: !!this._embedder }) + '\n');
+        }
+        else if (this.config.refreshMode === 'poll') {
+            const { FilePoller } = await import('./indexer/poller.js');
+            const poller = new FilePoller(this.config.dbPath, this.config.walkerConfig, {
+                history: this.config.history,
+                indexDependencies: this.config.indexDependencies,
+                lsp: this.config.lsp ?? undefined,
+                embedder: this._embedder ?? undefined,
+            });
+            poller.start();
+            this._refresher = poller;
+            this.log.startup('poll mode started', {
+                rootDir: this.config.rootDir,
+                embeddingEnabled: !!this._embedder,
+            });
+            process.stderr.write(JSON.stringify({ level: 'info', source: 'cli', message: 'poll mode started', rootDir: this.config.rootDir, embeddingEnabled: !!this._embedder }) + '\n');
+        }
+    }
+    /**
+     * Gracefully tear down all managed resources.
+     *
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    async shutdown() {
+        if (!this._started)
+            return;
+        this._started = false;
+        if (this._refresher) {
+            this._refresher.stop();
+            this._refresher = null;
+        }
+        if (this._embedder) {
+            try {
+                await this._embedder.dispose();
+            }
+            catch {
+                /* best-effort */
+            }
+            this._embedder = null;
+        }
+    }
+    /**
+     * Register process-level signal handlers (`SIGINT`, `SIGTERM`) that call
+     * `shutdown()` and exit. Convenience for CLI entry points.
+     */
+    installSignalHandlers() {
+        const handler = () => {
+            // Stop refresher synchronously to match CLI expectations.
+            if (this._refresher) {
+                this._refresher.stop();
+                this._refresher = null;
+            }
+            // Dispose embedder best-effort in background, then exit.
+            if (this._embedder) {
+                this._embedder.dispose().catch(() => { });
+                this._embedder = null;
+            }
+            this._started = false;
+            process.exit(0);
+        };
+        process.on('SIGINT', handler);
+        process.on('SIGTERM', handler);
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAC;AAsCzD,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;IACb,MAAM,CAAgB;IACtB,GAAG,CAAa;IAEjB,SAAS,GAA6B,IAAI,CAAC;IAC3C,UAAU,GAAqB,IAAI,CAAC;IACpC,QAAQ,GAAG,KAAK,CAAC;IAEzB,YAAY,MAAqB,EAAE,MAAmB;QACpD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,MAAM,IAAI,SAAS,EAAE,CAAC;IACnC,CAAC;IAED,8EAA8E;IAE9E,8EAA8E;IAC9E,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC;IACrC,CAAC;IAED,kFAAkF;IAClF,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,IAAI,SAAS,CAAC;IACtC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,8EAA8E;IAE9E;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,4EAA4E;QAC5E,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,EAAE,4BAA4B,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;gBAC/E,MAAM,QAAQ,GAAG,IAAI,4BAA4B,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;gBAC9E,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACtB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;gBAC1B,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,wBAAwB,EAAE;oBACzC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;oBAC1C,cAAc,EAAE,IAAI;iBACrB,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,GAAG,CAAC,IAAI,CACX,SAAS,EACT,4DAA4D,EAC5D,EAAE,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAC/C,CAAC;YACJ,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,OAAO,EAAE,CAAC;YACxC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;gBAC5E,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAC5B,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;gBAChD,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,SAAS;gBACjC,QAAQ,EAAE,IAAI,CAAC,SAAS,IAAI,SAAS;aACtC,CAAC,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;YAC1B,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB,EAAE;gBACrC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAC5B,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;aACnC,CAAC,CAAC;YACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,IAAI,CACzJ,CAAC;QACJ,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;YAC9C,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;gBAC1E,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAC5B,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;gBAChD,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,SAAS;gBACjC,QAAQ,EAAE,IAAI,CAAC,SAAS,IAAI,SAAS;aACtC,CAAC,CAAC;YACH,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE;gBACpC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAC5B,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;aACnC,CAAC,CAAC;YACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,IAAI,CACxJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC3B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QAEtB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,iBAAiB;YACnB,CAAC;YACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,qBAAqB;QACnB,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,0DAA0D;YAC1D,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;gBACvB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACzB,CAAC;YACD,yDAAyD;YACzD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAqB,CAAC,CAAC,CAAC;gBAC5D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACxB,CAAC;YACD,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC;QACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jafreck/lore",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Language-aware codebase indexer — tree-sitter parsing, symbol extraction, call-graph construction, and optional embeddings for semantic search",
   "type": "module",
   "main": "./dist/index.js",
@@ -61,36 +61,36 @@
     "fast-glob": "^3.3.3",
     "simple-git": "^3.32.3",
     "sqlite-vec": "^0.1.6",
-    "tree-sitter": "0.22.4",
+    "tree-sitter": "0.25.0",
     "tree-sitter-bash": "^0.25.1",
-    "tree-sitter-c": "^0.23.6",
-    "tree-sitter-c-sharp": "0.23.1",
-    "tree-sitter-cpp": "0.23.4",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-c-sharp": "^0.23.1",
+    "tree-sitter-cpp": "^0.23.4",
     "tree-sitter-dart": "^1.0.0",
     "tree-sitter-elixir": "^0.3.5",
     "tree-sitter-elm": "^4.5.0",
-    "tree-sitter-go": "0.23.4",
+    "tree-sitter-go": ">=0.23.4",
     "tree-sitter-haskell": "^0.23.1",
-    "tree-sitter-java": "0.23.5",
-    "tree-sitter-javascript": "0.23.1",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-julia": "^0.23.1",
     "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-lua": "^2.1.3",
     "tree-sitter-objc": "^3.0.2",
     "tree-sitter-ocaml": "^0.24.2",
     "tree-sitter-php": "^0.24.2",
-    "tree-sitter-python": "0.23.6",
+    "tree-sitter-python": ">=0.23.6",
     "tree-sitter-ruby": "^0.23.1",
-    "tree-sitter-rust": "0.24.0",
+    "tree-sitter-rust": "^0.24.0",
     "tree-sitter-scala": "^0.24.0",
     "tree-sitter-swift": "^0.7.1",
-    "tree-sitter-typescript": "0.23.2",
+    "tree-sitter-typescript": "^0.23.2",
     "tree-sitter-zig": "^0.2.0",
     "zod": "^4.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^25",
+    "@types/node": "^22",
     "@vitest/coverage-v8": "^4.0",
     "typescript": "^5.9",
     "vitest": "^4.0"