@toolbaux/guardian 0.1.23 → 0.2.1

package/dist/commands/init.js

@@ -13,32 +13,62 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { DEFAULT_SPECS_DIR } from "../config.js";
 const DEFAULT_CONFIG = {
     docs: {
         mode: "full",
     },
 };
+/**
+ * Hook script written to .claude/hooks/mcp-first.sh
+ *
+ * Blocks Read/Glob/Grep until a guardian MCP tool has been called in the
+ * current session. Session state lives in /tmp/guardian-used-<SESSION_ID>
+ * and is set by the PostToolUse hook (guardian-used.sh) below.
+ */
 const CLAUDE_CODE_HOOK_SCRIPT = `#!/bin/bash
-# Guardian MCP-first hook — ensures AI tools use Guardian MCP before reading source files.
-# Installed by: guardian init
+# Guardian MCP-first hook — blocks Read/Glob/Grep until guardian tools are used.
+# Installed by: guardian init  (v3 — session-scoped flag, no time drift)
 
 INPUT=$(cat)
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "default"')
+FLAG="/tmp/guardian-used-\${SESSION_ID}"
 
-cat >&2 <<BLOCK
-BLOCKED: Use Guardian MCP tools before reading source files.
+# If guardian was called in this session, allow all file operations.
+if [ -f "$FLAG" ]; then
+  exit 0
+fi
+
+cat >&2 <<'BLOCK'
+BLOCKED: Use Guardian MCP tools before exploring source files.
 
-Use these MCP tools first:
-  - guardian_orient  — get codebase overview
-  - guardian_search  — find features by keyword
-  - guardian_context — deep dive into a specific area
+Call one of these first:
+  guardian_search("your query")  — find files/symbols/endpoints by keyword
+  guardian_grep("pattern")       — semantic grep (replaces Grep tool)
+  guardian_glob("src/auth/**")   — semantic file discovery (replaces Glob tool)
+  guardian_orient()              — get codebase overview
 
-Then you can read individual files as needed.
+File reads are unblocked automatically for the rest of this session.
 BLOCK
 
 exit 2
 `;
+/**
+ * Hook script written to .claude/hooks/guardian-used.sh
+ *
+ * Called by PostToolUse after any guardian_* tool. Sets the session flag
+ * that mcp-first.sh checks, unblocking subsequent Read/Glob/Grep calls.
+ */
+const GUARDIAN_USED_SCRIPT = `#!/bin/bash
+# Guardian PostToolUse hook — marks guardian as used for this session.
+# Installed by: guardian init
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "default"')
+touch "/tmp/guardian-used-\${SESSION_ID}"
+exit 0
+`;
 const HOOK_SCRIPT = `#!/bin/sh
 # guardian pre-commit hook — keeps architecture context fresh
 # Installed by: guardian init
@@ -80,6 +110,22 @@ export async function runInit(options) {
     else {
         console.log("  · guardian.config.json already exists");
     }
+    // 2b. Ensure project_id is present in guardian.config.json
+    try {
+        const raw = await fs.readFile(configPath, "utf8");
+        const cfg = JSON.parse(raw);
+        if (!cfg.project_id) {
+            cfg.project_id = randomUUID();
+            await fs.writeFile(configPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+            console.log("  ✓ Added project_id to guardian.config.json");
+        }
+        else {
+            console.log("  · guardian.config.json already has project_id");
+        }
+    }
+    catch {
+        // Non-fatal — config may not be valid JSON yet
+    }
     // 3. Install pre-commit hook
     if (!options.skipHook) {
         const gitDir = path.join(root, ".git");
@@ -158,8 +204,6 @@ export async function runInit(options) {
         const { runExtract } = await import("./extract.js");
         await runExtract({
             projectRoot: root,
-            backendRoot: options.backendRoot,
-            frontendRoot: options.frontendRoot,
             output: specsDir,
             includeFileGraph: true,
             backend: options.backend,
@@ -167,8 +211,6 @@ export async function runInit(options) {
         const { runGenerate } = await import("./generate.js");
         await runGenerate({
             projectRoot: root,
-            backendRoot: options.backendRoot,
-            frontendRoot: options.frontendRoot,
             output: specsDir,
             aiContext: true,
         });
@@ -213,18 +255,13 @@ async function setupClaudeCodeHooks(root, specsDir) {
             try {
                 mcpConfig = JSON.parse(await fs.readFile(mcpJsonPath, "utf8"));
             }
-            catch {
-                // Corrupted — overwrite
-            }
+            catch { /* corrupted — overwrite */ }
         }
         if (!mcpConfig.mcpServers)
             mcpConfig.mcpServers = {};
         const servers = mcpConfig.mcpServers;
         if (!servers.guardian) {
-            servers.guardian = {
-                command: "guardian",
-                args: ["mcp-serve", "--specs", specsDir],
-            };
+            servers.guardian = { command: "guardian", args: ["mcp-serve", "--specs", specsDir] };
             await fs.writeFile(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf8");
             console.log("  ✓ Created .mcp.json (MCP server config)");
         }
@@ -238,58 +275,49 @@ async function setupClaudeCodeHooks(root, specsDir) {
     const claudeDir = path.join(root, ".claude");
     const hooksDir = path.join(claudeDir, "hooks");
     const settingsPath = path.join(claudeDir, "settings.json");
-    const hookScriptPath = path.join(hooksDir, "mcp-first.sh");
+    const mcpFirstPath = path.join(hooksDir, "mcp-first.sh");
+    const guardianUsedPath = path.join(hooksDir, "guardian-used.sh");
     await fs.mkdir(hooksDir, { recursive: true });
-    // Write the hook script
-    if (!(await fileExists(hookScriptPath))) {
-        await fs.writeFile(hookScriptPath, CLAUDE_CODE_HOOK_SCRIPT, "utf8");
-        await fs.chmod(hookScriptPath, 0o755);
-        console.log("  ✓ Created Claude Code MCP-first hook (.claude/hooks/mcp-first.sh)");
-    }
-    else {
-        console.log("  · Claude Code hook already exists");
-    }
+    // Always overwrite hook scripts so they stay in sync with this version of guardian.
+    await fs.writeFile(mcpFirstPath, CLAUDE_CODE_HOOK_SCRIPT, "utf8");
+    await fs.chmod(mcpFirstPath, 0o755);
+    console.log("  ✓ Wrote .claude/hooks/mcp-first.sh (PreToolUse — blocks until guardian called)");
+    await fs.writeFile(guardianUsedPath, GUARDIAN_USED_SCRIPT, "utf8");
+    await fs.chmod(guardianUsedPath, 0o755);
+    console.log("  ✓ Wrote .claude/hooks/guardian-used.sh (PostToolUse — sets session flag)");
     // Write or merge .claude/settings.json
     let settings = {};
     if (await fileExists(settingsPath)) {
         try {
             settings = JSON.parse(await fs.readFile(settingsPath, "utf8"));
         }
-        catch {
-            // Corrupted file — overwrite
-        }
+        catch { /* corrupted — overwrite */ }
     }
-    // Add MCP server config
+    // MCP server registration
     if (!settings.mcpServers)
         settings.mcpServers = {};
-    const mcpServers = settings.mcpServers;
-    if (!mcpServers.guardian) {
-        mcpServers.guardian = {
-            command: "guardian",
-            args: ["mcp-serve", "--specs", specsDir],
-        };
-    }
-    // Add PreToolUse hook
-    const hookEntry = {
-        matcher: "Read|Glob|Grep",
-        hooks: [
+    settings.mcpServers.guardian = {
+        command: "guardian",
+        args: ["mcp-serve", "--specs", specsDir],
+    };
+    // Hooks — always overwrite to keep in sync with installed scripts.
+    settings.hooks = {
+        // PreToolUse: block Read/Glob/Grep until a guardian tool has been called.
+        // The script itself handles the session-flag check — no "if" filter needed here.
+        PreToolUse: [
+            {
+                matcher: "Read|Glob|Grep",
+                hooks: [{ type: "command", command: ".claude/hooks/mcp-first.sh" }],
+            },
+        ],
+        // PostToolUse: set the session flag after any guardian MCP tool call.
+        PostToolUse: [
             {
-                type: "command",
-                if: "Read(//*/src/*)|Glob(*src*)|Grep(*src*)",
-                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/mcp-first.sh',
+                matcher: "mcp__guardian__guardian_search|mcp__guardian__guardian_orient|mcp__guardian__guardian_context|mcp__guardian__guardian_impact|mcp__guardian__guardian_grep|mcp__guardian__guardian_glob",
+                hooks: [{ type: "command", command: ".claude/hooks/guardian-used.sh" }],
             },
         ],
     };
-    if (!settings.hooks)
-        settings.hooks = {};
-    const hooks = settings.hooks;
-    if (!hooks.PreToolUse) {
-        hooks.PreToolUse = [hookEntry];
-        console.log("  ✓ Configured Claude Code PreToolUse hook in .claude/settings.json");
-    }
-    else {
-        console.log("  · Claude Code PreToolUse hook already configured");
-    }
     await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-    console.log("  ✓ Updated .claude/settings.json (MCP server + hooks)");
+    console.log("  ✓ Updated .claude/settings.json (MCP server + PreToolUse + PostToolUse hooks)");
 }

package/dist/commands/intel.js

@@ -13,6 +13,7 @@ import { writeCodebaseIntelligenceViaStore } from "../extract/codebase-intel.js"
 import { getOutputLayout } from "../output-layout.js";
 import { SqliteSpecsStore } from "../db/sqlite-specs-store.js";
 import { populateFTSIndex } from "../db/fts-builder.js";
+import { embedFunctions } from "../db/embeddings.js";
 export async function runIntel(options) {
     const specsDir = path.resolve(options.specs);
     const layout = getOutputLayout(specsDir);
@@ -49,6 +50,28 @@ export async function runIntel(options) {
                 catch { /* not generated yet — skip */ }
                 populateFTSIndex(store, intel, arch, funcIntel);
                 console.log(`Built FTS5 search index (${Object.keys(intel.api_registry ?? {}).length} endpoints indexed)`);
+                // Populate module_metrics from structural-intelligence.json (if present).
+                try {
+                    const siRaw = await (await import("node:fs/promises")).readFile((await import("node:path")).join(machineDir, "structural-intelligence.json"), "utf8");
+                    const siReports = JSON.parse(siRaw);
+                    if (Array.isArray(siReports) && siReports.length > 0) {
+                        store.rebuildModuleMetrics(siReports);
+                        console.log(`Indexed ${siReports.length} module metrics`);
+                    }
+                }
+                catch { /* structural-intelligence.json not generated yet — skip */ }
+                // Embed functions for semantic (vector) search.
+                // Uses local on-device model by default (no API key needed).
+                // If OPENAI_API_KEY is set, uses OpenAI text-embedding-3-small (better quality).
+                if (funcIntel?.functions?.length) {
+                    console.log(`[guardian embed] embedding ${funcIntel.functions.length} functions…`);
+                    try {
+                        await embedFunctions(store, funcIntel.functions, process.env.OPENAI_API_KEY);
+                    }
+                    catch (err) {
+                        console.warn(`[guardian embed] skipped: ${err.message}`);
+                    }
+                }
             }
             console.log(`Wrote guardian.db → ${layout.rootDir}`);
         }

package/dist/commands/mcp-serve.js

@@ -111,6 +111,83 @@ async function search(args) {
 async function model(args) {
     return runCli(["search", "--model", args.name, "--input", specsInputDir]);
 }
+/**
+ * guardian_grep — semantic grep via guardian search.
+ *
+ * Replaces raw Grep tool calls. Runs guardian BM25+vector search and returns
+ * matching symbols (file:line:name) and files, formatted like grep output.
+ * Claude gets richer context (call-graph, authority) with zero token overhead.
+ */
+async function grep(args) {
+    const raw = await runCli([
+        "search", "--query", args.query, "--format", "json", "--backend", "auto", "--input", specsInputDir,
+    ]);
+    try {
+        const data = JSON.parse(raw);
+        const lines = [`guardian_grep("${args.query}")`];
+        if (data.symbols?.length) {
+            lines.push("\nSymbols (file:line: name):");
+            for (const s of data.symbols.slice(0, 25)) {
+                lines.push(`  ${s.file}:${s.line}: ${s.name}`);
+            }
+        }
+        if (data.files?.length) {
+            lines.push("\nFiles:");
+            for (const f of data.files.slice(0, 15)) {
+                lines.push(`  ${f.file_path}`);
+            }
+        }
+        if (lines.length === 1)
+            lines.push("  (no matches — try a different query)");
+        return lines.join("\n");
+    }
+    catch {
+        return raw; // passthrough if search returns plain text
+    }
+}
+/**
+ * guardian_glob — semantic file discovery via guardian search.
+ *
+ * Replaces raw Glob tool calls. Extracts meaningful keywords from the glob
+ * pattern and searches the guardian index for matching files. Falls back to
+ * guiding the user toward a more descriptive query for pure extension patterns.
+ */
+async function glob(args) {
+    // Extract keywords: "src/auth/**/*.ts" → "auth", "src/middleware/error*" → "middleware error"
+    const keywords = args.pattern
+        .replace(/\*\*?/g, " ")
+        .replace(/\.\w+$/, "") // strip trailing extension
+        .replace(/[[\]{}]/g, " ")
+        .split(/[/\s]+/)
+        .filter(s => s.length > 2 && !/^(src|lib|dist|app|index)$/.test(s))
+        .join(" ")
+        .trim();
+    if (!keywords) {
+        return [
+            `guardian_glob("${args.pattern}"): pattern has no meaningful keywords.`,
+            `Use guardian_search with a descriptive query instead, e.g.:`,
+            `  guardian_search("TypeScript source files") — or describe what you're looking for.`,
+        ].join("\n");
+    }
+    const raw = await runCli([
+        "search", "--query", keywords, "--format", "json", "--backend", "auto", "--input", specsInputDir,
+    ]);
+    try {
+        const data = JSON.parse(raw);
+        const files = data.files ?? [];
+        const lines = [
+            `guardian_glob("${args.pattern}") — searched: "${keywords}"`,
+            `\nMatching files:`,
+            ...files.slice(0, 20).map(f => `  ${f.file_path}`),
+        ];
+        if (files.length === 0)
+            lines.push("  (no matches)");
+        return lines.join("\n");
+    }
+    catch {
+        return raw;
+    }
+}
 // ── MCP protocol ──
 const TOOLS = [
     {
@@ -167,6 +244,39 @@ const TOOLS = [
         description: "MCP usage stats for this session. Call at end to evaluate guardian's usefulness.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "guardian_grep",
+        description: [
+            "Semantic grep — find symbols and files matching a keyword or pattern.",
+            "Use INSTEAD of the Grep tool. Returns matching function/class names with file:line locations.",
+            "Backed by BM25 + call-graph authority so relevant source definitions surface first.",
+            "Example: guardian_grep('validate token') → auth.py:42: validate_token, middleware.py:18: check_jwt",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Keyword or phrase to search for (natural language OK)" },
+                path: { type: "string", description: "Optional: restrict to files under this path prefix" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "guardian_glob",
+        description: [
+            "Semantic file discovery — find files matching a path pattern.",
+            "Use INSTEAD of the Glob tool. Extracts keywords from the pattern and searches the guardian index.",
+            "Example: guardian_glob('src/auth/**/*.ts') → searches for 'auth typescript' files.",
+            "For pure extension globs with no path context, use guardian_search with a descriptive query.",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "Glob pattern (e.g. 'src/auth/**/*.ts', '**/middleware*')" },
+            },
+            required: ["pattern"],
+        },
+    },
 ];
 const TOOL_HANDLERS = {
     guardian_orient: orient,
@@ -175,6 +285,8 @@ const TOOL_HANDLERS = {
     guardian_search: search,
     guardian_model: model,
     guardian_metrics: async () => JSON.stringify(metrics.summary()),
+    guardian_grep: grep,
+    guardian_glob: glob,
 };
 function respond(id, result) {
     const msg = JSON.stringify({ jsonrpc: "2.0", id, result });

package/dist/commands/search.js

@@ -17,6 +17,7 @@ export async function runSearch(options) {
             if (sqliteResult !== null) {
                 const base = JSON.parse(await querySearch(inputDir, options.query));
                 base.files = sqliteResult.files;
+                base.symbols = sqliteResult.symbols;
                 base.search_signal = sqliteResult.signal;
                 console.log(JSON.stringify(base));
                 return;
@@ -138,12 +139,36 @@ async function runSearchSqlite(specsInput, query, limit, backend = "sqlite") {
             console.log(`No FTS results for "${query}"`);
             return true;
         }
+        let queryVec;
+        try {
+            const { embedQuery } = await import("../db/embeddings.js");
+            const vec = await embedQuery(cleaned || query, process.env.OPENAI_API_KEY);
+            if (vec)
+                queryVec = vec;
+        }
+        catch { /* graceful degradation */ }
+        const symbols = store.searchSymbols(cleaned || query, Math.ceil(limit / 2), queryVec);
         const lines = [`## FTS5 search: "${query}"\n`];
+        // Build a map of file → matching symbols for quick lookup
+        const symbolsByFile = new Map();
+        for (const s of symbols) {
+            if (!symbolsByFile.has(s.file_path))
+                symbolsByFile.set(s.file_path, []);
+            symbolsByFile.get(s.file_path).push({ name: s.name, line: s.line });
+        }
         for (const r of results) {
             const rank = Math.abs(r.rank).toFixed(3);
             lines.push(`### \`${r.file_path}\`  (score: ${rank})`);
-            if (r.symbol_name)
-                lines.push(`  symbols: ${r.symbol_name}`);
+            // Matching symbols from this file (snippet equivalent)
+            const fileSyms = symbolsByFile.get(r.file_path) ?? [];
+            const inlineSyms = r.matching_symbols.filter(s => !fileSyms.some(f => f.name === s));
+            if (fileSyms.length) {
+                for (const s of fileSyms)
+                    lines.push(`  → \`${s.name}\` :${s.line}`);
+            }
+            if (inlineSyms.length) {
+                lines.push(`  symbols: ${inlineSyms.join(", ")}`);
+            }
             if (r.imports.length)
                 lines.push(`  imports: ${r.imports.join(", ")}`);
             if (r.used_by.length)
@@ -177,7 +202,22 @@ async function getSqliteFileList(specsInput, query, limit, backend = "auto") {
         if (results.length === 0)
             return null;
         const signal = store.querySignal(query);
-        return { files: results.map((r) => r.file_path), signal };
+        // Hybrid symbol search: BM25 + call-graph authority + optional vector similarity.
+        // embedQuery uses local model (no API key) or OpenAI if OPENAI_API_KEY is set.
+        let queryVec;
+        try {
+            const { embedQuery } = await import("../db/embeddings.js");
+            const vec = await embedQuery(cleaned || query, process.env.OPENAI_API_KEY);
+            if (vec)
+                queryVec = vec;
+        }
+        catch { /* graceful degradation — vector unavailable */ }
+        const symbols = store.searchSymbols(cleaned || query, Math.ceil(limit / 2), queryVec);
+        return {
+            files: results.map((r) => r.file_path),
+            symbols: symbols.map((s) => ({ file: s.file_path, name: s.name, line: s.line })),
+            signal,
+        };
     }
     finally {
         await store.close();

package/dist/config.js

@@ -273,6 +273,7 @@ function normalizeConfig(input, configDir) {
 }
 function mergeConfig(base, override) {
     return {
+        project_id: override.project_id ?? base.project_id,
         project: {
             root: override.project?.root ?? base.project?.root ?? "",
             backendRoot: override.project?.backendRoot ?? base.project?.backendRoot ?? "",

package/dist/db/embeddings.js

@@ -0,0 +1,113 @@
+/**
+ * Embedding generation for function-level semantic search.
+ *
+ * Strategy (local-first, no API key required):
+ *   Default  — @xenova/transformers running Xenova/all-MiniLM-L6-v2 on-device.
+ *              Model downloads once (~23 MB) and is cached in ~/.cache/xenova.
+ *              dim=384, pure JS/ONNX, no external service needed.
+ *
+ *   Upgrade  — OpenAI text-embedding-3-small when OPENAI_API_KEY is set.
+ *              dim=256, higher quality, costs ~$0.002 per 1M tokens.
+ *
+ * Text per function (concise — name carries most semantic signal):
+ *   "{name} {filename}: {top calls} {short literals}"
+ */
+const LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
+const LOCAL_DIM = 384;
+const OPENAI_MODEL = "text-embedding-3-small";
+const OPENAI_DIM = 256;
+const BATCH = 64; // safe for both local and OpenAI
+function fnToText(fn) {
+    const filename = fn.file.split("/").pop() ?? fn.file;
+    const callStr = (fn.calls ?? []).slice(0, 10).join(" ");
+    const litStr = (fn.stringLiterals ?? []).slice(0, 5).join(" ").slice(0, 100);
+    return `${fn.name} ${filename}: ${callStr} ${litStr}`.trim().slice(0, 300);
+}
+// ── Local embedder (no API key) ───────────────────────────────────────────────
+async function embedBatchLocal(texts, pipe) {
+    const out = [];
+    for (const text of texts) {
+        const result = await pipe(text, { pooling: "mean", normalize: true });
+        out.push(new Float32Array(result.data));
+    }
+    return out;
+}
+// ── OpenAI embedder (OPENAI_API_KEY required) ─────────────────────────────────
+async function embedBatchOpenAI(texts, apiKey) {
+    const { default: OpenAI } = await import("openai");
+    const client = new OpenAI({ apiKey });
+    const response = await client.embeddings.create({
+        model: OPENAI_MODEL,
+        input: texts,
+        dimensions: OPENAI_DIM,
+        encoding_format: "float",
+    });
+    return response.data.map(d => new Float32Array(d.embedding));
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Embed all functions and store them in guardian.db function_embeddings table.
+ * Uses local model by default; OpenAI when OPENAI_API_KEY is set (better quality).
+ */
+export async function embedFunctions(store, fns, apiKey) {
+    if (fns.length === 0)
+        return;
+    const useOpenAI = !!apiKey;
+    let pipe;
+    if (!useOpenAI) {
+        // Lazy-load local model (downloads once, then cached)
+        const { pipeline } = await import("@xenova/transformers");
+        console.log(`[guardian embed] loading local model ${LOCAL_MODEL}…`);
+        pipe = await pipeline("feature-extraction", LOCAL_MODEL);
+    }
+    const rows = [];
+    for (let i = 0; i < fns.length; i += BATCH) {
+        const batch = fns.slice(i, i + BATCH);
+        const texts = batch.map(fnToText);
+        let vecs;
+        try {
+            vecs = useOpenAI
+                ? await embedBatchOpenAI(texts, apiKey)
+                : await embedBatchLocal(texts, pipe);
+        }
+        catch (err) {
+            console.warn(`[guardian embed] batch ${i}–${i + batch.length - 1} failed: ${err.message}`);
+            continue;
+        }
+        for (let j = 0; j < batch.length; j++) {
+            if (!vecs[j])
+                continue;
+            rows.push({
+                file_path: batch[j].file,
+                name: batch[j].name,
+                line: batch[j].lines[0],
+                vec: vecs[j],
+            });
+        }
+        if (i > 0 && i % 500 === 0) {
+            console.log(`[guardian embed] ${i}/${fns.length} functions embedded`);
+        }
+    }
+    store.rebuildEmbeddings(rows);
+    const source = useOpenAI ? `OpenAI ${OPENAI_MODEL} dim=${OPENAI_DIM}` : `local ${LOCAL_MODEL} dim=${LOCAL_DIM}`;
+    console.log(`[guardian embed] stored ${rows.length} embeddings (${source})`);
+}
+/**
+ * Embed a single query string for hybrid search.
+ * Returns null on failure — graceful degradation to BM25 + call-graph authority.
+ */
+export async function embedQuery(query, apiKey) {
+    try {
+        if (apiKey) {
+            const [vec] = await embedBatchOpenAI([query.slice(0, 300)], apiKey);
+            return vec ?? null;
+        }
+        const { pipeline } = await import("@xenova/transformers");
+        const pipe = await pipeline("feature-extraction", LOCAL_MODEL);
+        const [vec] = await embedBatchLocal([query.slice(0, 300)], pipe);
+        return vec ?? null;
+    }
+    catch {
+        return null;
+    }
+}