opencode-rag-plugin 1.19.4 → 1.19.5

package/dist/chunker/base.js

@@ -2,7 +2,7 @@
  * @fileoverview Abstract base class for tree-sitter based language chunkers.
  */
 import { Parser } from "web-tree-sitter";
-import { loadLanguage, loadLanguageFromPath, walkTree } from "./grammar.js";
+import { loadLanguage, loadLanguageFromPath, walkTree, buildByteOffsetMap } from "./grammar.js";
 import { uuid } from "./uuid.js";
 /** Module-level parser pool shared across all TreeSitterChunker instances. */
 const parserPool = new Map();
@@ -45,8 +45,15 @@ export class TreeSitterChunker {
                 if (!tree) {
                     return [];
                 }
-                const nodes = walkTree(tree.rootNode, types, content);
-                tree.delete();
+                // tree-sitter ranges are UTF-8 byte offsets; translate for slicing
+                const offsetMap = buildByteOffsetMap(content);
+                let nodes;
+                try {
+                    nodes = walkTree(tree.rootNode, types, content, 10, 0, offsetMap);
+                }
+                finally {
+                    tree.delete();
+                }
                 return nodes.map((node) => ({
                     id: uuid(),
                     content: node.text,
@@ -108,8 +115,15 @@ export class TreeSitterChunker {
         if (!tree) {
             return [];
         }
-        const nodes = walkTree(tree.rootNode, this.nodeTypes, content);
-        tree.delete();
+        // tree-sitter ranges are UTF-8 byte offsets; translate for slicing
+        const offsetMap = buildByteOffsetMap(content);
+        let nodes;
+        try {
+            nodes = walkTree(tree.rootNode, this.nodeTypes, content, 10, 0, offsetMap);
+        }
+        finally {
+            tree.delete();
+        }
         return nodes.map((node) => ({
             id: uuid(),
             content: node.text,

package/dist/chunker/factory.js

@@ -174,14 +174,26 @@ function splitOversized(chunks, filePath) {
     }
     return result;
 }
-/** Apply config overrides to a chunker before it's used. */
-function applyChunkerConfig(chunker, _filePath, options) {
-    if (options?.maxSvgSizeBytes && chunker instanceof TreeSitterChunker) {
-        const ext = _filePath.toLowerCase();
-        if (ext.endsWith(".svg") || ext.endsWith(".xml") || ext.endsWith(".csproj")) {
-            chunker.maxContentBytes = options.maxSvgSizeBytes;
-        }
-    }
+/**
+ * Wrap a chunker with a per-file byte limit.
+ *
+ * Previously the limit was assigned onto the shared chunker singleton
+ * (`chunker.maxContentBytes = ...`) — under pLimit concurrency one file's
+ * limit could bleed into unrelated concurrent files, and it was never
+ * reset, so a later large XML/SVG file was silently skipped.
+ */
+function withByteLimit(chunker, limit) {
+    const language = chunker.language;
+    return {
+        language,
+        fileExtensions: chunker.fileExtensions,
+        async chunk(filePath, content) {
+            if (limit > 0 && Buffer.byteLength(content, "utf-8") > limit) {
+                throw new Error(`File exceeds ${limit} byte limit for ${language} chunker`);
+            }
+            return chunker.chunk(filePath, content);
+        },
+    };
 }
 /**
  * Chunk a file by looking up its registered chunker, applying node-type
@@ -203,7 +215,13 @@ export async function chunkFile(filePath, content, nodeTypesOverrides, options)
             chunker = chunker.withNodeTypes(new Set(overrideTypes));
         }
     }
-    applyChunkerConfig(chunker, filePath, options);
+    // Per-file byte limit (SVG/XML/csproj) without mutating the shared singleton
+    if (options?.maxSvgSizeBytes && chunker instanceof TreeSitterChunker) {
+        const ext = filePath.toLowerCase();
+        if (ext.endsWith(".svg") || ext.endsWith(".xml") || ext.endsWith(".csproj")) {
+            chunker = withByteLimit(chunker, options.maxSvgSizeBytes);
+        }
+    }
     const chunks = await chunker.chunk(filePath, content);
     if (chunks.length === 0) {
         return fallbackChunker.chunk(filePath, content);

package/dist/chunker/grammar.d.ts

@@ -57,6 +57,23 @@ export interface AstNode {
      */
     leadingDoc?: string;
 }
+/**
+ * Build a byte-offset → UTF-16-index map for a source string.
+ *
+ * tree-sitter reports node ranges as UTF-8 BYTE offsets, but JavaScript
+ * `String.prototype.slice` counts UTF-16 code units. For any file containing
+ * multi-byte characters the two disagree, so slicing with raw node indices
+ * truncates/garbles chunk content and doc comments. Tree-sitter node
+ * boundaries always align to code-point boundaries, so an exact map from
+ * byte offset to UTF-16 index is sufficient.
+ *
+ * Returns `null` for pure-ASCII sources (byte offsets == UTF-16 offsets),
+ * which is the common case and avoids the allocation.
+ *
+ * @param source - The full source text.
+ * @returns A Map from UTF-8 byte offset to UTF-16 index, or `null` for ASCII.
+ */
+export declare function buildByteOffsetMap(source: string): Map<number, number> | null;
 /**
  * Recursively walk a tree-sitter AST and collect nodes matching the given
  * type set.
@@ -75,4 +92,4 @@ export interface AstNode {
  * @param depth - Current recursion depth (internal, start at 0).
  * @returns An array of {@link AstNode} objects for matching declarations.
  */
-export declare function walkTree(node: Node, nodeTypes: Set<string>, source: string, maxDepth?: number, depth?: number): AstNode[];
+export declare function walkTree(node: Node, nodeTypes: Set<string>, source: string, maxDepth?: number, depth?: number, offsetMap?: Map<number, number> | null): AstNode[];

package/dist/chunker/grammar.js

@@ -120,6 +120,44 @@ const COMMENT_NODE_TYPES = new Set([
     "marginalia",
     "Comment",
 ]);
+/**
+ * Build a byte-offset → UTF-16-index map for a source string.
+ *
+ * tree-sitter reports node ranges as UTF-8 BYTE offsets, but JavaScript
+ * `String.prototype.slice` counts UTF-16 code units. For any file containing
+ * multi-byte characters the two disagree, so slicing with raw node indices
+ * truncates/garbles chunk content and doc comments. Tree-sitter node
+ * boundaries always align to code-point boundaries, so an exact map from
+ * byte offset to UTF-16 index is sufficient.
+ *
+ * Returns `null` for pure-ASCII sources (byte offsets == UTF-16 offsets),
+ * which is the common case and avoids the allocation.
+ *
+ * @param source - The full source text.
+ * @returns A Map from UTF-8 byte offset to UTF-16 index, or `null` for ASCII.
+ */
+export function buildByteOffsetMap(source) {
+    if (!/[\u0080-\uffff]/u.test(source))
+        return null;
+    const map = new Map();
+    let byteOffset = 0;
+    let utf16Index = 0;
+    for (const ch of source) {
+        map.set(byteOffset, utf16Index);
+        byteOffset += Buffer.byteLength(ch, "utf-8");
+        utf16Index += ch.length;
+    }
+    map.set(byteOffset, utf16Index);
+    return map;
+}
+/** Slice `source` by tree-sitter byte offsets, translating through the map when present. */
+function sliceByBytes(source, startByte, endByte, offsetMap) {
+    if (!offsetMap)
+        return source.slice(startByte, endByte);
+    const start = offsetMap.get(startByte) ?? startByte;
+    const end = offsetMap.get(endByte) ?? endByte;
+    return source.slice(start, end);
+}
 function cleanCommentText(text) {
     const lines = text.split("\n");
     if (text.startsWith("/*")) {
@@ -152,19 +190,19 @@ function cleanCommentText(text) {
     let cleaned = lines.map((line) => line.replace(prefix, ""));
     return cleaned.filter((l) => l.trim().length > 0).join("\n");
 }
-function extractLeadingComments(node, source) {
+function extractLeadingComments(node, source, offsetMap) {
     const comments = [];
     let sibling = node.previousSibling;
     while (sibling) {
         if (COMMENT_NODE_TYPES.has(sibling.type)) {
-            const raw = source.slice(sibling.startIndex, sibling.endIndex);
+            const raw = sliceByBytes(source, sibling.startIndex, sibling.endIndex, offsetMap);
             comments.unshift(cleanCommentText(raw));
             sibling = sibling.previousSibling;
         }
         else if (sibling.type === "expression_statement") {
             const firstChild = sibling.namedChildren[0];
             if (firstChild?.type === "string") {
-                const raw = source.slice(firstChild.startIndex, firstChild.endIndex);
+                const raw = sliceByBytes(source, firstChild.startIndex, firstChild.endIndex, offsetMap);
                 comments.unshift(cleanCommentText(raw));
                 sibling = sibling.previousSibling;
             }
@@ -180,7 +218,7 @@ function extractLeadingComments(node, source) {
         return undefined;
     return comments.join("\n\n");
 }
-function extractDocstringFromBody(node, source) {
+function extractDocstringFromBody(node, source, offsetMap) {
     if (node.type !== "function_definition" && node.type !== "class_definition") {
         return undefined;
     }
@@ -193,7 +231,7 @@ function extractDocstringFromBody(node, source) {
     const stringNode = firstStmt.namedChildren[0];
     if (!stringNode || stringNode.type !== "string")
         return undefined;
-    return cleanCommentText(source.slice(stringNode.startIndex, stringNode.endIndex));
+    return cleanCommentText(sliceByBytes(source, stringNode.startIndex, stringNode.endIndex, offsetMap));
 }
 /**
  * Recursively walk a tree-sitter AST and collect nodes matching the given
@@ -213,16 +251,16 @@ function extractDocstringFromBody(node, source) {
  * @param depth - Current recursion depth (internal, start at 0).
  * @returns An array of {@link AstNode} objects for matching declarations.
  */
-export function walkTree(node, nodeTypes, source, maxDepth = 10, depth = 0) {
+export function walkTree(node, nodeTypes, source, maxDepth = 10, depth = 0, offsetMap) {
     const results = [];
     if (nodeTypes.has(node.type) && depth > 0) {
-        const leadingComments = extractLeadingComments(node, source);
-        const bodyDocstring = extractDocstringFromBody(node, source);
+        const leadingComments = extractLeadingComments(node, source, offsetMap);
+        const bodyDocstring = extractDocstringFromBody(node, source, offsetMap);
         const leadingDoc = [leadingComments, bodyDocstring]
             .filter((d) => d !== undefined && d.length > 0)
             .join("\n\n");
         results.push({
-            text: source.slice(node.startIndex, node.endIndex),
+            text: sliceByBytes(source, node.startIndex, node.endIndex, offsetMap),
             startLine: node.startPosition.row + 1,
             endLine: node.endPosition.row + 1,
             startIndex: node.startIndex,
@@ -234,7 +272,7 @@ export function walkTree(node, nodeTypes, source, maxDepth = 10, depth = 0) {
     }
     if (depth < maxDepth) {
         for (const child of node.children) {
-            results.push(...walkTree(child, nodeTypes, source, maxDepth, depth + 1));
+            results.push(...walkTree(child, nodeTypes, source, maxDepth, depth + 1, offsetMap));
         }
     }
     return results;

package/dist/chunker/pdf.js

@@ -22,19 +22,18 @@ function getStandardFontsUrl() {
  * Create a pdfjs-dist PDF document from a buffer.
  * Uses `@thednp/dommatrix` for DOMMatrix polyfill (lighter alternative to native canvas).
  * @param buffer - Raw buffer of the PDF file.
- * @returns A promise resolving to a pdfjs-dist PDFDocumentProxy.
+ * @returns The pdfjs LoadingTask for the document.
  */
-async function createPdfDocument(buffer) {
+async function getPdfLoadingTask(buffer) {
     const { default: CSSMatrix } = await import("@thednp/dommatrix");
     globalThis.DOMMatrix ??= CSSMatrix;
     globalThis.DOMMatrixReadOnly ??= CSSMatrix;
     const { getDocument } = await import("pdfjs-dist/legacy/build/pdf.mjs");
-    const loadingTask = getDocument({
+    return getDocument({
         data: new Uint8Array(buffer),
         standardFontDataUrl: getStandardFontsUrl(),
         verbosity: 0,
     });
-    return loadingTask.promise;
 }
 /**
  * Extract the full text content from a PDF file buffer.
@@ -47,17 +46,34 @@ export async function extractPdfText(buffer) {
     if (buffer.length > MAX_PDF_SIZE_BYTES) {
         throw new Error(`PDF too large: ${(buffer.length / 1024 / 1024).toFixed(1)} MB (max 100 MB)`);
     }
-    const pdf = await createPdfDocument(buffer);
-    const texts = [];
-    const pageCount = Math.min(pdf.numPages, MAX_PDF_PAGES);
-    for (let i = 1; i <= pageCount; i++) {
-        const page = await pdf.getPage(i);
-        const content = await page.getTextContent();
-        const textItems = content.items.filter((item) => typeof item === "object" && item !== null && "str" in item);
-        const strings = textItems.map((item) => item.str);
-        texts.push(strings.join(" "));
+    // loadingTask.destroy() releases the pdfjs worker/document resources —
+    // without it long-running watch/plugin processes leak them per PDF.
+    const loadingTask = await getPdfLoadingTask(buffer);
+    try {
+        const pdf = await loadingTask.promise;
+        const texts = [];
+        const pageCount = Math.min(pdf.numPages, MAX_PDF_PAGES);
+        for (let i = 1; i <= pageCount; i++) {
+            const page = await pdf.getPage(i);
+            try {
+                const content = await page.getTextContent();
+                const strings = [];
+                for (const item of content.items) {
+                    if (typeof item === "object" && item !== null && "str" in item) {
+                        strings.push(item.str);
+                    }
+                }
+                texts.push(strings.join(" "));
+            }
+            finally {
+                page.cleanup();
+            }
+        }
+        return texts.join("\n\n");
+    }
+    finally {
+        await loadingTask.destroy().catch(() => { });
     }
-    return texts.join("\n\n");
 }
 /**
  * Chunker for PDF documents (.pdf).

package/dist/cli/commands/init-helpers.js

@@ -379,10 +379,23 @@ export async function installPluginFromGlobal(opencodeDir, packageName, skipInst
     if (existsSync(workspaceTarget)) {
         rmSync(workspaceTarget, { recursive: true, force: true });
     }
-    // Create directory junction from workspace → global runtime
+    // Create directory junction from workspace → global runtime.
+    // Junction creation can throw (EPERM, cross-drive on Windows) — fall back
+    // to a copy instead of aborting `init`.
     console.log(`  ${c.created("Linking:")} ${packageName} from global cache...`);
     mkdirSync(path.dirname(workspaceTarget), { recursive: true });
-    createJunction(globalPluginDir, workspaceTarget);
+    try {
+        createJunction(globalPluginDir, workspaceTarget);
+    }
+    catch (err) {
+        console.log(`  ${c.warn("Junction failed, falling back to copy...")}`);
+        rmSync(workspaceTarget, { recursive: true, force: true });
+        const { cpSync } = await import("node:fs");
+        mkdirSync(path.dirname(workspaceTarget), { recursive: true });
+        cpSync(globalPluginDir, workspaceTarget, { recursive: true });
+        console.log(`  ${c.success("Copied:")} ${packageName} from global cache`);
+        return;
+    }
     const cliEntry = path.join(workspaceTarget, "dist", "cli.js");
     if (!existsSync(cliEntry)) {
         // Junction may not work (e.g. cross-drive on Windows) — fall back to copy

package/dist/cli/commands/init.js

@@ -11,7 +11,7 @@
  */
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
-import { loadConfig } from "../../core/config.js";
+import { loadConfig, findConfigFile } from "../../core/config.js";
 import { checkProviderHealth, pullOllamaModels } from "../../embedder/health.js";
 import { destroyAllPooledConnections } from "../../embedder/http.js";
 import { c } from "../format.js";
@@ -37,7 +37,10 @@ export function registerInitCommand(program) {
         try {
             const cwd = process.cwd();
             const packageMetadata = getPackageMetadata();
-            const configPath = path.join(cwd, "opencode-rag.json");
+            // Use findConfigFile so an existing config in .opencode/rag.json (or
+            // .opencode/opencode-rag.json) is respected instead of being shadowed
+            // by a new root-level opencode-rag.json.
+            const configPath = findConfigFile(cwd) ?? path.join(cwd, "opencode-rag.json");
             const opencodeDir = path.join(cwd, ".opencode");
             const gitignorePath = path.join(opencodeDir, ".gitignore");
             const opencodeConfigPath = path.join(opencodeDir, "opencode.json");
@@ -253,27 +256,34 @@ export function registerInitCommand(program) {
                         return { model: r.model, baseUrl: ragConfig.embedding.baseUrl, proxy: ragConfig.embedding.proxy };
                     });
                     console.log(`\n  ${c.warn("Models not found:")} ${pullEntries.map((e) => e.model).join(", ")}`);
-                    const readline = await import("node:readline");
-                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-                    const answer = await new Promise((resolve) => {
-                        rl.question(`  Pull ${pullEntries.length === 1 ? "this model" : "these models"} now? (y/n) `, resolve);
-                    });
-                    rl.close();
-                    if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
-                        console.log();
-                        try {
-                            await pullOllamaModels(pullEntries, (model, line) => {
-                                console.log(`  ${c.value(model)}: ${line}`);
-                            });
-                            console.log(`\n  ${c.success("Models pulled successfully.")}`);
-                        }
-                        catch (err) {
-                            console.error(`\n  ${c.error("Pull failed:")} ${err.message}`);
-                            console.log(`  ${c.dim("Pull manually with: ollama pull <model>")}`);
-                        }
+                    // Non-TTY guard: rl.question would block forever with a still-open
+                    // stdin pipe (e.g. `echo y | opencode-rag init`, CI runners).
+                    if (!process.stdin.isTTY) {
+                        console.log(`  ${c.dim("Non-interactive shell — skipping. Pull manually with: ollama pull <model>")}`);
                     }
                     else {
-                        console.log(`  ${c.dim("Skipped. Pull manually with: ollama pull <model>")}`);
+                        const readline = await import("node:readline");
+                        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                        const answer = await new Promise((resolve) => {
+                            rl.question(`  Pull ${pullEntries.length === 1 ? "this model" : "these models"} now? (y/n) `, resolve);
+                        });
+                        rl.close();
+                        if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+                            console.log();
+                            try {
+                                await pullOllamaModels(pullEntries, (model, line) => {
+                                    console.log(`  ${c.value(model)}: ${line}`);
+                                });
+                                console.log(`\n  ${c.success("Models pulled successfully.")}`);
+                            }
+                            catch (err) {
+                                console.error(`\n  ${c.error("Pull failed:")} ${err.message}`);
+                                console.log(`  ${c.dim("Pull manually with: ollama pull <model>")}`);
+                            }
+                        }
+                        else {
+                            console.log(`  ${c.dim("Skipped. Pull manually with: ollama pull <model>")}`);
+                        }
                     }
                 }
                 const hasErrors = results.some((r) => r.status === "error");

package/dist/cli/commands/quirk.js

@@ -16,6 +16,7 @@ export function registerQuirkCommand(program) {
         .option("-t, --type <type>", "quirk type: gotcha, preference, decision, environment-constraint")
         .option("--tag <tags...>", "tags for filtering")
         .option("--source-ref <path>", "source file path reference")
+        .option("-c, --config <path>", "path to config file")
         .action(async (content, options) => {
         try {
             const ctx = await resolveCliContext(options, resolveLogPath());
@@ -49,6 +50,11 @@ export function registerQuirkCommand(program) {
         .option("-c, --config <path>", "path to config file")
         .action(async (id, options) => {
         try {
+            const confidence = options.confidence;
+            if (confidence !== undefined && (Number.isNaN(confidence) || confidence < 0 || confidence > 1)) {
+                logCliError(resolveLogPath(), "quirk update", "Failed to update quirk: --confidence must be a number between 0 and 1");
+                process.exit(1);
+            }
             const ctx = await resolveCliContext(options, resolveLogPath());
             const { config, embedder, store, keywordIndex } = ctx;
             const tags = options.tag;
@@ -56,7 +62,7 @@ export function registerQuirkCommand(program) {
                 content: options.content,
                 quirkType: options.type,
                 tags: tags ? (Array.isArray(tags) ? tags : [tags]) : undefined,
-                confidence: options.confidence,
+                confidence,
                 sourceRef: options.sourceRef,
             });
             logCliInfo(ctx.logFilePath, "quirk update", `\n${c.success("Quirk updated:")}`);
@@ -148,7 +154,7 @@ export function registerQuirkCommand(program) {
             const { config, embedder, store, keywordIndex } = ctx;
             const results = await recallQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, content, { topK: 5 });
             if (results.length > 0) {
-                logCliInfo(ctx.logFilePath, "quirk test", c.success("\n✓ Quirk has been appended:\n"));
+                logCliInfo(ctx.logFilePath, "quirk test", c.warn("\n✗ Similar quirk(s) already exist — quirk has NOT been appended:\n"));
                 for (const r of results) {
                     const badge = r.chunk.metadata.quirkType ? `[${r.chunk.metadata.quirkType}] ` : "";
                     const tags = r.chunk.metadata.tags?.length ? ` (${r.chunk.metadata.tags.join(", ")})` : "";
@@ -159,7 +165,7 @@ export function registerQuirkCommand(program) {
                 }
             }
             else {
-                logCliInfo(ctx.logFilePath, "quirk test", c.warn("\n✗ No matching quirk found — quirk has not been appended\n"));
+                logCliInfo(ctx.logFilePath, "quirk test", c.success("\n✓ No matching quirk found — safe to append\n"));
             }
             await cleanupContext(ctx);
         }

package/dist/cli/commands/setup.js

@@ -81,9 +81,12 @@ export function registerSetupCommand(program) {
         if (options.uninstall) {
             console.log(`\n${c.heading("Removing OpenCodeRAG runtime...")}\n`);
             removeIfExists(runtimePluginDir);
-            removeIfExists(runtimeSdkDir);
+            // Only remove the @opencode-ai/plugin SDK package — the scope dir may
+            // be shared with other OpenCode plugins/tools.
+            removeIfExists(runtimeSdkPluginDir);
             removeIfExists(versionFile);
-            console.log(`  ${c.updated("Removed:")} ${c.file(runtimeDir)}`);
+            console.log(`  ${c.updated("Removed:")} ${c.file(runtimePluginDir)}`);
+            console.log(`  ${c.updated("Removed:")} ${c.file(runtimeSdkPluginDir)}`);
             console.log(`\n  ${c.success("Done.")} Run ${c.file("npm uninstall -g opencode-rag-plugin")} to remove the global package.\n`);
             return;
         }

package/dist/cli/commands/status.js

@@ -147,14 +147,23 @@ export function registerStatusCommand(program) {
                     logCliInfo(logFilePath, "status", `${c.label("Runtime:")}           ${c.warn("version unknown — run `opencode-rag setup`")}`);
                 }
             }
-            // Async GitHub update check (fire-and-forget, 5s timeout).
-            // Runs unless autoUpdate is explicitly disabled.
+            // GitHub update check. Runs unless autoUpdate is explicitly disabled.
+            // Awaited (raced against 3s) so the result can actually print —
+            // process.exit(0) below would previously kill the promise before it
+            // resolved, making the Update: line dead code.
             if (config.autoUpdate?.enabled) {
-                checkForUpdate(pkg.version).then((info) => {
-                    if (info.updateAvailable) {
+                try {
+                    const info = await Promise.race([
+                        checkForUpdate(pkg.version),
+                        new Promise((resolve) => setTimeout(() => resolve(null), 3000)),
+                    ]);
+                    if (info && info.updateAvailable) {
                         process.stdout.write(`  ${c.label("Update:")}            ${c.warn(`v${info.latestVersion} available — run \`opencode-rag update\` to install`)}\n`);
                     }
-                }).catch(() => { });
+                }
+                catch {
+                    /* ignore network errors */
+                }
             }
             // Force exit — avoid LanceDB close() hanging on Windows native bindings.
             // Status is read-only so there's no state to lose.

package/dist/cli/commands/ui.js

@@ -5,7 +5,7 @@
  * `ui` command — starts a local web UI for browsing the vector database.
  */
 import path from "node:path";
-import { c, resolveCliContext, logCliError, logCliInfo } from "../format.js";
+import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo } from "../format.js";
 /**
  * Register the `ui` command on the given Commander program.
  *
@@ -33,9 +33,10 @@ export function registerUiCommand(program) {
             const openBrowser = options.open !== false && (config.ui?.openBrowser ?? true);
             const { startWebUi } = await import("../../web/server.js");
             const server = await startWebUi(storePath, port, cwd, config.embedding.vectorDimension ?? 384, config);
-            const url = `http://127.0.0.1:${server.port}`;
+            const url = `http://127.0.0.1:${server.port}/?token=${server.token}`;
             logCliInfo(logFilePath, "ui", `\n${c.heading("OpenCodeRAG Web UI")}`);
             logCliInfo(logFilePath, "ui", `  ${c.label("URL:")} ${c.value(url)}`);
+            logCliInfo(logFilePath, "ui", `  ${c.dim("The token in the URL authenticates this session — keep it private.")}`);
             logCliInfo(logFilePath, "ui", `  ${c.dim("Press Ctrl+C to stop")}\n`);
             if (openBrowser) {
                 const { spawn } = await import("node:child_process");
@@ -52,14 +53,27 @@ export function registerUiCommand(program) {
                     console.error(c.dim(`Could not open browser automatically. Open ${url} manually.`));
                 }
             }
-            process.on("SIGINT", async () => {
-                await server.close();
-                process.exit(0);
-            });
-            process.on("SIGTERM", async () => {
-                await server.close();
+            let shuttingDown = false;
+            const shutdown = async () => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                try {
+                    await server.close();
+                }
+                catch {
+                    // best-effort — the process is exiting anyway
+                }
+                try {
+                    await cleanupContext(ctx);
+                }
+                catch {
+                    // best-effort cleanup
+                }
                 process.exit(0);
-            });
+            };
+            process.on("SIGINT", shutdown);
+            process.on("SIGTERM", shutdown);
         }
         catch (err) {
             const message = err.message || String(err);

package/dist/cli/commands/update.js

@@ -24,11 +24,10 @@ export function registerUpdateCommand(program) {
         console.log(`\n${c.heading("OpenCodeRAG Update")}\n`);
         console.log(`  ${c.label("Current version:")} ${c.value(currentVersion)}`);
         console.log(`  ${c.label("Checking...")}     `);
-        let info;
-        try {
-            info = await checkForUpdate(currentVersion);
-        }
-        catch {
+        // checkForUpdate never throws (all failures collapse to "no update"),
+        // so the try/catch below is defensive only.
+        const info = await checkForUpdate(currentVersion).catch(() => null);
+        if (!info) {
             console.log(`\n  ${c.warn("Could not reach the update server. Check your network and try again.")}\n`);
             process.exit(1);
             return;

package/dist/cli/format.d.ts

@@ -60,7 +60,7 @@ export declare const c: {
  * @param message - Human-readable error message.
  * @param error - Optional error object for structured logging.
  */
-export declare function logCliError(_logFilePath: string, _scope: string, message: string, _error: unknown): void;
+export declare function logCliError(logFilePath: string, scope: string, message: string, error?: unknown): void;
 /**
  * Log an informational message to stdout and optionally append to the debug log.
  *
@@ -68,7 +68,7 @@ export declare function logCliError(_logFilePath: string, _scope: string, messag
  * @param scope - Logical scope (e.g. "index", "query") for log filtering.
  * @param message - Human-readable info message.
  */
-export declare function logCliInfo(_logFilePath: string, _scope: string, message: string): void;
+export declare function logCliInfo(logFilePath: string, scope: string, message: string): void;
 /**
  * Resolve a full `RagContext` from CLI options and log the config details.
  *
@@ -82,6 +82,9 @@ export declare function resolveCliContext(opt: CliOptions, logFilePath: string,
 /**
  * Gracefully close a `RagContext` — closes the vector store and destroys pooled HTTP connections.
  *
+ * The store close is raced against a timeout because LanceDB's native `close()`
+ * can hang indefinitely on Windows; callers must never be blocked forever.
+ *
  * @param ctx - The `RagContext` to clean up.
  */
 export declare function cleanupContext(ctx: RagContext): Promise<void>;