opencode-rag-plugin 1.12.17 → 1.14.6

package/dist/plugin.js

@@ -1,5 +1,5 @@
 import { tool } from "@opencode-ai/plugin/tool";
-import { loadConfig, DEFAULT_CONFIG, resolveLogConfig } from "./core/config.js";
+import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig } from "./core/config.js";
 import { createEmbedder } from "./embedder/factory.js";
 import { createDescriptionProvider } from "./describer/factory.js";
 import { createVectorStore } from "./vectorstore/factory.js";
@@ -9,9 +9,11 @@ import { appendDebugLog } from "./core/fileLogger.js";
 import { loadRuntimeOverrides, applyRuntimeOverrides } from "./core/runtime-overrides.js";
 import { createBackgroundIndexer } from "./watcher.js";
 import { createRagReadTool } from "./opencode/create-read-tool.js";
-import { createFileSkeletonTool, createFindUsagesTool, } from "./opencode/tools.js";
+import { createFileSkeletonTool, createFindUsagesTool, createDescribeImageTool, } from "./opencode/tools.js";
 import { resolveApiKey } from "./core/resolve-api-key.js";
 import { consumePendingRagInjection } from "./core/rag-injection-flag.js";
+import { loadDocProgress, markSubdirectoryDocumented } from "./core/doc-progress.js";
+import { loadManifest } from "./core/manifest.js";
 import { createSessionLogger } from "./eval/session-logger.js";
 import { countTokens } from "./eval/token-counter.js";
 import { checkForUpdate } from "./updater.js";
@@ -20,12 +22,22 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, execSync } from "node:child_process";
 import { tmpdir } from "node:os";
+/** Cache of loaded RAG configurations keyed by workspace directory. */
 const configCache = new Map();
+/** Active background indexer instances keyed by workspace directory. */
 const backgroundIndexers = new Map();
+/** Active MCP server instances keyed by workspace directory. */
 const mcpServers = new Map();
+/** Pending update notifications keyed by workspace directory. */
 const pendingUpdateInfo = new Map();
+/** Name of the semantic search tool as exposed to the LLM. */
 const CONTEXT_TOOL_NAME = "search_semantic";
+/** Marker string injected into context output to identify RAG-sourced content. */
 const CONTEXT_MARKER = "search_semantic retrieved context";
+/**
+ * Append a verbose log entry with an optional structured payload.
+ * The payload is serialised using formatLogPayload for readability.
+ */
 function appendVerboseLog(logFilePath, scope, message, payload, logLevel) {
     appendDebugLog(logFilePath, {
         scope,
@@ -34,6 +46,10 @@ function appendVerboseLog(logFilePath, scope, message, payload, logLevel) {
             : message,
     }, logLevel);
 }
+/**
+ * Format an arbitrary value as a human-readable indented string
+ * for debug logging. Handles null, primitives, arrays, and nested objects.
+ */
 function formatLogPayload(value, indent = 0) {
     const prefix = "  ".repeat(indent);
     if (value === null) {
@@ -89,6 +105,10 @@ function formatLogPayload(value, indent = 0) {
     }
     return `${prefix}${String(value)}`;
 }
+/**
+ * Indent every line of a multi-line string by the given number of
+ * two-space indentation levels.
+ */
 function indentMultiline(text, indent) {
     const prefix = "  ".repeat(indent);
     return text
@@ -96,15 +116,17 @@ function indentMultiline(text, indent) {
         .map((line) => `${prefix}${line}`)
         .join("\n");
 }
+/**
+ * Load the RAG configuration for a directory, searching in order:
+ * opencode-rag.json, .opencode/opencode-rag.json, .opencode/rag.json.
+ * Caches the result per directory.
+ */
 async function getConfig(directory) {
     const cached = configCache.get(directory);
     if (cached)
         return cached;
-    for (const loc of ["opencode-rag.json", ".opencode/opencode-rag.json", ".opencode/rag.json"]) {
-        const configPath = path.join(directory, loc);
-        if (!existsSync(configPath)) {
-            continue;
-        }
+    const configPath = findConfigFile(directory);
+    if (configPath) {
         try {
             const cfg = loadConfig(configPath);
             await loadChunkersFromConfig(cfg, path.dirname(configPath));
@@ -122,6 +144,10 @@ async function getConfig(directory) {
     configCache.set(directory, DEFAULT_CONFIG);
     return DEFAULT_CONFIG;
 }
+/**
+ * Format retrieval results into a Markdown context block for LLM injection.
+ * Includes per-chunk file paths, line numbers, relevance scores, and descriptions.
+ */
 function formatContext(results) {
     if (results.length === 0)
         return "";
@@ -142,6 +168,10 @@ function formatContext(results) {
     parts.push("---\n");
     return parts.join("\n");
 }
+/**
+ * Format auto-injected context results, trimming to a token budget.
+ * Results are sorted by relevance and included up to maxChunks.
+ */
 function formatAutoInjectContext(results, worktree, maxTokens, maxChunks) {
     if (results.length === 0)
         return "";
@@ -177,6 +207,10 @@ function formatAutoInjectContext(results, worktree, maxTokens, maxChunks) {
     }
     return formatted;
 }
+/**
+ * Build the effective query string from a RetrievalQueryHints object,
+ * appending path and language hints as additional context.
+ */
 function buildRetrievalQuery(hints) {
     const parts = [hints.query.trim()];
     const pathHints = hints.pathHints?.map((hint) => hint.trim()).filter((hint) => hint.length > 0) ?? [];
@@ -189,6 +223,10 @@ function buildRetrievalQuery(hints) {
     }
     return parts.join("\n").trim();
 }
+/**
+ * Remove duplicate results based on file path + line range + content.
+ * Keeps the first occurrence of each unique result.
+ */
 function dedupeResults(results) {
     const seen = new Set();
     const deduped = [];
@@ -207,11 +245,19 @@ function dedupeResults(results) {
     }
     return deduped;
 }
+/**
+ * Perform a retrieval query against the vector store with the given parameters.
+ * Returns an empty array for blank queries.
+ */
 async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false) {
     if (query.trim().length === 0)
         return [];
     return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, queryPrefix, explain });
 }
+/**
+ * Load results from one or two queries (primary + optional extra), deduplicate,
+ * sort by descending score, and limit to maxContextChunks from config.
+ */
 async function loadRetrievedResults(query, embedder, store, cfg, retrieveFn = retrieve, topK = cfg.retrieval.topK, extraQuery, keywordIndex, queryPrefix, explain = false) {
     const minScore = cfg.retrieval.minScore;
     const kw = cfg.retrieval.hybridSearch?.keywordWeight;
@@ -223,11 +269,17 @@ async function loadRetrievedResults(query, embedder, store, cfg, retrieveFn = re
         .sort((a, b) => b.score - a.score)
         .slice(0, cfg.openCode.maxContextChunks);
 }
+/** Default set of plugin dependencies using the real implementations. */
 const defaultDependencies = {
     createEmbedder,
     createStore: (storePath, dimension, config) => createVectorStore(config, storePath, dimension),
     retrieve,
 };
+/**
+ * Format a list of relevant files (aggregated from chunks) for display.
+ * Groups chunks by file path and sorts by maximum relevance score.
+ * Includes an AGENTS.md-style tool usage reminder at the end.
+ */
 function formatFileList(results, worktree, maxFiles = 10) {
     const fileMap = new Map();
     for (const r of results) {
@@ -268,8 +320,12 @@ function formatFileList(results, worktree, maxFiles = 10) {
  *
  * Attempts to find the user's message content from output.message first
  * (via parts/text), then falls back to input fields.
+ *
+ * @param input - The incoming hook input containing session and message metadata.
+ * @param output - The output object potentially containing the user's message parts.
+ * @returns The extracted user message text, or an empty string if not found.
  */
-function extractUserMessageText(input, output) {
+function extractUserMessageText(_input, output) {
     // Try to extract from output.parts first (most common path)
     if (output?.message) {
         const msg = output.message;
@@ -291,6 +347,19 @@ function extractUserMessageText(input, output) {
     }
     return "";
 }
+/**
+ * Create the RAG plugin hook implementations for an OpenCode workspace.
+ *
+ * Wires together the vector store, embedder, keyword index, and description
+ * provider into OpenCode's hook system. Handles:
+ * - Automatic context injection on chat messages
+ * - Documentation mode auto-kickoff
+ * - Tool registration (semantic search, file skeleton, find usages, describe image)
+ * - Session-level caching and evaluation logging
+ *
+ * @param options - Configuration and dependencies for building the hooks.
+ * @returns A complete set of OpenCode hooks for RAG functionality.
+ */
 export function createRagHooks(options) {
     const dependencies = {
         ...defaultDependencies,
@@ -313,11 +382,6 @@ export function createRagHooks(options) {
     // Session-level caches for lazy retrieval
     const sessionLastMessage = new Map();
     const sessionRetrievalCache = new Map();
-    // Session-level tool usage tracking for nudge mechanism
-    const RAG_TOOL_NAMES = new Set(["search_semantic", "get_file_skeleton", "find_usages"]);
-    const sessionRagToolCalls = new Map();
-    const sessionMessageCount = new Map();
-    const sessionSkeletonCalls = new Map(); // sessionID → set of filePaths
     // Evaluation session logger — captures OpenCode events for analysis
     const sessionLogger = createSessionLogger(options.storePath);
     appendDebugLog(options.logFilePath, {
@@ -464,6 +528,20 @@ export function createRagHooks(options) {
             error: err,
         });
     }
+    try {
+        const describeImageTool = createDescribeImageTool({
+            worktree: options.worktree,
+            config: effectiveCfg,
+        });
+        tools["describe_image"] = describeImageTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register describe_image tool",
+            error: err,
+        });
+    }
     if (readOverride) {
         const readTool = createRagReadTool({
             worktree: options.worktree,
@@ -491,24 +569,6 @@ export function createRagHooks(options) {
             sessionLogger.onEvent(event);
         },
         tool: tools,
-        async "tool.execute.after"(input, output) {
-            // Track RAG tool usage per session
-            if (RAG_TOOL_NAMES.has(input.tool)) {
-                const prev = sessionRagToolCalls.get(input.sessionID) ?? 0;
-                sessionRagToolCalls.set(input.sessionID, prev + 1);
-            }
-        },
-        async "tool.execute.before"(input, output) {
-            // Track skeleton calls per session for read-interception analytics
-            if (input.tool === "get_file_skeleton") {
-                const filePath = output.args?.filePath;
-                if (filePath) {
-                    const set = sessionSkeletonCalls.get(input.sessionID) ?? new Set();
-                    set.add(filePath);
-                    sessionSkeletonCalls.set(input.sessionID, set);
-                }
-            }
-        },
         async "experimental.chat.system.transform"(_input, output) {
             appendDebugLog(options.logFilePath, {
                 scope: "experimental.chat.system.transform",
@@ -519,18 +579,21 @@ export function createRagHooks(options) {
                 "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
                 "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
                 "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
+                "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
                 "",
                 "Decision tree — ALWAYS follow this order:",
                 "1. User mentions code behavior/architecture → `search_semantic(query)`",
                 "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
                 "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
                 "4. User asks a code question → `search_semantic` to gather context before answering",
+                "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
                 "",
                 "Proactive triggers — you MUST call these tools when:",
                 "- User asks about code behavior, architecture, or implementation details",
                 "- User asks to edit, refactor, or fix code — call `find_usages` first",
                 "- User references files or functions you haven't read yet",
                 "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
+                "- User refers to an image, screenshot, diagram, or visual asset",
                 "- Before answering ANY code-related question, retrieve context first",
                 "- Before reading ANY file, call `get_file_skeleton` to orient first",
                 "",
@@ -539,6 +602,7 @@ export function createRagHooks(options) {
                 "- Editing a function without calling `find_usages` first (breaks call sites)",
                 "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
                 "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
+                "- Treating image files as text — use `describe_image` instead of reading raw bytes",
             ];
             output.system.unshift(guidance.join("\n"));
             // Inject update notification if available
@@ -547,6 +611,11 @@ export function createRagHooks(options) {
                 output.system.unshift(`OpenCodeRAG update available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}. ` +
                     `Run \`opencode-rag update\` to install.`);
             }
+            // Inject documentation mode system prompt if enabled
+            const docMode = getEffectiveCfg().documentationMode;
+            if (docMode?.enabled && docMode.systemPrompt) {
+                output.system.unshift(docMode.systemPrompt);
+            }
         },
         async "chat.message"(input, output) {
             try {
@@ -554,9 +623,90 @@ export function createRagHooks(options) {
                 if (text.length === 0)
                     return;
                 sessionLastMessage.set(input.sessionID, text);
-                // Track message count for nudge mechanism
-                const prevMsgCount = sessionMessageCount.get(input.sessionID) ?? 0;
-                sessionMessageCount.set(input.sessionID, prevMsgCount + 1);
+                // Handle /doc slash command
+                if (text.startsWith("/doc")) {
+                    const docMode = getEffectiveCfg().documentationMode;
+                    if (!docMode?.enabled) {
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: "Documentation mode is not enabled. Set `documentationMode.enabled` to `true` in opencode-rag.json." };
+                            }
+                        }
+                        return;
+                    }
+                    const arg = text.slice(4).trim();
+                    try {
+                        const manifest = await loadManifest(options.storePath);
+                        const allFiles = Object.keys(manifest.manifest.files);
+                        if (allFiles.length === 0) {
+                            const parts = output?.parts ?? output?.message?.parts;
+                            if (Array.isArray(parts) && parts.length > 0) {
+                                const first = parts[0];
+                                if (typeof first.text === "string") {
+                                    parts[0] = { ...first, text: "No indexed files found. Run indexing first, then use `/doc`." };
+                                }
+                            }
+                            return;
+                        }
+                        if (arg) {
+                            markSubdirectoryDocumented(options.storePath, arg, allFiles);
+                        }
+                        const progress = loadDocProgress(options.storePath);
+                        const remaining = allFiles.filter((f) => !progress.documented.includes(f));
+                        let docMsg;
+                        if (remaining.length === 0) {
+                            docMsg = `**All ${allFiles.length} indexed files have been documented.** No remaining files.`;
+                        }
+                        else {
+                            const grouped = {};
+                            for (const f of remaining) {
+                                const dir = path.dirname(f);
+                                (grouped[dir] ??= []).push(f);
+                            }
+                            const lines = [
+                                "## Documentation",
+                                "",
+                                "Pick a subdirectory and document ALL files within it using Google JSDoc style.",
+                                `When done, type \`/doc <subdirectory>\` to mark it complete and see what's left.`,
+                                "",
+                            ];
+                            for (const [dir, files] of Object.entries(grouped).sort(([a], [b]) => a.localeCompare(b))) {
+                                lines.push(`### ${dir} (${files.length} file${files.length === 1 ? "" : "s"})`);
+                                for (const f of files) {
+                                    lines.push(`- \`${f}\``);
+                                }
+                                lines.push("");
+                            }
+                            lines.push(`Progress: ${progress.documented.length} / ${allFiles.length} files documented.`);
+                            lines.push(`Remaining: ${remaining.length} files.`);
+                            docMsg = lines.join("\n");
+                        }
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: docMsg };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        appendDebugLog(options.logFilePath, {
+                            scope: "chat.message",
+                            message: "Failed to handle /doc command",
+                            error: err,
+                        });
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: "Failed to start documentation. Ensure the workspace is indexed." };
+                            }
+                        }
+                    }
+                    return;
+                }
                 const pendingInjection = consumePendingRagInjection(options.storePath);
                 const count = await store.count();
                 if (count === 0)
@@ -583,9 +733,32 @@ export function createRagHooks(options) {
                     return;
                 }
                 if (pendingInjection === "chunks") {
-                    const maxChunks = effectiveCfg.openCode.autoInject?.maxChunks ?? 5;
-                    const topChunks = results.slice(0, maxChunks);
-                    const chunkContext = formatAutoInjectContext(topChunks, options.worktree, effectiveCfg.openCode.autoInject?.maxTokens ?? 3000, maxChunks);
+                    const autoInjectCfg = effectiveCfg.openCode.autoInject;
+                    if (autoInjectCfg?.enabled === false) {
+                        sessionLogger.onRagContext(input.sessionID, input.messageID, {
+                            chunkCount: 0,
+                            uniqueFiles: 0,
+                            contextTokens: 0,
+                            topScore: 0,
+                            retrievalTimeMs,
+                        });
+                        return;
+                    }
+                    const minScore = autoInjectCfg?.minScore ?? 0.85;
+                    const maxChunks = autoInjectCfg?.maxChunks ?? 5;
+                    const filtered = results.filter((r) => r.score >= minScore);
+                    if (filtered.length === 0) {
+                        sessionLogger.onRagContext(input.sessionID, input.messageID, {
+                            chunkCount: 0,
+                            uniqueFiles: 0,
+                            contextTokens: 0,
+                            topScore: 0,
+                            retrievalTimeMs,
+                        });
+                        return;
+                    }
+                    const topChunks = filtered.slice(0, maxChunks);
+                    const chunkContext = formatAutoInjectContext(topChunks, options.worktree, autoInjectCfg?.maxTokens ?? 3000, maxChunks);
                     sessionLogger.onRagContext(input.sessionID, input.messageID, {
                         chunkCount: topChunks.length,
                         uniqueFiles: new Set(topChunks.map((r) => r.chunk.metadata.filePath)).size,
@@ -605,12 +778,35 @@ export function createRagHooks(options) {
                     return;
                 }
                 if (pendingInjection === "files") {
-                    const fileList = formatFileList(results, options.worktree, effectiveCfg.retrieval.topK);
+                    const autoInjectCfg = effectiveCfg.openCode.autoInject;
+                    if (autoInjectCfg?.enabled === false) {
+                        sessionLogger.onRagContext(input.sessionID, input.messageID, {
+                            chunkCount: 0,
+                            uniqueFiles: 0,
+                            contextTokens: 0,
+                            topScore: 0,
+                            retrievalTimeMs,
+                        });
+                        return;
+                    }
+                    const minScore = autoInjectCfg?.minScore ?? 0.85;
+                    const filtered = results.filter((r) => r.score >= minScore);
+                    if (filtered.length === 0) {
+                        sessionLogger.onRagContext(input.sessionID, input.messageID, {
+                            chunkCount: 0,
+                            uniqueFiles: 0,
+                            contextTokens: 0,
+                            topScore: 0,
+                            retrievalTimeMs,
+                        });
+                        return;
+                    }
+                    const fileList = formatFileList(filtered, options.worktree, effectiveCfg.retrieval.topK);
                     sessionLogger.onRagContext(input.sessionID, input.messageID, {
                         chunkCount: 0,
                         uniqueFiles: 0,
                         contextTokens: fileList ? countTokens(fileList) : 0,
-                        topScore: results[0]?.score ?? 0,
+                        topScore: filtered[0]?.score ?? 0,
                         retrievalTimeMs,
                     });
                     if (!fileList)
@@ -675,6 +871,10 @@ export function createRagHooks(options) {
         },
     };
 }
+/**
+ * Load the persistent keyword index from disk, falling back to an empty
+ * index if loading fails.
+ */
 async function loadKeywordIndex(storePath, logFilePath, logLevel) {
     const { KeywordIndex } = await import("./retriever/keyword-index.js");
     try {
@@ -695,6 +895,10 @@ async function loadKeywordIndex(storePath, logFilePath, logLevel) {
     }
 }
 let _cachedNodeExecutable;
+/**
+ * Resolve the path to the Node.js executable, caching the result.
+ * Checks `process.execPath` first, then falls back to `where`/`which`.
+ */
 function resolveNodeExecutable() {
     if (_cachedNodeExecutable !== undefined)
         return _cachedNodeExecutable;
@@ -719,6 +923,10 @@ function resolveNodeExecutable() {
     _cachedNodeExecutable = found;
     return _cachedNodeExecutable;
 }
+/**
+ * Resolve the MCP CLI entry point script path.
+ * Checks `dist/cli.js` first, then falls back to `src/cli.ts`.
+ */
 function resolveMcpCliEntry() {
     const selfDir = path.dirname(fileURLToPath(import.meta.url));
     const packageRoot = path.resolve(selfDir, "..");
@@ -730,6 +938,11 @@ function resolveMcpCliEntry() {
         return srcCli;
     return null;
 }
+/**
+ * Start an MCP server process for the given workspace directory.
+ * Spawns the CLI in MCP mode as a child process and wires stdout/stderr
+ * to the debug log. Returns a handle for graceful shutdown.
+ */
 function startMcpServerProcess(cwd, logFilePath, logLevel) {
     const cliEntry = resolveMcpCliEntry();
     if (!cliEntry) {
@@ -797,6 +1010,18 @@ function startMcpServerProcess(cwd, logFilePath, logLevel) {
         },
     };
 }
+/**
+ * OpenCodeRAG plugin factory — invoked by OpenCode's plugin system for each workspace.
+ *
+ * Bootstraps the full RAG pipeline: loads config, probes vector dimensions,
+ * creates embedder/store, starts the background auto-indexer (if enabled),
+ * launches the MCP server (if enabled), checks for updates, and returns
+ * the RAG hooks that power tools and automatic context injection.
+ *
+ * @param input - Plugin input containing the workspace directory and runtime context.
+ * @param _options - Optional additional plugin options (unused).
+ * @returns A complete set of OpenCode hooks for RAG functionality.
+ */
 export const ragPlugin = async (input, _options) => {
     const cfg = await getConfig(input.directory);
     const logFilePath = path.resolve(input.directory, resolveLogConfig(cfg).logFilePath);
@@ -898,7 +1123,7 @@ export const ragPlugin = async (input, _options) => {
         descriptionProvider,
     });
     // Start background auto-indexer if enabled
-    const autoIndexCfg = effectiveCfg.openCode.autoIndex ?? { enabled: true, debounceMs: 5000, intervalMs: 300000 };
+    const autoIndexCfg = effectiveCfg.openCode.autoIndex ?? { enabled: false, debounceMs: 5000, intervalMs: 300000 };
     if (autoIndexCfg.enabled) {
         const indexer = createBackgroundIndexer({
             cwd: input.directory,