opencode-rag-plugin 1.22.0 → 1.22.2

package/dist/cli/commands/index-command.js

@@ -98,6 +98,7 @@ export function registerIndexCommand(program) {
                 }
             }
             logCliInfo(logFilePath, "index", `${c.label("Scanning:")} ${c.file(cwd)}`);
+            let incomplete = false;
             const runPass = async (watchTriggered = false, abortSignal, filterPaths) => {
                 const passStarted = Date.now();
                 const stats = await runIndexPass({
@@ -116,6 +117,14 @@ export function registerIndexCommand(program) {
                 });
                 if (!watchTriggered) {
                     logIndexSummary(logFilePath, stats);
+                    if (stats.embeddingUnavailable) {
+                        incomplete = true;
+                        logCliInfo(logFilePath, "index", `\n${c.error("Indexing incomplete:")} the embedding provider was unavailable — nothing was stored. Fix the provider and run the index again.`);
+                    }
+                    else if (stats.totalChunks === 0 && stats.newFiles + stats.modifiedFiles > 0) {
+                        incomplete = true;
+                        logCliInfo(logFilePath, "index", `\n${c.warn("Indexing incomplete:")} files were processed but no chunks were stored. Check the log for details.`);
+                    }
                     logCliInfo(logFilePath, "index", `\n${c.success("Indexing complete.")} ${c.num(stats.finalCount)} chunks stored (${formatDuration(Date.now() - passStarted)}).`);
                 }
                 if (sigReceived && !watchTriggered) {
@@ -128,7 +137,7 @@ export function registerIndexCommand(program) {
             process.removeListener("SIGTERM", handleSigint);
             if (!options.watch) {
                 await cleanupContext(ctx);
-                process.exit(sigReceived ? 130 : 0);
+                process.exit(sigReceived ? 130 : incomplete ? 1 : 0);
             }
             // Only one watcher may run per workspace — a background auto-indexer
             // in an OpenCode session (or another `index --watch`) may already own

package/dist/cli/commands/status.js

@@ -75,6 +75,20 @@ export function registerStatusCommand(program) {
             logCliInfo(logFilePath, "status", `${c.label("Store path:")}        ${c.file(storePath)}`);
             logCliInfo(logFilePath, "status", `${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
             logCliInfo(logFilePath, "status", `${c.label("Embedding model:")}   ${c.value(config.embedding.model)}`);
+            const storeDimension = await store.getVectorDimension?.();
+            const embedderDimension = config.embedding.vectorDimension;
+            if (embedderDimension && embedderDimension > 0) {
+                logCliInfo(logFilePath, "status", `${c.label("Embedder dim:")}      ${c.num(embedderDimension)}`);
+            }
+            if (storeDimension !== undefined) {
+                logCliInfo(logFilePath, "status", `${c.label("Store dimension:")}   ${c.num(storeDimension)}`);
+            }
+            if (storeDimension !== undefined &&
+                embedderDimension !== undefined &&
+                embedderDimension > 0 &&
+                storeDimension !== embedderDimension) {
+                logCliInfo(logFilePath, "status", `${c.label("Dimension mismatch:")} ${c.warn("yes")} — the store was built with a different embedding model. Run 'opencode-rag index' to rebuild.`);
+            }
             logCliInfo(logFilePath, "status", `${c.label("File extensions:")}   ${config.indexing.includeExtensions.join(", ")}`);
             logCliInfo(logFilePath, "status", `${c.label("Excluded dirs:")}     ${config.indexing.excludeDirs.join(", ")}`);
             logCliInfo(logFilePath, "status", `${c.label("Default top-K:")}     ${c.num(config.retrieval.topK)}`);

package/dist/cli/format.js

@@ -92,7 +92,7 @@ export async function resolveCliContext(opt, logFilePath, bootstrapOpts) {
         configPath: opt.config,
         ...bootstrapOpts,
     });
-    logCliInfo(logFilePath, "config", `${c.label("Config:")} ${c.file(ctx.logFilePath)}`);
+    logCliInfo(logFilePath, "config", `${c.label("Config:")} ${c.file(ctx.configPath ?? "(built-in defaults)")}`);
     logConfigDetails(logFilePath, ctx.config);
     return ctx;
 }
@@ -105,6 +105,9 @@ export async function resolveCliContext(opt, logFilePath, bootstrapOpts) {
 function logConfigDetails(logFilePath, config) {
     logCliInfo(logFilePath, "config", `  ${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
     logCliInfo(logFilePath, "config", `  ${c.label("Embedding model:")}    ${c.value(config.embedding.model)}`);
+    if (config.embedding.vectorDimension && config.embedding.vectorDimension > 0) {
+        logCliInfo(logFilePath, "config", `  ${c.label("Embedding dim:")}      ${c.num(config.embedding.vectorDimension)}`);
+    }
     logCliInfo(logFilePath, "config", `  ${c.label("Vector store:")}       ${c.file(config.vectorStore.path)}`);
 }
 /**
@@ -153,7 +156,13 @@ export function logIndexSummary(logFilePath, stats) {
     if (stats.descriptionFailedFiles > 0) {
         logCliInfo(logFilePath, "index", `  ${c.label("Desc failed:")}     ${c.num(stats.descriptionFailedFiles)}`);
     }
+    if (stats.embeddingFailures > 0) {
+        logCliInfo(logFilePath, "index", `  ${c.label("Embed failed:")}    ${c.num(stats.embeddingFailures)} chunk(s) without vectors — retried next pass`);
+    }
     logCliInfo(logFilePath, "index", `  ${c.label("Chunks written:")}   ${c.num(stats.totalChunks)}`);
+    if (stats.embeddingUnavailable) {
+        logCliInfo(logFilePath, "index", `  ${c.error("Embedding provider unavailable during this pass — no chunks were stored.")}`);
+    }
 }
 /**
  * Format a millisecond duration into a compact human-readable string.

package/dist/core/bootstrap.d.ts

@@ -35,6 +35,8 @@ export interface RagContext {
     dimension: number;
     /** Resolved path to the debug log file. */
     logFilePath: string;
+    /** Resolved path to the config file, or undefined when built-in defaults are used. */
+    configPath?: string;
 }
 /** Bootstrap the full RAG pipeline context: load config, resolve API keys, create embedder, vector store, keyword index, and description provider. */
 export declare function resolveRagContext(opts?: BootstrapOptions): Promise<RagContext>;

package/dist/core/bootstrap.js

@@ -6,26 +6,46 @@ import path from "node:path";
 import { loadConfig, findConfigFile, resolveLogConfig, DEFAULT_CONFIG } from "./config.js";
 import { resolveApiKey } from "./resolve-api-key.js";
 import { loadChunkersFromConfig } from "../chunker/loader.js";
-import { createEmbedder } from "../embedder/factory.js";
+import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
 import { createDescriptionProvider } from "../describer/factory.js";
 import { createVectorStore } from "../vectorstore/factory.js";
+import { readStoreDimension } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
-/** Probe the embedding provider to determine the vector dimension. Falls back to 384 on failure. */
-async function probeDimension(embedder) {
-    try {
-        const probe = await embedder.embed(["dimension-probe"], "query");
-        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
-            return probe[0].length;
-        }
+/**
+ * Resolve the embedding dimension for the store.
+ *
+ * Precedence: an explicit `embedding.vectorDimension` in the config wins (it
+ * is persisted after the first successful probe), then a live probe of the
+ * provider, then the dimension of an existing store table, then the 384
+ * fallback. The old behavior always probed and fell back to 384 — which
+ * silently created 384-dimensional stores whenever the provider was down,
+ * even though the config declared the real dimension.
+ *
+ * @param embedder - Configured embedding provider (probed only when needed).
+ * @param storePath - Vector store path, used to read an existing schema.
+ * @param skipProbe - When true, never call the provider (read-only commands).
+ * @returns The resolved dimension.
+ */
+async function resolveDimension(embedder, storePath, skipProbe, configured) {
+    if (configured && configured > 0) {
+        return configured;
     }
-    catch {
-        // fallback to 384
+    if (!skipProbe) {
+        const probe = await probeEmbeddingDimension(embedder);
+        if (probe.dimension !== undefined) {
+            return probe.dimension;
+        }
+        const storeDimension = await readStoreDimension(storePath);
+        if (storeDimension !== undefined) {
+            console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
+                `using the existing store's dimension ${storeDimension}.`);
+            return storeDimension;
+        }
+        console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
+            "falling back to 384. Set embedding.vectorDimension explicitly if the provider produces a different size.");
+        return 384;
     }
-    // A wrong dimension is only discovered later as cryptic LanceDB errors —
-    // surface the fallback loudly so misconfigured providers are easy to spot.
-    console.warn("[bootstrap] Could not probe embedding dimension — falling back to 384. " +
-        "If indexing later fails with dimension errors, set embedding.vectorDimension explicitly.");
-    return 384;
+    return (await readStoreDimension(storePath)) ?? 384;
 }
 /** Load the keyword index from disk, or create a new empty one if loading fails. */
 async function loadKeywordIndex(storePath) {
@@ -61,8 +81,16 @@ export async function resolveRagContext(opts = {}) {
     }
     const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
     const embedder = createEmbedder(cfg);
-    const dimension = opts.skipProbe ? 384 : await probeDimension(embedder);
     const storePath = path.resolve(workDir, cfg.vectorStore.path);
+    const dimension = await resolveDimension(embedder, storePath, opts.skipProbe ?? false, cfg.embedding.vectorDimension);
+    // Warn (but do not block) when the existing store schema disagrees with the
+    // resolved dimension: the next index pass rebuilds automatically, and search
+    // callers would otherwise see only cryptic LanceDB errors.
+    const storeDimension = await readStoreDimension(storePath);
+    if (storeDimension !== undefined && storeDimension !== dimension) {
+        console.warn(`[bootstrap] Store was built with vector dimension ${storeDimension} but the current embedder produces ${dimension} — ` +
+            "run 'opencode-rag index' to rebuild the index with the current model.");
+    }
     const store = createVectorStore(cfg, storePath, dimension);
     const keywordIndex = opts.skipKeywordIndex
         ? new KeywordIndex(storePath)
@@ -80,6 +108,7 @@ export async function resolveRagContext(opts = {}) {
         descriptionProvider,
         dimension,
         logFilePath,
+        configPath,
     };
 }
 //# sourceMappingURL=bootstrap.js.map

package/dist/core/config.d.ts

@@ -183,6 +183,8 @@ export interface TuiConfig {
     fileListKeybinding: string;
     /** Keybinding to toggle the chunk viewer panel. */
     chunksKeybinding: string;
+    /** Keybinding to open the RAG settings dialog. Must be distinguishable by the terminal (see docs). */
+    settingsKeybinding: string;
 }
 /** Configuration for the standalone MCP (Model Context Protocol) server. */
 export interface McpConfig {
@@ -294,6 +296,18 @@ export interface RagConfig {
         ollamaMaxBatchSize?: number;
         /** Maximum concurrent description generation requests. */
         descriptionConcurrency?: number;
+        /**
+         * Include LLM-generated chunk descriptions in the text that gets embedded.
+         *
+         * Descriptions help general-purpose embedding models align natural-language
+         * queries with raw code. Code-specialized models (e.g. jina-code-embeddings,
+         * trained for NL→code retrieval with instruction prefixes) do not need the
+         * crutch — and their passage prompt expects a code snippet, not prose.
+         * When false, descriptions are still generated and stored (search results,
+         * web UI), but only path/meta header/content are embedded.
+         * @default true
+         */
+        embedDescriptions?: boolean;
         /**
          * Maximum file size in bytes for SVG/XML files before chunking is skipped.
          * Large SVGs can cause tree-sitter to hang. Set to 0 for no limit.

package/dist/core/config.js

@@ -117,6 +117,7 @@ export const DEFAULT_CONFIG = {
         embedConcurrency: 3,
         ollamaMaxBatchSize: 100,
         descriptionConcurrency: 4,
+        embedDescriptions: true,
         maxSvgSizeBytes: 1_048_576,
         optimizeIntervalWindows: 8,
     },
@@ -294,6 +295,7 @@ export const DEFAULT_CONFIG = {
     tui: {
         fileListKeybinding: "ctrl+enter",
         chunksKeybinding: "ctrl+alt+enter",
+        settingsKeybinding: "ctrl+shift+r",
     },
     logging: {
         level: "info",

package/dist/core/interfaces.d.ts

@@ -224,6 +224,14 @@ export interface VectorStore {
      * Used by the index pipeline to detect silent corruption before scanning.
      */
     checkIntegrity?(): Promise<boolean>;
+    /**
+     * Return the actual embedding dimension of the stored vector column, or
+     * `undefined` when the store has no table yet. Used to detect a store that
+     * was built with a different embedding model than the currently configured
+     * one — a mismatch makes every vector search fail and silently corrupts
+     * writes, so the pipeline rebuilds the index instead.
+     */
+    getVectorDimension?(): Promise<number | undefined>;
 }
 /** Filter criteria for narrowing search results by file path, language, kind, or extension. */
 export interface MetadataFilter {

package/dist/core/runtime-overrides.d.ts

@@ -49,6 +49,7 @@ export interface RuntimeOverrides {
     tui?: {
         fileListKeybinding?: string;
         chunksKeybinding?: string;
+        settingsKeybinding?: string;
     };
 }
 /** Load runtime overrides from the store directory. Returns empty object if none exist. */

package/dist/core/runtime-overrides.js

@@ -149,6 +149,7 @@ export function applyRuntimeOverrides(cfg, overrides) {
             ...(merged.tui ?? {}),
             fileListKeybinding: overrides.tui.fileListKeybinding ?? merged.tui?.fileListKeybinding ?? DEFAULT_CONFIG.tui.fileListKeybinding,
             chunksKeybinding: overrides.tui.chunksKeybinding ?? merged.tui?.chunksKeybinding ?? DEFAULT_CONFIG.tui.chunksKeybinding,
+            settingsKeybinding: overrides.tui.settingsKeybinding ?? merged.tui?.settingsKeybinding ?? DEFAULT_CONFIG.tui.settingsKeybinding,
         };
     }
     return merged;

package/dist/embedder/factory.d.ts

@@ -15,6 +15,26 @@ import type { RagConfig } from "../core/config.js";
  * @throws If the provider is unsupported or a required apiKey is not set
  */
 export declare function createEmbedder(config: RagConfig): EmbeddingProvider;
+/** Result of probing an embedding provider for its output dimension. */
+export interface EmbeddingProbeResult {
+    /** Detected vector dimension, or `undefined` when the probe failed. */
+    dimension?: number;
+    /** Error raised by the provider (or an empty response), when the probe failed. */
+    error?: Error;
+}
+/**
+ * Probe an embedding provider with a single short text to discover the
+ * dimension of the vectors it produces.
+ *
+ * Used as a health/dimension preflight before expensive index work: a provider
+ * that is down (server not running, model not pulled) fails here in
+ * milliseconds instead of after chunking and describing every file. Errors are
+ * captured in the result rather than thrown.
+ *
+ * @param embedder - The embedding provider to probe.
+ * @returns The detected dimension, or the failure reason.
+ */
+export declare function probeEmbeddingDimension(embedder: EmbeddingProvider): Promise<EmbeddingProbeResult>;
 /**
  * Embed a list of texts in batches with optional concurrency control and per-batch retry.
  *

package/dist/embedder/factory.js

@@ -40,6 +40,30 @@ export function createEmbedder(config) {
     }
     throw new Error(`Unknown embedding provider: ${provider}`);
 }
+/**
+ * Probe an embedding provider with a single short text to discover the
+ * dimension of the vectors it produces.
+ *
+ * Used as a health/dimension preflight before expensive index work: a provider
+ * that is down (server not running, model not pulled) fails here in
+ * milliseconds instead of after chunking and describing every file. Errors are
+ * captured in the result rather than thrown.
+ *
+ * @param embedder - The embedding provider to probe.
+ * @returns The detected dimension, or the failure reason.
+ */
+export async function probeEmbeddingDimension(embedder) {
+    try {
+        const probe = await embedder.embed(["dimension-probe"], "query");
+        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
+            return { dimension: probe[0].length };
+        }
+        return { error: new Error("Embedding provider returned an empty probe vector") };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}
 /**
  * HTTP statuses that indicate a permanent failure — retrying cannot help
  * (auth errors, bad requests, missing resources). Providers raise these as