@cruxy/cli 0.1.1 → 0.2.0

package/README.md

@@ -25,7 +25,12 @@ cruxy run                           # interactive session
 ## Features
 
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
-  `grep_files`, `run_command`, `git_status`, `apply_patch`.
+  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`.
+- **Codebase index** — a local, incremental semantic index (`cruxy index`)
+  behind the `search_codebase` tool. Embeddings run on-device via fastembed
+  (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at
+  `.cruxy/index.db`. Only changed files are re-embedded; `.gitignore` /
+  `.cruxyignore` are respected and secrets (`.env*`, keys) are never indexed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
 - **Safety** — a single approval gate with diff previews that fails closed;
@@ -36,6 +41,18 @@ Interactive slash commands: `/help`, `/clear`, `/compact`, `/reload`, `/exit`.
 
 For unattended runs, pass `--yes` to approve every action.
 
+### Codebase search
+
+```bash
+cruxy index            # build / refresh the local index (.cruxy/index.db)
+cruxy index --status   # show what's indexed
+cruxy index --force    # re-embed every file
+```
+
+The index refreshes itself lazily the first time the agent calls
+`search_codebase`, so it works even without running `cruxy index` first. The
+bge-small embedding model (~130 MB) downloads and caches on first use.
+
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.
 

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy index` — build or refresh the local codebase search index that backs
+ * the `search_codebase` tool. `--status` reports the current state without
+ * modifying it; `--force` re-embeds every file regardless of content hashes.
+ */
+export declare function indexCommand(): Command;

package/dist/cli/commands/index.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { getIndexService, indexDbPath, resetIndexServices, } from "../../indexing/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy index` — build or refresh the local codebase search index that backs
+ * the `search_codebase` tool. `--status` reports the current state without
+ * modifying it; `--force` re-embeds every file regardless of content hashes.
+ */
+export function indexCommand() {
+    return new Command("index")
+        .description("build or refresh the local codebase search index")
+        .option("--status", "show index status without building")
+        .option("--force", "re-embed every file, ignoring content hashes")
+        .action(async (opts) => {
+        const { config } = loadConfig();
+        if (!config.index.enabled) {
+            logger.warn("codebase indexing is disabled (index.enabled = false)");
+            return;
+        }
+        const cwd = process.cwd();
+        if (opts.status) {
+            // Don't create an empty DB just to report "no index built yet".
+            if (config.index.store !== "memory" && !existsSync(indexDbPath(cwd))) {
+                logger.print(`${pc.bold("index:")} ${pc.dim("not built yet")} — run ${pc.bold("cruxy index")}`);
+                return;
+            }
+            const service = await getIndexService(cwd, config, logger);
+            printStatus(service.status());
+            await resetIndexServices();
+            return;
+        }
+        logger.info(pc.dim(`indexing ${cwd} …`));
+        logger.info(pc.dim("(first run may download the local embedding model)"));
+        const service = await getIndexService(cwd, config, logger);
+        try {
+            const stats = await service.index({ force: opts.force });
+            logger.print(`${pc.green("indexed")} ${stats.filesIndexed} file(s), ${stats.chunksIndexed} chunk(s) ` +
+                pc.dim(`(${stats.filesSkipped} unchanged, ${stats.filesPurged} purged, ${stats.durationMs}ms)`));
+        }
+        catch (err) {
+            logger.error(`indexing failed: ${err.message}`);
+            process.exitCode = 1;
+        }
+        finally {
+            await resetIndexServices();
+        }
+    });
+}
+function printStatus(status) {
+    logger.print(`${pc.bold("index:")}    ${status.exists ? pc.green("built") : pc.yellow("empty")}`);
+    logger.print(`${pc.bold("store:")}    ${status.storePath ?? "(in-memory)"}`);
+    logger.print(`${pc.bold("embedder:")} ${status.embedderId ?? pc.dim("(none)")}` +
+        (status.dim ? pc.dim(` · ${status.dim}d`) : ""));
+    logger.print(`${pc.bold("files:")}    ${status.files}`);
+    logger.print(`${pc.bold("chunks:")}   ${status.chunks}`);
+}

package/dist/cli/program.js

@@ -4,6 +4,7 @@ import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
 import { logger } from "../utils/logger.js";
 import { runCommand } from "./commands/run.js";
 import { configCommand } from "./commands/config.js";
+import { indexCommand } from "./commands/index.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -24,6 +25,7 @@ export function buildProgram() {
     });
     program.addCommand(runCommand());
     program.addCommand(configCommand());
+    program.addCommand(indexCommand());
     // Default action: no subcommand -> interactive entrypoint (stub for now).
     program.action(() => {
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));

package/dist/config/schema.d.ts

@@ -97,6 +97,93 @@ export declare const ApprovalConfigSchema: z.ZodObject<{
 }, {
     mode?: "auto" | "prompt" | undefined;
 }>;
+/**
+ * Codebase semantic index (C.17): the local embedding index that backs the
+ * `search_codebase` tool and `cruxy index`. Every field is defaulted so the
+ * feature works with zero configuration.
+ */
+export declare const IndexConfigSchema: z.ZodObject<{
+    /** Master switch for `search_codebase` and `cruxy index`. */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
+     * model downloads and caches on first use) is selectable — if it cannot be
+     * loaded, indexing fails loudly rather than degrading. (The deterministic
+     * hashing embedder exists for tests and is injected directly, never chosen
+     * here.)
+     */
+    embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
+    /**
+     * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
+     * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
+     * falls back to memory when the native dependency cannot be loaded.
+     */
+    store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
+    /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
+    maxFileBytes: z.ZodDefault<z.ZodNumber>;
+    chunk: z.ZodEffects<z.ZodDefault<z.ZodObject<{
+        /** Target chunk window, in lines. */
+        windowLines: z.ZodDefault<z.ZodNumber>;
+        /** Lines shared between consecutive chunks; must be < windowLines. */
+        overlapLines: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        windowLines: number;
+        overlapLines: number;
+    }, {
+        windowLines?: number | undefined;
+        overlapLines?: number | undefined;
+    }>>, {
+        windowLines: number;
+        overlapLines: number;
+    }, {
+        windowLines?: number | undefined;
+        overlapLines?: number | undefined;
+    } | undefined>;
+    search: z.ZodDefault<z.ZodObject<{
+        /** Number of hits returned when the tool omits `k`. */
+        defaultK: z.ZodDefault<z.ZodNumber>;
+        /** Approximate token budget for combined snippets (chars/4 heuristic). */
+        tokenBudget: z.ZodDefault<z.ZodNumber>;
+        /** Maximum lines kept in any single returned snippet. */
+        maxSnippetLines: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        defaultK: number;
+        tokenBudget: number;
+        maxSnippetLines: number;
+    }, {
+        defaultK?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxSnippetLines?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    search: {
+        defaultK: number;
+        tokenBudget: number;
+        maxSnippetLines: number;
+    };
+    enabled: boolean;
+    embedder: "fastembed";
+    store: "auto" | "sqlite" | "memory";
+    maxFileBytes: number;
+    chunk: {
+        windowLines: number;
+        overlapLines: number;
+    };
+}, {
+    search?: {
+        defaultK?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxSnippetLines?: number | undefined;
+    } | undefined;
+    enabled?: boolean | undefined;
+    embedder?: "fastembed" | undefined;
+    store?: "auto" | "sqlite" | "memory" | undefined;
+    maxFileBytes?: number | undefined;
+    chunk?: {
+        windowLines?: number | undefined;
+        overlapLines?: number | undefined;
+    } | undefined;
+}>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -203,6 +290,88 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }, {
         mode?: "auto" | "prompt" | undefined;
     }>>;
+    index: z.ZodDefault<z.ZodObject<{
+        /** Master switch for `search_codebase` and `cruxy index`. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
+         * model downloads and caches on first use) is selectable — if it cannot be
+         * loaded, indexing fails loudly rather than degrading. (The deterministic
+         * hashing embedder exists for tests and is injected directly, never chosen
+         * here.)
+         */
+        embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
+        /**
+         * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
+         * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
+         * falls back to memory when the native dependency cannot be loaded.
+         */
+        store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
+        /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
+        maxFileBytes: z.ZodDefault<z.ZodNumber>;
+        chunk: z.ZodEffects<z.ZodDefault<z.ZodObject<{
+            /** Target chunk window, in lines. */
+            windowLines: z.ZodDefault<z.ZodNumber>;
+            /** Lines shared between consecutive chunks; must be < windowLines. */
+            overlapLines: z.ZodDefault<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            windowLines: number;
+            overlapLines: number;
+        }, {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        }>>, {
+            windowLines: number;
+            overlapLines: number;
+        }, {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        } | undefined>;
+        search: z.ZodDefault<z.ZodObject<{
+            /** Number of hits returned when the tool omits `k`. */
+            defaultK: z.ZodDefault<z.ZodNumber>;
+            /** Approximate token budget for combined snippets (chars/4 heuristic). */
+            tokenBudget: z.ZodDefault<z.ZodNumber>;
+            /** Maximum lines kept in any single returned snippet. */
+            maxSnippetLines: z.ZodDefault<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            defaultK: number;
+            tokenBudget: number;
+            maxSnippetLines: number;
+        }, {
+            defaultK?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxSnippetLines?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        search: {
+            defaultK: number;
+            tokenBudget: number;
+            maxSnippetLines: number;
+        };
+        enabled: boolean;
+        embedder: "fastembed";
+        store: "auto" | "sqlite" | "memory";
+        maxFileBytes: number;
+        chunk: {
+            windowLines: number;
+            overlapLines: number;
+        };
+    }, {
+        search?: {
+            defaultK?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxSnippetLines?: number | undefined;
+        } | undefined;
+        enabled?: boolean | undefined;
+        embedder?: "fastembed" | undefined;
+        store?: "auto" | "sqlite" | "memory" | undefined;
+        maxFileBytes?: number | undefined;
+        chunk?: {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        } | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -251,6 +420,21 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval: {
         mode: "auto" | "prompt";
     };
+    index: {
+        search: {
+            defaultK: number;
+            tokenBudget: number;
+            maxSnippetLines: number;
+        };
+        enabled: boolean;
+        embedder: "fastembed";
+        store: "auto" | "sqlite" | "memory";
+        maxFileBytes: number;
+        chunk: {
+            windowLines: number;
+            overlapLines: number;
+        };
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -291,6 +475,21 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval?: {
         mode?: "auto" | "prompt" | undefined;
     } | undefined;
+    index?: {
+        search?: {
+            defaultK?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxSnippetLines?: number | undefined;
+        } | undefined;
+        enabled?: boolean | undefined;
+        embedder?: "fastembed" | undefined;
+        store?: "auto" | "sqlite" | "memory" | undefined;
+        maxFileBytes?: number | undefined;
+        chunk?: {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        } | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -72,6 +72,60 @@ export const ApprovalConfigSchema = z
     mode: z.enum(["prompt", "auto"]).default("prompt"),
 })
     .strict();
+/**
+ * Codebase semantic index (C.17): the local embedding index that backs the
+ * `search_codebase` tool and `cruxy index`. Every field is defaulted so the
+ * feature works with zero configuration.
+ */
+export const IndexConfigSchema = z
+    .object({
+    /** Master switch for `search_codebase` and `cruxy index`. */
+    enabled: z.boolean().default(true),
+    /**
+     * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
+     * model downloads and caches on first use) is selectable — if it cannot be
+     * loaded, indexing fails loudly rather than degrading. (The deterministic
+     * hashing embedder exists for tests and is injected directly, never chosen
+     * here.)
+     */
+    embedder: z.enum(["fastembed"]).default("fastembed"),
+    /**
+     * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
+     * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
+     * falls back to memory when the native dependency cannot be loaded.
+     */
+    store: z.enum(["auto", "sqlite", "memory"]).default("auto"),
+    /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
+    maxFileBytes: z
+        .number()
+        .int()
+        .positive()
+        .default(1024 * 1024),
+    chunk: z
+        .object({
+        /** Target chunk window, in lines. */
+        windowLines: z.number().int().positive().default(60),
+        /** Lines shared between consecutive chunks; must be < windowLines. */
+        overlapLines: z.number().int().nonnegative().default(15),
+    })
+        .strict()
+        .default({})
+        .refine((c) => c.overlapLines < c.windowLines, {
+        message: "index.chunk.overlapLines must be less than windowLines",
+    }),
+    search: z
+        .object({
+        /** Number of hits returned when the tool omits `k`. */
+        defaultK: z.number().int().positive().default(8),
+        /** Approximate token budget for combined snippets (chars/4 heuristic). */
+        tokenBudget: z.number().int().positive().default(1500),
+        /** Maximum lines kept in any single returned snippet. */
+        maxSnippetLines: z.number().int().positive().default(40),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -90,6 +144,7 @@ export const CruxyConfigSchema = z
     shell: ShellConfigSchema.default({}),
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
+    index: IndexConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/indexing/chunker.d.ts

@@ -0,0 +1,28 @@
+import type { Chunk } from "./types.js";
+/** Knobs for {@link chunkFile}. */
+export interface ChunkOptions {
+    /** Target window size, in lines. */
+    windowLines: number;
+    /** Lines shared between consecutive windows (clamped to < windowLines). */
+    overlapLines: number;
+    /**
+     * How far (in lines) the window end may slide to land on a blank-line
+     * boundary. Keeps chunks aligned to natural gaps without drifting too far
+     * from the target size.
+     */
+    snapSlack?: number;
+}
+/**
+ * Split a file's text into overlapping line windows.
+ *
+ * Windows are `windowLines` long and advance by `windowLines - overlapLines`, so
+ * consecutive chunks share `overlapLines` lines (context that would otherwise be
+ * severed at a hard cut). Where possible the window end is nudged — within
+ * `snapSlack` lines — to fall right after a blank line, so chunks break at
+ * natural boundaries (between functions, paragraphs, etc.).
+ *
+ * Line numbers are 1-based and inclusive. A whitespace-only (or empty) file
+ * yields no chunks. A file shorter than one window yields exactly one chunk.
+ * Coverage is gap-free: every source line belongs to at least one chunk.
+ */
+export declare function chunkFile(path: string, text: string, opts: ChunkOptions): Chunk[];

package/dist/indexing/chunker.js

@@ -0,0 +1,65 @@
+const DEFAULT_SNAP_SLACK = 8;
+/**
+ * Split a file's text into overlapping line windows.
+ *
+ * Windows are `windowLines` long and advance by `windowLines - overlapLines`, so
+ * consecutive chunks share `overlapLines` lines (context that would otherwise be
+ * severed at a hard cut). Where possible the window end is nudged — within
+ * `snapSlack` lines — to fall right after a blank line, so chunks break at
+ * natural boundaries (between functions, paragraphs, etc.).
+ *
+ * Line numbers are 1-based and inclusive. A whitespace-only (or empty) file
+ * yields no chunks. A file shorter than one window yields exactly one chunk.
+ * Coverage is gap-free: every source line belongs to at least one chunk.
+ */
+export function chunkFile(path, text, opts) {
+    if (text.trim() === "")
+        return [];
+    const lines = text.split("\n");
+    // A trailing newline produces a phantom empty final element; drop it so line
+    // counts match what an editor shows.
+    if (lines.length > 1 && lines[lines.length - 1] === "")
+        lines.pop();
+    const n = lines.length;
+    const window = Math.max(1, Math.floor(opts.windowLines));
+    const overlap = Math.min(Math.max(0, Math.floor(opts.overlapLines)), window - 1);
+    const slack = Math.max(0, opts.snapSlack ?? DEFAULT_SNAP_SLACK);
+    const chunks = [];
+    let start = 0; // 0-based, inclusive
+    while (start < n) {
+        let end = Math.min(start + window, n); // 0-based, exclusive
+        // Snap the end to a nearby blank-line boundary (the last included line is
+        // blank), unless we've already reached EOF.
+        if (end < n && slack > 0) {
+            const lo = Math.max(start + 1, end - slack);
+            const hi = Math.min(n, end + slack);
+            let best = -1;
+            let bestDist = Infinity;
+            for (let e = lo; e <= hi; e++) {
+                const endsOnBlank = e === n || lines[e - 1].trim() === "";
+                if (!endsOnBlank)
+                    continue;
+                const dist = Math.abs(e - end);
+                if (dist < bestDist) {
+                    bestDist = dist;
+                    best = e;
+                }
+            }
+            if (best !== -1)
+                end = best;
+        }
+        chunks.push({
+            path,
+            startLine: start + 1,
+            endLine: end,
+            text: lines.slice(start, end).join("\n"),
+        });
+        if (end >= n)
+            break;
+        // Advance by the window stride, but never regress (a short snapped window
+        // could otherwise leave nextStart <= start).
+        const nextStart = end - overlap;
+        start = nextStart > start ? nextStart : end;
+    }
+    return chunks;
+}

package/dist/indexing/embedder.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Output dimensionality of bge-small-en-v1.5, and the default size of the
+ * hashing embedder's feature space, so the two backends are interchangeable in
+ * the store schema.
+ */
+export declare const DEFAULT_DIM = 384;
+/**
+ * Turns text into vectors. Two implementations ship: {@link FastEmbedEmbedder}
+ * (local ONNX, semantic) and {@link HashingEmbedder} (dependency-free,
+ * deterministic, lexical). The store records `id`; if it changes, the index is
+ * re-embedded from scratch (see `indexer.ts`).
+ */
+export interface Embedder {
+    /** Stable identity of this embedder + model. Persisted with the index. */
+    readonly id: string;
+    /** Embedding dimensionality. */
+    readonly dim: number;
+    /**
+     * Embed document/passage texts. Returns one L2-normalized vector per input,
+     * in the same order. An empty input yields an empty array.
+     */
+    embed(texts: string[]): Promise<Float32Array[]>;
+    /**
+     * Embed a search query. May use a different representation than {@link embed}
+     * (e.g. bge prepends a retrieval instruction to queries).
+     */
+    embedQuery(text: string): Promise<Float32Array>;
+}
+/**
+ * Split text into lowercase lexical tokens, breaking identifiers on camelCase
+ * and snake/kebab boundaries so `getUserById` contributes `get`/`user`/`by`/`id`.
+ */
+export declare function tokenize(text: string): string[];
+export interface HashingEmbedderOptions {
+    dim?: number;
+}
+/**
+ * A deterministic, dependency-free embedder: signed feature hashing
+ * (bag-of-words) over code-aware tokens, L2-normalized. It captures lexical
+ * overlap rather than true semantics, but it is offline, instant, and stable —
+ * which makes it the right default for tests and a sane fallback when the native
+ * embedding model is unavailable.
+ */
+export declare class HashingEmbedder implements Embedder {
+    readonly id: string;
+    readonly dim: number;
+    constructor(opts?: HashingEmbedderOptions);
+    embed(texts: string[]): Promise<Float32Array[]>;
+    embedQuery(text: string): Promise<Float32Array>;
+    private embedOne;
+}
+export interface FastEmbedEmbedderOptions {
+    /** Where the ONNX model is downloaded/cached. Defaults to fastembed's own dir. */
+    cacheDir?: string;
+    /** Max model input length, in tokens. */
+    maxLength?: number;
+    /** Texts per inference batch. */
+    batchSize?: number;
+    /** Print the model download progress on first run. */
+    showDownloadProgress?: boolean;
+}
+/**
+ * Local semantic embeddings via fastembed (ONNX), model bge-small-en-v1.5
+ * (384-dim). The native dependency is imported lazily on first use, so merely
+ * registering the `search_codebase` tool stays cheap and the heavy ONNX runtime
+ * only loads when an index is actually built or queried.
+ *
+ * Embedding is CPU-bound and single-threaded inside ONNX, so throughput is
+ * bounded by `batchSize` (fed sequentially through fastembed's batching
+ * generator) rather than by JS-level concurrency.
+ */
+export declare class FastEmbedEmbedder implements Embedder {
+    readonly id = "fastembed:bge-small-en-v1.5";
+    readonly dim = 384;
+    private readonly opts;
+    private model;
+    constructor(opts?: FastEmbedEmbedderOptions);
+    private getModel;
+    embed(texts: string[]): Promise<Float32Array[]>;
+    embedQuery(text: string): Promise<Float32Array>;
+}
+export interface CreateEmbedderOptions {
+    /** Cache dir for the fastembed model. */
+    cacheDir?: string;
+}
+/**
+ * Build the **production** embedder: fastembed / bge-small-en-v1.5.
+ *
+ * The native dependency is loaded eagerly here so a missing or broken install
+ * fails *now*, loudly, with an actionable message — rather than silently
+ * degrading search quality at query time. There is deliberately **no** fallback
+ * to {@link HashingEmbedder}: that backend is reachable only by explicit
+ * injection in tests (see `getIndexService`'s `deps.embedder`), never selected
+ * automatically by this factory or by config.
+ *
+ * @throws if the fastembed native module cannot be loaded.
+ */
+export declare function createEmbedder(opts?: CreateEmbedderOptions): Promise<Embedder>;