@amsterdamdatalabs/enact-docs-search 0.1.0

package/NOTICE

@@ -0,0 +1,50 @@
+enact-docs-search — third-party notices
+========================================
+
+This tool's Chunker, DocumentStore, and VectorStore modules are adapted from:
+
+  obsidian-qmd
+  https://github.com/thirteen37/obsidian-qmd
+  Licence: MIT, as declared in the project's README (`## License` -> `MIT`).
+  The upstream repository carries no LICENSE file and no per-file copyright
+  header, so there is no copyright notice to reproduce here; this entry
+  records provenance in its place.
+
+Files adapted (each carries an `Adapted from obsidian-qmd (MIT): <url>`
+header comment pointing back here):
+
+  src/indexing/chunker.ts        <- src/indexing/Chunker.ts        (near-verbatim port)
+  src/storage/document-store.ts  <- src/storage/DocumentStore.ts   (near-verbatim port)
+  src/storage/vector-store.ts    <- src/storage/VectorStore.ts     (ported from the
+                                     hnswlib-wasm API to hnswlib-node's API)
+  src/search/search-service.ts   <- src/search/SearchService.ts    (RRF fusion logic
+                                     carried over; query-expansion/reranking, which
+                                     call out to an LLM, were dropped as out of scope)
+
+Written fresh, not adapted (the upstream equivalents are Obsidian/Electron-
+specific plumbing with no Node analogue worth porting):
+
+  src/embeddings/embedding-service.ts  (upstream patches ONNX Runtime for
+                                         Obsidian's Electron renderer via blob
+                                         URLs; @xenova/transformers needs none
+                                         of that under plain Node/Bun)
+  src/adapter/repo-walker.ts           (replaces Obsidian's `Vault` with
+                                         node:fs/promises)
+  src/storage/persistence.ts           (replaces the plugin's IndexedDB/
+                                         localforage persistence with plain
+                                         per-repo cache files)
+  src/indexing/indexing-service.ts     (replaces Obsidian's long-lived
+                                         in-process indexing loop with a
+                                         manifest-driven incremental diff,
+                                         since this CLI process exits between
+                                         runs)
+  src/cli.ts, src/types.ts
+
+Runtime dependencies and their licences (all permissive, verified in
+package.json / node_modules at time of writing):
+
+  minisearch            MIT           BM25 full-text index
+  @xenova/transformers  Apache-2.0    local embeddings (no API key/network
+                                       call after the model is first cached)
+  hnswlib-node           Apache-2.0    HNSW vector index (native Node build,
+                                       not the wasm build obsidian-qmd uses)

package/README.md

@@ -0,0 +1,35 @@
+# @amsterdamdatalabs/enact-docs-search
+
+Hybrid BM25 and vector search over a repository's `docs/`, `.plans/`, and
+`.specs/` knowledge trees.
+
+## Install
+
+```bash
+npm install -g @amsterdamdatalabs/enact-docs-search
+```
+
+Node.js 22 or newer is required. The first semantic query downloads the local
+`Xenova/all-MiniLM-L6-v2` embedding model; subsequent queries use the per-repo
+cache under `~/.cache/enact-docs-search/`.
+
+## Usage
+
+Run inside a target repository:
+
+```bash
+enact-docs-search query "how crate boundaries are defined?"
+enact-docs-search index
+enact-docs-search index --force
+```
+
+Queries automatically refresh a missing or stale cache incrementally. Use
+`enact-docs-search --help` for advanced scope, mode, JSON, and exclusion
+controls.
+
+The package is also usable through `npx` or `bunx`:
+
+```bash
+npx @amsterdamdatalabs/enact-docs-search query "conversation vs tasks"
+bunx @amsterdamdatalabs/enact-docs-search query "conversation vs tasks"
+```

package/dist/adapter/repo-walker.d.ts

@@ -0,0 +1,22 @@
+export interface RepoFile {
+    /** Path relative to the repo root, using forward slashes. */
+    path: string;
+    /** Absolute path on disk. */
+    absPath: string;
+    /** Last-modified time in epoch milliseconds. */
+    mtimeMs: number;
+}
+export interface WalkOptions {
+    /** Extra glob patterns (relative to repoRoot) to exclude, in addition to the defaults. */
+    exclude?: string[];
+}
+/**
+ * List every Markdown/MDX file under the given roots (each relative to
+ * repoRoot), sorted for deterministic output.
+ */
+export declare function listMarkdownFiles(repoRoot: string, roots: string[], options?: WalkOptions): Promise<RepoFile[]>;
+/** Read a file's text content (equivalent to `vault.cachedRead`). */
+export declare function readRepoFile(absPath: string): Promise<string>;
+/** Repo-relative path with forward slashes, given an absolute path under repoRoot. */
+export declare function toRepoRelative(repoRoot: string, absPath: string): string;
+//# sourceMappingURL=repo-walker.d.ts.map

package/dist/adapter/repo-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-walker.d.ts","sourceRoot":"","sources":["../../src/adapter/repo-walker.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAcrB;AA4DD,qEAAqE;AACrE,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/adapter/repo-walker.js

@@ -0,0 +1,96 @@
+/**
+ * repo-walker.ts — small Node/Bun adapter that stands in for Obsidian's
+ * `App`/`Vault` in the upstream obsidian-qmd design.
+ *
+ * obsidian-qmd's IndexingService only ever touches the vault through three
+ * calls: `vault.getMarkdownFiles()`, `vault.cachedRead(file)`, and
+ * `file.stat.mtime` / `file.path`. This module provides the same three
+ * operations against a plain directory on disk, using Node's filesystem APIs
+ * for discovery, reads, and stats — no Obsidian or runtime-specific types
+ * anywhere in this file.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+const DEFAULT_EXCLUDES = [
+    "**/.astro/**",
+    "**/node_modules/**",
+    "**/.git/**",
+];
+/**
+ * List every Markdown/MDX file under the given roots (each relative to
+ * repoRoot), sorted for deterministic output.
+ */
+export async function listMarkdownFiles(repoRoot, roots, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.exclude ?? [])];
+    const files = [];
+    for (const root of roots) {
+        const absRoot = join(repoRoot, root);
+        const rootStat = await stat(absRoot).catch(() => null);
+        if (!rootStat || !rootStat.isDirectory())
+            continue;
+        await walk(absRoot, root, excludes, files);
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return files;
+}
+function isExcluded(relPath, excludes) {
+    for (const pattern of excludes) {
+        if (globToRegExp(pattern).test(relPath))
+            return true;
+    }
+    return false;
+}
+async function walk(absDir, relDir, excludes, files) {
+    const entries = await readdir(absDir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const relPath = `${relDir}/${entry.name}`;
+        if (isExcluded(relPath, excludes))
+            continue;
+        const absPath = join(absDir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(absPath, relPath, excludes, files);
+            continue;
+        }
+        if (!entry.isFile() || !/\.(?:md|mdx)$/i.test(entry.name))
+            continue;
+        const fileStat = await stat(absPath);
+        files.push({ path: relPath, absPath, mtimeMs: fileStat.mtimeMs });
+    }
+}
+function globToRegExp(pattern) {
+    const normalized = pattern.replaceAll("\\", "/");
+    let source = "^";
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized[i];
+        if (char === "*" && normalized[i + 1] === "*") {
+            i++;
+            if (normalized[i + 1] === "/") {
+                i++;
+                source += "(?:.*/)?";
+            }
+            else {
+                source += ".*";
+            }
+        }
+        else if (char === "*") {
+            source += "[^/]*";
+        }
+        else if (char === "?") {
+            source += "[^/]";
+        }
+        else {
+            source += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+        }
+    }
+    return new RegExp(`${source}$`);
+}
+/** Read a file's text content (equivalent to `vault.cachedRead`). */
+export async function readRepoFile(absPath) {
+    return readFile(absPath, "utf-8");
+}
+/** Repo-relative path with forward slashes, given an absolute path under repoRoot. */
+export function toRepoRelative(repoRoot, absPath) {
+    return relative(repoRoot, absPath).split(sep).join("/");
+}
+//# sourceMappingURL=repo-walker.js.map

package/dist/adapter/repo-walker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-walker.js","sourceRoot":"","sources":["../../src/adapter/repo-walker.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * enact-docs-search — hybrid (BM25 + vector) search CLI over a repo's
+ * docs/.plans/.specs knowledge trees. Takes the target repo as an argument;
+ * does not hardcode any particular checkout.
+ *
+ * Usage:
+ *   enact-docs-search index --repo <path> [--scope docs|plans|specs|all] [--force] [--keyword-only]
+ *   enact-docs-search query "<text>" --repo <path> [--scope ...] [--mode hybrid|keyword|semantic] [--limit N]
+ */
+import { DocumentStore } from "./storage/document-store.js";
+import { VectorStore, DependencyError as VectorDependencyError } from "./storage/vector-store.js";
+import { EmbeddingService, DependencyError as EmbeddingDependencyError } from "./embeddings/embedding-service.js";
+import { SearchService } from "./search/search-service.js";
+import { runIndex } from "./indexing/indexing-service.js";
+import { listMarkdownFiles } from "./adapter/repo-walker.js";
+import { repoCacheDir, paths, readManifest, readDocumentStoreExport, readVectorSidecar, vectorIndexExists, checkFreshness, } from "./storage/persistence.js";
+import { scopesToRoots } from "./types.js";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+const EMBEDDING_DIMENSIONS = 384;
+function usage() {
+    return `enact-docs-search — hybrid semantic + keyword search over docs/.plans/.specs
+
+Usage:
+  enact-docs-search index --repo <path> [--scope docs|plans|specs|all] [--force] [--keyword-only] [--exclude <glob>]
+  enact-docs-search query "<text>" --repo <path> [--scope docs|plans|specs|all] [--mode hybrid|keyword|semantic] [--limit N] [--exclude <glob>]
+
+Options:
+  --repo <path>       Target repository root. If omitted, auto-detected by
+                      walking up from the current directory for docs/,
+                      .plans/, or .specs/
+  --scope <scope>     docs | plans | specs | all (default: all)
+  --mode <mode>       hybrid | keyword | semantic (default: hybrid, query only)
+  --limit <n>         Max results to return (default: 10, query only)
+  --force             Full rebuild, ignoring the incremental manifest (index only)
+  --keyword-only      Skip embedding generation entirely (index only, much faster)
+  --exclude <glob>    Additional glob to exclude from scanning; repeatable
+  --json              Emit machine-readable JSON instead of text (query only)
+
+Query automatically incrementally refreshes a missing or stale cache. Use
+index --force only for an explicit full rebuild.
+
+Exit codes: 0 = matches found, 1 = no matches, 2 = usage/dependency error.`;
+}
+function parseArgs(argv) {
+    const parsed = {
+        positional: [],
+        scope: "all",
+        mode: "hybrid",
+        limit: 10,
+        force: false,
+        keywordOnly: false,
+        exclude: [],
+        json: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--repo":
+                parsed.repo = argv[++i];
+                break;
+            case "--scope":
+                parsed.scope = argv[++i];
+                break;
+            case "--mode":
+                parsed.mode = argv[++i];
+                break;
+            case "--limit":
+                parsed.limit = Number(argv[++i]);
+                break;
+            case "--force":
+                parsed.force = true;
+                break;
+            case "--keyword-only":
+                parsed.keywordOnly = true;
+                break;
+            case "--exclude":
+                parsed.exclude.push(argv[++i]);
+                break;
+            case "--json":
+                parsed.json = true;
+                break;
+            case "-h":
+            case "--help":
+                console.log(usage());
+                process.exit(0);
+                break;
+            default:
+                parsed.positional.push(arg);
+        }
+    }
+    return parsed;
+}
+function fail(message) {
+    console.error(`enact-docs-search: FAIL — ${message}`);
+    process.exit(2);
+}
+/** Routine, non-error status line (detected repo root, staleness notice,
+ * ...). Deliberately on stdout via console.log, not console.error/stderr —
+ * stderr renders red in most terminals, and a purely informational message
+ * (nothing failed, nothing needs the user's attention as a problem) reading
+ * as an error is misleading. Reserve stderr for fail() and genuine
+ * unexpected errors. */
+function info(message) {
+    console.log(message);
+}
+/**
+ * Auto-detect a repo root when --repo is omitted: walk up from cwd looking
+ * for a directory that has any of docs/, .plans/, or .specs/. Stops at the
+ * filesystem root. Returns null if nothing is found, so the caller can fail
+ * with a clear message rather than silently picking the wrong directory.
+ */
+function detectRepoRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        for (const marker of ["docs", ".plans", ".specs"]) {
+            if (existsSync(join(dir, marker)))
+                return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function validateScope(scope) {
+    if (!["docs", "plans", "specs", "all"].includes(scope)) {
+        fail(`unknown scope '${scope}' (use docs, plans, specs, or all)`);
+    }
+}
+function validateMode(mode) {
+    if (!["keyword", "semantic", "hybrid"].includes(mode)) {
+        fail(`unknown mode '${mode}' (use keyword, semantic, or hybrid)`);
+    }
+}
+async function cmdIndex(args) {
+    if (!args.repo) {
+        const detected = detectRepoRoot(process.cwd());
+        if (!detected) {
+            fail("--repo <path> was not given, and no docs/, .plans/, or .specs/ found walking up from " +
+                process.cwd() +
+                " — pass --repo explicitly");
+        }
+        args.repo = detected;
+    }
+    validateScope(args.scope);
+    info(`root: ${args.repo} (scope: ${args.scope})`);
+    const t0 = Date.now();
+    let lastPhase = "";
+    const result = await runIndex({
+        repoPath: args.repo,
+        scope: args.scope,
+        force: args.force,
+        skipEmbeddings: args.keywordOnly,
+        exclude: args.exclude,
+        onProgress: (p) => {
+            if (p.phase !== lastPhase) {
+                process.stderr.write(`\n[${p.phase}] `);
+                lastPhase = p.phase;
+            }
+            if (p.totalFiles > 0) {
+                process.stderr.write(`\r[${p.phase}] ${p.filesProcessed}/${p.totalFiles}` + (p.currentFile ? `  ${p.currentFile}` : "         "));
+            }
+        },
+    });
+    process.stderr.write("\n");
+    console.log(`enact-docs-search: indexed scope='${result.scope}' — ` +
+        `${result.filesScanned} files scanned, ${result.filesChanged} changed, ${result.filesRemoved} removed, ` +
+        `${result.chunksIndexed} chunks, ${result.embeddingsGenerated} embeddings ` +
+        `(${(Date.now() - t0)}ms)`);
+    console.log(`enact-docs-search: cache at ${repoCacheDir(args.repo)}`);
+}
+async function cmdQuery(args) {
+    const query = args.positional[0];
+    if (!query)
+        fail("a query string is required");
+    if (!args.repo) {
+        const detected = detectRepoRoot(process.cwd());
+        if (!detected) {
+            fail("--repo <path> was not given, and no docs/, .plans/, or .specs/ found walking up from " +
+                process.cwd() +
+                " — pass --repo explicitly");
+        }
+        args.repo = detected;
+    }
+    validateScope(args.scope);
+    validateMode(args.mode);
+    // In --json mode, stdout must be pure JSON for downstream parsers — route
+    // this status line to stderr instead of suppressing it outright.
+    if (args.json) {
+        console.error(`root: ${args.repo} (scope: ${args.scope}, mode: ${args.mode})`);
+    }
+    else {
+        info(`root: ${args.repo} (scope: ${args.scope}, mode: ${args.mode})`);
+    }
+    const cacheDir = repoCacheDir(args.repo);
+    const manifest = await readManifest(cacheDir);
+    // Freshness check (I-08: refresh stale or missing results before serving them).
+    const roots = scopesToRoots(args.scope);
+    const currentFiles = await listMarkdownFiles(args.repo, roots, { exclude: args.exclude });
+    const freshness = checkFreshness(manifest, args.scope, currentFiles);
+    const hasVectorFile = args.mode !== "keyword" && await vectorIndexExists(cacheDir);
+    const vectorSidecar = args.mode !== "keyword" ? await readVectorSidecar(cacheDir) : null;
+    const needsVectorIndex = args.mode !== "keyword" && (!hasVectorFile || !vectorSidecar);
+    const rebuildVectorIndex = args.mode !== "keyword" && hasVectorFile && !vectorSidecar;
+    const needsRefresh = freshness.neverIndexed || freshness.staleCount > 0 || needsVectorIndex;
+    if (needsRefresh) {
+        const reason = freshness.neverIndexed
+            ? "no index"
+            : freshness.staleCount > 0
+                ? `${freshness.staleCount} changed file(s)`
+                : "no usable vector index";
+        const message = `enact-docs-search: refreshing ${args.scope} index (${reason})`;
+        if (args.json)
+            console.error(message);
+        else
+            info(message);
+        try {
+            await runIndex({
+                repoPath: args.repo,
+                scope: args.scope,
+                force: rebuildVectorIndex,
+                skipEmbeddings: args.mode === "keyword",
+                exclude: args.exclude,
+            });
+        }
+        catch (error) {
+            if (error instanceof VectorDependencyError || error instanceof EmbeddingDependencyError) {
+                fail(error.message);
+            }
+            throw error;
+        }
+    }
+    const docStoreExport = await readDocumentStoreExport(cacheDir);
+    const docStore = new DocumentStore();
+    await docStore.initialize(docStoreExport ?? undefined);
+    let embeddingService = null;
+    const vectorStore = new VectorStore({ dimensions: EMBEDDING_DIMENSIONS });
+    if (args.mode !== "keyword") {
+        const hasVectors = await vectorIndexExists(cacheDir);
+        if (!hasVectors) {
+            fail(`no vector index for scope '${args.scope}' after automatic refresh`);
+        }
+        const sidecar = await readVectorSidecar(cacheDir);
+        if (!sidecar)
+            fail("vector index sidecar is missing or corrupt; re-run index --force");
+        try {
+            await vectorStore.loadFromDisk(paths(cacheDir).vectorIndex, sidecar);
+            embeddingService = new EmbeddingService();
+            await embeddingService.initialize();
+        }
+        catch (error) {
+            if (error instanceof VectorDependencyError || error instanceof EmbeddingDependencyError) {
+                fail(error.message);
+            }
+            throw error;
+        }
+    }
+    const highlight = !args.json && process.stdout.isTTY ? "ansi" : "plain";
+    const searchService = new SearchService(docStore, vectorStore, embeddingService);
+    const results = await searchService.search(query, {
+        mode: args.mode,
+        scope: args.scope,
+        limit: args.limit,
+        highlight,
+        repoRoot: args.repo,
+    });
+    if (args.json) {
+        console.log(JSON.stringify({ query, mode: args.mode, scope: args.scope, results }, null, 2));
+    }
+    else {
+        printResults(query, results);
+    }
+    process.exit(results.length > 0 ? 0 : 1);
+}
+function printResults(query, results) {
+    console.log(`${results.length} result(s) for "${query}"`);
+    if (results.length === 0)
+        return;
+    results.forEach((r, i) => {
+        console.log("");
+        const heading = r.headingBreadcrumb?.length ? ` [${r.headingBreadcrumb.join(" > ")}]` : "";
+        console.log(`${i + 1}. ${r.filePath}:${r.startLine}${heading}`);
+        console.log(`   ${r.snippet ?? ""}`);
+    });
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    if (!command || command === "-h" || command === "--help") {
+        console.log(usage());
+        process.exit(command ? 0 : 2);
+    }
+    const args = parseArgs(rest);
+    switch (command) {
+        case "index":
+            await cmdIndex(args);
+            break;
+        case "query":
+            await cmdQuery(args);
+            break;
+        default:
+            fail(`unknown command '${command}' (use 'index' or 'query')`);
+    }
+}
+main().catch((error) => {
+    console.error(`enact-docs-search: FAIL — unexpected error: ${error.stack ?? error}`);
+    process.exit(2);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/embedding-service.d.ts

@@ -0,0 +1,12 @@
+export declare const EMBEDDING_DIMENSIONS = 384;
+export declare class DependencyError extends Error {
+}
+export declare class EmbeddingService {
+    private embeddingPipeline;
+    private ready;
+    initialize(): Promise<void>;
+    isReady(): boolean;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=embedding-service.d.ts.map

package/dist/embeddings/embedding-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-service.d.ts","sourceRoot":"","sources":["../../src/embeddings/embedding-service.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAE7C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,KAAK,CAAS;IAEhB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC,OAAO,IAAI,OAAO;IAIZ,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAWtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAqBvD"}

package/dist/embeddings/embedding-service.js

@@ -0,0 +1,67 @@
+const MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+export const EMBEDDING_DIMENSIONS = 384;
+export class DependencyError extends Error {
+}
+export class EmbeddingService {
+    embeddingPipeline = null;
+    ready = false;
+    async initialize() {
+        let transformers;
+        try {
+            transformers = await import("@xenova/transformers");
+        }
+        catch (error) {
+            throw new DependencyError("Semantic search requires @xenova/transformers, which is not installed.\n" +
+                "Run `npm install` in the enact-docs-search directory, then retry.\n" +
+                `Original error: ${error.message}`);
+        }
+        const { pipeline, env } = transformers;
+        env.allowLocalModels = false;
+        try {
+            this.embeddingPipeline = (await pipeline("feature-extraction", MODEL_ID, {
+                quantized: false,
+            }));
+            this.ready = true;
+        }
+        catch (error) {
+            throw new DependencyError("Failed to load the local embedding model (Xenova/all-MiniLM-L6-v2).\n" +
+                "This downloads on first use and is then cached; check network access " +
+                "and retry.\n" +
+                `Original error: ${error.message}`);
+        }
+    }
+    isReady() {
+        return this.ready && this.embeddingPipeline !== null;
+    }
+    async embed(text) {
+        if (!this.isReady() || !this.embeddingPipeline) {
+            throw new Error("Embedding service not initialized");
+        }
+        const output = await this.embeddingPipeline(text ?? "", {
+            pooling: "mean",
+            normalize: true,
+        });
+        return Array.from(output.data);
+    }
+    async embedBatch(texts) {
+        if (!this.isReady() || !this.embeddingPipeline) {
+            throw new Error("Embedding service not initialized");
+        }
+        if (texts.length === 0)
+            return [];
+        const safeTexts = texts.map((t) => t ?? "");
+        const output = await this.embeddingPipeline(safeTexts, {
+            pooling: "mean",
+            normalize: true,
+        });
+        const data = output.data;
+        const results = [];
+        for (let i = 0; i < safeTexts.length; i++) {
+            const start = i * EMBEDDING_DIMENSIONS;
+            const end = start + EMBEDDING_DIMENSIONS;
+            results.push(Array.from(data.slice(start, end)));
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=embedding-service.js.map

package/dist/embeddings/embedding-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-service.js","sourceRoot":"","sources":["../../src/embeddings/embedding-service.ts"],"names":[],"mappings":"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"}