opencode-rag-plugin 1.19.5 → 1.20.0

package/dist/watcher.js

@@ -5,7 +5,7 @@
  */
 import chokidar from "chokidar";
 import path from "node:path";
-import { writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { writeFileSync, unlinkSync, existsSync, readFileSync, openSync, closeSync } from "node:fs";
 import { appendDebugLog } from "./core/fileLogger.js";
 import { isCorruptionError } from "./vectorstore/lancedb.js";
 import { createWatchPassScheduler, createWatchIgnore, runIndexPass, } from "./indexer.js";
@@ -18,6 +18,81 @@ function writeWatcherStatus(storePath, status) {
         // silently ignore write errors
     }
 }
+// ── Cross-process watcher claim lock ────────────────────────────────────────
+// `index.lock` only serializes individual index passes — it does NOT stop N
+// processes (N OpenCode sessions, or a session + `opencode-rag index --watch`)
+// from each spawning their own chokidar watcher for the same workspace. Every
+// extra watcher fires its own fire-and-forget initial pass (all but one skip
+// the pass lock and then retry every 30s) and burns file-watcher resources.
+// The claim lock below guarantees at most ONE active watcher per workspace:
+// the first process to claim it runs the watcher; the others stay dormant and
+// periodically re-check so they take over if the owning process exits.
+const WATCHER_LOCK_FILE = "watcher.lock";
+/** How often a dormant indexer re-checks whether the watcher lock is free. */
+const WATCHER_RECHECK_MS = 60_000;
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readWatcherLock(storePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(path.join(storePath, WATCHER_LOCK_FILE), "utf-8"));
+        return typeof parsed.pid === "number" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Atomically claim the watcher lock for a workspace. Returns true only if
+ * this process is now the active watcher. A stale lock (dead PID) or an
+ * unreadable/corrupt lock file is cleared and re-claimed.
+ */
+export function tryAcquireWatcherLock(storePath) {
+    const lockPath = path.join(storePath, WATCHER_LOCK_FILE);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const existing = readWatcherLock(storePath);
+        if (!existing || !isPidAlive(existing.pid)) {
+            // Stale, corrupt, or missing lock — clear it and claim atomically
+            // (O_EXCL create so two racing processes cannot both win).
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* may not exist */ }
+            try {
+                const fd = openSync(lockPath, "wx");
+                try {
+                    writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), "utf-8");
+                }
+                finally {
+                    closeSync(fd);
+                }
+                return true;
+            }
+            catch {
+                // Someone else claimed it between our unlink and create — retry once.
+                continue;
+            }
+        }
+        return false;
+    }
+    return false;
+}
+/** Release the watcher lock — only if this process owns it. */
+export function releaseWatcherLock(storePath) {
+    const lock = readWatcherLock(storePath);
+    if (lock?.pid === process.pid) {
+        try {
+            unlinkSync(path.join(storePath, WATCHER_LOCK_FILE));
+        }
+        catch { /* ignore */ }
+    }
+}
 /**
  * Create a background file watcher that automatically re-indexes the
  * workspace when files change. Uses chokidar for file system events and
@@ -29,110 +104,120 @@ function writeWatcherStatus(storePath, status) {
  */
 export function createBackgroundIndexer(options) {
     const { cwd, storePath, config, store, embedder, logFilePath, logLevel, keywordIndex, descriptionProvider, dimension } = options;
-    writeWatcherStatus(storePath, { running: false, lastRunAt: undefined });
-    const ac = new AbortController();
-    const updateStatus = (partial) => {
-        writeWatcherStatus(storePath, { running: false, lastRunAt: undefined, ...partial });
-    };
-    const runPass = async (filterPaths) => {
-        updateStatus({ running: true, lastRunAt: Date.now() });
-        try {
-            const stats = await runIndexPass({
-                cwd,
-                storePath,
-                config,
-                store,
-                embedder,
-                keywordIndex,
-                descriptionProvider,
-                dimension,
-                filterPaths,
-                abortSignal: ac.signal,
-                logger: {
-                    info: (message) => appendDebugLog(logFilePath, { scope: "autoIndex", message }, logLevel),
-                    warn: (message) => appendDebugLog(logFilePath, { scope: "autoIndex", message }, logLevel),
-                    debug: (message) => appendDebugLog(logFilePath, { scope: "autoIndex", message: `DEBUG: ${message}`, severity: "debug" }, logLevel),
-                },
-            });
-            // A lock-skipped pass did NO work — retry shortly so the workspace
-            // does not stay unindexed until the next file event.
-            if (stats.skipped) {
+    const autoIndexCfg = config.openCode.autoIndex ?? { enabled: false, debounceMs: 5000, intervalMs: 300000 };
+    let active = false;
+    let recheckTimer;
+    let stopActive;
+    /** Start the chokidar watcher, debounced scheduler, and initial pass. */
+    const startActive = () => {
+        if (active)
+            return;
+        active = true;
+        writeWatcherStatus(storePath, { running: false, lastRunAt: undefined });
+        const ac = new AbortController();
+        const updateStatus = (partial) => {
+            writeWatcherStatus(storePath, { running: false, lastRunAt: undefined, ...partial });
+        };
+        const runPass = async (filterPaths) => {
+            updateStatus({ running: true, lastRunAt: Date.now() });
+            try {
+                const stats = await runIndexPass({
+                    cwd,
+                    storePath,
+                    config,
+                    store,
+                    embedder,
+                    keywordIndex,
+                    descriptionProvider,
+                    dimension,
+                    filterPaths,
+                    abortSignal: ac.signal,
+                    logger: {
+                        info: (message) => appendDebugLog(logFilePath, { scope: "autoIndex", message }, logLevel),
+                        warn: (message) => appendDebugLog(logFilePath, { scope: "autoIndex", message }, logLevel),
+                        debug: (message) => appendDebugLog(logFilePath, { scope: "autoIndex", message: `DEBUG: ${message}`, severity: "debug" }, logLevel),
+                    },
+                });
+                // A lock-skipped pass did NO work — retry shortly so the workspace
+                // does not stay unindexed until the next file event.
+                if (stats.skipped) {
+                    appendDebugLog(logFilePath, {
+                        scope: "autoIndex",
+                        message: "Index pass skipped (another pass holds the lock) — retrying in 30s",
+                    }, logLevel);
+                    if (!ac.signal.aborted) {
+                        setTimeout(() => {
+                            if (!ac.signal.aborted)
+                                scheduler.notifyChange(filterPaths);
+                        }, 30_000).unref();
+                    }
+                }
+                updateStatus({ running: false, lastRunAt: Date.now() });
+            }
+            catch (err) {
                 appendDebugLog(logFilePath, {
                     scope: "autoIndex",
-                    message: "Index pass skipped (another pass holds the lock) — retrying in 30s",
+                    message: "Watch reindex pass failed",
+                    error: err,
                 }, logLevel);
-                if (!ac.signal.aborted) {
-                    setTimeout(() => {
-                        if (!ac.signal.aborted)
-                            scheduler.notifyChange(filterPaths);
-                    }, 30_000).unref();
+                if (isCorruptionError(err)) {
+                    appendDebugLog(logFilePath, {
+                        scope: "autoIndex",
+                        message: "Corruption detected — run 'opencode-rag index --force' to rebuild manually",
+                    }, logLevel);
                 }
+                updateStatus({ running: false, lastRunAt: Date.now() });
             }
-            updateStatus({ running: false, lastRunAt: Date.now() });
-        }
-        catch (err) {
+        };
+        // Fire-and-forget initial index pass
+        runPass().catch((err) => {
             appendDebugLog(logFilePath, {
                 scope: "autoIndex",
-                message: "Watch reindex pass failed",
+                message: "Initial index pass failed",
                 error: err,
             }, logLevel);
-            if (isCorruptionError(err)) {
-                appendDebugLog(logFilePath, {
-                    scope: "autoIndex",
-                    message: "Corruption detected — run 'opencode-rag index --force' to rebuild manually",
-                }, logLevel);
-            }
-            updateStatus({ running: false, lastRunAt: Date.now() });
-        }
-    };
-    // Fire-and-forget initial index pass
-    runPass().catch((err) => {
-        appendDebugLog(logFilePath, {
-            scope: "autoIndex",
-            message: "Initial index pass failed",
-            error: err,
-        }, logLevel);
-    });
-    const autoIndexCfg = config.openCode.autoIndex ?? { enabled: false, debounceMs: 5000, intervalMs: 300000 };
-    const scheduler = createWatchPassScheduler(runPass, (error) => {
-        const message = error.message || String(error);
-        appendDebugLog(logFilePath, {
-            scope: "autoIndex",
-            message: `Watch reindex failed: ${message}`,
-            error,
-        }, logLevel);
-    }, autoIndexCfg.debounceMs);
-    const watcher = chokidar.watch(cwd, {
-        ignored: createWatchIgnore(cwd, config, storePath),
-        ignoreInitial: true,
-        persistent: true,
-    });
-    const handleChange = (filePath) => scheduler.notifyChange(filePath ? [filePath] : undefined);
-    watcher.on("add", handleChange);
-    watcher.on("change", handleChange);
-    watcher.on("unlink", handleChange);
-    watcher.on("unlinkDir", handleChange);
-    watcher.on("addDir", handleChange);
-    watcher.on("error", (error) => {
-        appendDebugLog(logFilePath, {
-            scope: "autoIndex",
-            message: `Watcher error: ${error.message}`,
-            error,
-        }, logLevel);
-    });
-    // Periodic timer: only needed for git backend (chokidar gets real FS events).
-    // Note: with git mode BOTH backends run — the scheduler coalesces redundant
-    // passes into one, so this only adds a safety net for missed events.
-    const watcherBackend = autoIndexCfg.watcher ?? "chokidar";
-    const periodicTimer = watcherBackend === "git"
-        ? setInterval(() => {
-            scheduler.notifyChange();
-        }, autoIndexCfg.intervalMs)
-        : undefined;
-    // Never keep the process alive just for the periodic scan
-    periodicTimer?.unref();
-    return {
-        async close() {
+        });
+        const scheduler = createWatchPassScheduler(runPass, (error) => {
+            const message = error.message || String(error);
+            appendDebugLog(logFilePath, {
+                scope: "autoIndex",
+                message: `Watch reindex failed: ${message}`,
+                error,
+            }, logLevel);
+        }, autoIndexCfg.debounceMs);
+        const watcher = chokidar.watch(cwd, {
+            ignored: createWatchIgnore(cwd, config, storePath),
+            ignoreInitial: true,
+            persistent: true,
+        });
+        const handleChange = (filePath) => scheduler.notifyChange(filePath ? [filePath] : undefined);
+        watcher.on("add", handleChange);
+        watcher.on("change", handleChange);
+        watcher.on("unlink", handleChange);
+        watcher.on("unlinkDir", handleChange);
+        watcher.on("addDir", handleChange);
+        watcher.on("error", (error) => {
+            appendDebugLog(logFilePath, {
+                scope: "autoIndex",
+                message: `Watcher error: ${error.message}`,
+                error,
+            }, logLevel);
+        });
+        // Periodic timer: only needed for git backend (chokidar gets real FS events).
+        // Note: with git mode BOTH backends run — the scheduler coalesces redundant
+        // passes into one, so this only adds a safety net for missed events.
+        const watcherBackend = autoIndexCfg.watcher ?? "chokidar";
+        const periodicTimer = watcherBackend === "git"
+            ? setInterval(() => {
+                scheduler.notifyChange();
+            }, autoIndexCfg.intervalMs)
+            : undefined;
+        // Never keep the process alive just for the periodic scan
+        periodicTimer?.unref();
+        stopActive = async () => {
+            if (!active)
+                return;
+            active = false;
             if (periodicTimer)
                 clearInterval(periodicTimer);
             ac.abort();
@@ -154,10 +239,51 @@ export function createBackgroundIndexer(options) {
                 }
                 catch { /* ignore */ }
             }
+            releaseWatcherLock(storePath);
             appendDebugLog(logFilePath, {
                 scope: "autoIndex",
                 message: "Background indexer shut down",
             });
+        };
+    };
+    if (tryAcquireWatcherLock(storePath)) {
+        startActive();
+    }
+    else {
+        // Another process already runs the watcher for this workspace (a second
+        // OpenCode session, `opencode-rag index --watch`, …). Stay dormant and
+        // re-check periodically so this process takes over once the owner exits.
+        const owner = readWatcherLock(storePath);
+        appendDebugLog(logFilePath, {
+            scope: "autoIndex",
+            message: owner?.pid
+                ? `Watcher already running for this workspace (PID ${owner.pid}) — skipping duplicate watcher`
+                : "Watcher already running for this workspace — skipping duplicate watcher",
+        }, logLevel);
+        recheckTimer = setInterval(() => {
+            if (!active && tryAcquireWatcherLock(storePath)) {
+                appendDebugLog(logFilePath, {
+                    scope: "autoIndex",
+                    message: "Previous watcher released this workspace — taking over",
+                }, logLevel);
+                if (recheckTimer) {
+                    clearInterval(recheckTimer);
+                    recheckTimer = undefined;
+                }
+                startActive();
+            }
+        }, WATCHER_RECHECK_MS);
+        recheckTimer.unref();
+    }
+    return {
+        async close() {
+            if (recheckTimer) {
+                clearInterval(recheckTimer);
+                recheckTimer = undefined;
+            }
+            if (stopActive) {
+                await stopActive();
+            }
         },
     };
 }

package/dist/web/api.js

@@ -602,17 +602,18 @@ function redactKeys(obj) {
     }
 }
 /**
- * Project chunk embeddings to 2D via PCA for the Embedding Space Explorer.
- * Capped at 5000 chunks and memoized per (storePath, maxChunks) so the
+ * Project chunk embeddings to 2D/3D via PCA for the Embedding Space Explorer.
+ * Capped at 5000 chunks and memoized per (maxChunks, dims) so the
  * O(n·dim²) computation does not run on every visit.
  */
 let projectionCache = null;
 async function handleEmbeddingProjection(store, params) {
     const rawMaxChunks = parseInt(params.get("maxChunks") ?? "5000", 10);
     const maxChunks = Number.isFinite(rawMaxChunks) ? Math.min(5000, Math.max(1, rawMaxChunks)) : 5000;
+    const dims = parseInt(params.get("dims") ?? "2", 10) === 3 ? 3 : 2;
     try {
         // Invalidated after a reindex pass completes (see handleReindex)
-        const cacheKey = `${maxChunks}`;
+        const cacheKey = `${maxChunks}:${dims}`;
         if (projectionCache && projectionCache.key === cacheKey) {
             return { status: 200, body: projectionCache.body };
         }
@@ -622,23 +623,31 @@ async function handleEmbeddingProjection(store, params) {
             return { status: 200, body: projectionCache.body };
         }
         if (chunks.length === 1) {
-            const body = { points: [{ id: chunks[0].id, x: 0.5, y: 0.5, filePath: chunks[0].filePath, startLine: chunks[0].startLine, endLine: chunks[0].endLine, language: chunks[0].language, description: chunks[0].description }], totalChunks: 1, displayedChunks: 1 };
+            const point = { id: chunks[0].id, x: 0.5, y: 0.5, filePath: chunks[0].filePath, startLine: chunks[0].startLine, endLine: chunks[0].endLine, language: chunks[0].language, description: chunks[0].description };
+            if (dims === 3)
+                point.z = 0.5;
+            const body = { points: [point], totalChunks: 1, displayedChunks: 1 };
             projectionCache = { key: cacheKey, body };
             return { status: 200, body };
         }
         const { computePCA } = await import("./pca.js");
         const vectors = chunks.map(c => c.embedding);
-        const projected = computePCA(vectors);
-        const points = chunks.map((c, i) => ({
-            id: c.id,
-            x: projected[i].x,
-            y: projected[i].y,
-            filePath: c.filePath,
-            startLine: c.startLine,
-            endLine: c.endLine,
-            language: c.language,
-            description: c.description,
-        }));
+        const projected = computePCA(vectors, dims);
+        const points = chunks.map((c, i) => {
+            const point = {
+                id: c.id,
+                x: projected[i].x,
+                y: projected[i].y,
+                filePath: c.filePath,
+                startLine: c.startLine,
+                endLine: c.endLine,
+                language: c.language,
+                description: c.description,
+            };
+            if (dims === 3)
+                point.z = projected[i].z;
+            return point;
+        });
         const body = { points, totalChunks: chunks.length, displayedChunks: points.length };
         projectionCache = { key: cacheKey, body };
         return { status: 200, body };

package/dist/web/pca.d.ts

@@ -1,7 +1,10 @@
 /**
- * Self-contained, zero-dependency PCA implementation for 2D embedding projection.
+ * Self-contained, zero-dependency PCA implementation for embedding projection.
+ * Supports projecting to 2 or 3 dimensions (top-K eigenvectors via power
+ * iteration + deflation).
  */
-export declare function computePCA(vectors: number[][]): {
+export declare function computePCA(vectors: number[][], dims?: 2 | 3): {
     x: number;
     y: number;
+    z?: number;
 }[];

package/dist/web/pca.js

@@ -1,13 +1,15 @@
 /**
- * Self-contained, zero-dependency PCA implementation for 2D embedding projection.
+ * Self-contained, zero-dependency PCA implementation for embedding projection.
+ * Supports projecting to 2 or 3 dimensions (top-K eigenvectors via power
+ * iteration + deflation).
  */
-export function computePCA(vectors) {
+export function computePCA(vectors, dims = 2) {
     const n = vectors.length;
     if (n === 0)
         return [];
     const dim = vectors[0].length;
     if (n === 1)
-        return [{ x: 0.5, y: 0.5 }];
+        return dims === 3 ? [{ x: 0.5, y: 0.5, z: 0.5 }] : [{ x: 0.5, y: 0.5 }];
     // 1. Compute column means
     const means = new Array(dim).fill(0);
     for (let i = 0; i < n; i++) {
@@ -19,7 +21,9 @@ export function computePCA(vectors) {
         means[j] /= n;
     // 2. Center data
     const centered = vectors.map(v => v.map((val, j) => val - means[j]));
-    // 3. Compute covariance matrix (dim x dim), upper triangle
+    // 3. Compute covariance matrix (dim x dim); fill the upper triangle then
+    // mirror it so the matrix is symmetric (power iteration needs a symmetric
+    // operator to find the true principal axes).
     const cov = Array.from({ length: dim }, () => new Array(dim).fill(0));
     for (let i = 0; i < n; i++) {
         for (let j = 0; j < dim; j++) {
@@ -31,23 +35,42 @@ export function computePCA(vectors) {
     for (let j = 0; j < dim; j++) {
         for (let k = j; k < dim; k++) {
             cov[j][k] /= n - 1;
+            cov[k][j] = cov[j][k];
         }
     }
-    // 4. Power iteration to find top-2 eigenvectors
-    const pc1 = powerIteration(cov, dim, 50);
-    // Deflate: subtract PC1's contribution to find PC2
-    const deflated = cov.map((row, i) => {
-        const pc1DotRow = pc1.reduce((sum, v, idx) => sum + v * cov[i][idx], 0);
-        const pc1NormSq = pc1.reduce((sum, v) => sum + v * v, 0);
-        return row.map((val, j) => val - (pc1DotRow / pc1NormSq) * pc1[j]);
+    // 4. Find the top-K eigenvectors: power iteration, then deflate the
+    // covariance by each discovered eigenvector before finding the next.
+    // Once the remaining matrix is numerically ~zero (degenerate / low-rank
+    // input), the rest of the PCs are zero vectors — this keeps PC2/PC3 from
+    // picking up deflation noise and avoids NaN from a 0/0 deflation.
+    const pcs = [];
+    let deflated = cov;
+    const threshold = maxAbs(cov) * 1e-12;
+    for (let pc = 0; pc < dims; pc++) {
+        if (maxAbs(deflated) <= threshold) {
+            pcs.push(new Array(dim).fill(0));
+            continue;
+        }
+        const eigen = powerIteration(deflated, dim, 50);
+        pcs.push(eigen);
+        deflated = deflate(deflated, eigen);
+    }
+    // 5. Project centered data onto the PCs
+    const projected = centered.map(v => {
+        const point = { x: 0, y: 0, z: 0 };
+        for (let pc = 0; pc < dims; pc++) {
+            const s = v.reduce((sum, val, j) => sum + val * pcs[pc][j], 0);
+            if (pc === 0)
+                point.x = s;
+            else if (pc === 1)
+                point.y = s;
+            else
+                point.z = s;
+        }
+        return point;
     });
-    const pc2 = powerIteration(deflated, dim, 50);
-    // 5. Project centered data onto PCs
-    const projected = centered.map(v => ({
-        x: v.reduce((sum, val, j) => sum + val * pc1[j], 0),
-        y: v.reduce((sum, val, j) => sum + val * pc2[j], 0),
-    }));
-    // 6. Normalize to [0, 1]
+    // 6. Normalize to [0, 1]. 2D keeps per-axis normalization (unchanged);
+    // 3D uses the max extent across all axes so the cube stays proportional.
     const xs = projected.map(p => p.x);
     const ys = projected.map(p => p.y);
     const minX = Math.min(...xs);
@@ -56,11 +79,43 @@ export function computePCA(vectors) {
     const maxY = Math.max(...ys);
     const rangeX = maxX - minX || 1;
     const rangeY = maxY - minY || 1;
+    if (dims === 2) {
+        return projected.map(p => ({
+            x: (p.x - minX) / rangeX,
+            y: (p.y - minY) / rangeY,
+        }));
+    }
+    const zs = projected.map(p => p.z);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    const maxRange = Math.max(rangeX, rangeY, maxZ - minZ || 1);
     return projected.map(p => ({
-        x: (p.x - minX) / rangeX,
-        y: (p.y - minY) / rangeY,
+        x: (p.x - minX) / maxRange,
+        y: (p.y - minY) / maxRange,
+        z: (p.z - minZ) / maxRange,
     }));
 }
+/** Subtract the outer-product contribution of a principal component from a symmetric matrix. */
+function deflate(matrix, pc) {
+    const pcNormSq = pc.reduce((sum, v) => sum + v * v, 0);
+    return matrix.map((row, i) => {
+        const pcDotRow = pc.reduce((sum, v, idx) => sum + v * matrix[i][idx], 0);
+        const scale = pcNormSq > 1e-12 ? pcDotRow / pcNormSq : 0;
+        return row.map((val, j) => val - scale * pc[j]);
+    });
+}
+/** Largest absolute entry of a matrix. */
+function maxAbs(matrix) {
+    let m = 0;
+    for (const row of matrix) {
+        for (const val of row) {
+            const abs = Math.abs(val);
+            if (abs > m)
+                m = abs;
+        }
+    }
+    return m;
+}
 /** Power iteration to find the dominant eigenvector of a symmetric matrix. */
 function powerIteration(matrix, dim, maxIter) {
     let v = new Array(dim).fill(0).map(() => Math.random() * 2 - 1);