opencode-rag-plugin 1.15.0 → 1.17.0

package/dist/core/config.js

@@ -2,7 +2,7 @@
  * @fileoverview Configuration types and defaults for OpenCodeRAG. Defines RagConfig,
  * all sub-config interfaces, DEFAULT_CONFIG, validateConfig, and loadConfig.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { env } from "node:process";
 export const DEFAULT_CONFIG = {
@@ -106,6 +106,7 @@ export const DEFAULT_CONFIG = {
         embedConcurrency: 6,
         ollamaMaxBatchSize: 4000,
         descriptionConcurrency: 4,
+        maxSvgSizeBytes: 1_048_576,
     },
     vectorStore: {
         path: "./.opencode/rag_db",
@@ -113,7 +114,7 @@ export const DEFAULT_CONFIG = {
     },
     retrieval: {
         topK: 20,
-        minScore: 0.5,
+        minScore: 0.35,
         hybridSearch: {
             enabled: true,
             keywordWeight: 0.4,
@@ -130,6 +131,7 @@ export const DEFAULT_CONFIG = {
         enabled: true,
         maxContextChunks: 10,
         readOverride: true,
+        injectSystemPrompt: true,
         autoIndex: {
             enabled: false,
             debounceMs: 2000,
@@ -143,7 +145,7 @@ export const DEFAULT_CONFIG = {
         model: "minicpm-v4.6:latest",
         baseUrl: "http://127.0.0.1:11434/api",
         timeoutMs: 60000,
-        prompt: "Describe this image 10-20 comma-separated keywords.",
+        prompt: "Describe this image in 1-2 sentences: what it shows, its purpose, and key visual elements.",
         think: false,
         numCtx: 2048,
         resizeMaxDimension: 1024,
@@ -156,7 +158,7 @@ export const DEFAULT_CONFIG = {
         think: false,
         numCtx: 4096,
         timeoutMs: 60000,
-        systemPrompt: "Describe this code in 10-20 comma-separated keywords.",
+        systemPrompt: "Describe this code in 2-3 sentences: purpose, key concepts, inputs/outputs, and dependencies. No code repetition.",
         batchConcurrency: 1,
         retryMax: 3,
         retryBaseDelayMs: 1000,
@@ -426,4 +428,32 @@ export function loadConfig(filePath, validate = true) {
     }
     return cfg;
 }
+/**
+ * Persist a probed embedding vector dimension into the config JSON file.
+ * Sets `embedding.vectorDimension` so subsequent startups skip the probe.
+ * This is a best-effort operation — failures are silently ignored.
+ *
+ * @param configPath - Absolute path to the config JSON file.
+ * @param dimension - The vector dimension to persist.
+ */
+export function persistProbedDimension(configPath, dimension) {
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf-8");
+    }
+    catch {
+        return;
+    }
+    try {
+        const obj = JSON.parse(raw);
+        const embedding = (obj.embedding ??= {});
+        if (embedding.vectorDimension === dimension)
+            return; // already set
+        embedding.vectorDimension = dimension;
+        writeFileSync(configPath, JSON.stringify(obj, null, 2), "utf-8");
+    }
+    catch {
+        // best-effort
+    }
+}
 //# sourceMappingURL=config.js.map

package/dist/core/desc-cache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Persistent description cache keyed by content hash + description config hash.
+ * Survives aborted index runs so that descriptions are not regenerated unnecessarily.
+ * Two namespaces: "code" (per-chunk descriptions) and "image" (per-file image descriptions).
+ */
+export declare class DescriptionCache {
+    private cache;
+    private cacheDir;
+    private dirty;
+    private savePromise;
+    private loadPromise;
+    constructor(cacheDir: string);
+    /** Load the cache from disk. */
+    load(): Promise<void>;
+    /** Get a cached description for the given key. */
+    get(key: string): string | undefined;
+    /** Set a cached description for the given key. */
+    set(key: string, description: string): void;
+    /** Set multiple entries at once. */
+    setMany(entries: Array<[string, string]>): void;
+    /** Check if a key exists in the cache. */
+    has(key: string): boolean;
+    /** Persist the cache to disk if dirty. Safe to call multiple times. */
+    save(): Promise<void>;
+    /** Build a cache key for a code chunk. */
+    static codeKey(content: string, descConfigHash: string): string;
+    /** Build a cache key for an image file. */
+    static imageKey(imageBytesHash: string, imageDescConfigHash: string): string;
+    /** Remove old entries to stay under the limit. */
+    private maybeEvict;
+}

package/dist/core/desc-cache.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Persistent description cache keyed by content hash + description config hash.
+ * Survives aborted index runs so that descriptions are not regenerated unnecessarily.
+ * Two namespaces: "code" (per-chunk descriptions) and "image" (per-file image descriptions).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+const CACHE_VERSION = 1;
+const MAX_ENTRIES = 50_000;
+const MAX_AGE_DAYS = 30;
+export class DescriptionCache {
+    cache = { version: CACHE_VERSION, entries: {} };
+    cacheDir;
+    dirty = false;
+    savePromise = Promise.resolve();
+    loadPromise = null;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir;
+    }
+    /** Load the cache from disk. */
+    async load() {
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.loadPromise = (async () => {
+            const cachePath = path.join(this.cacheDir, ".desc-cache.json");
+            try {
+                const raw = await fs.readFile(cachePath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed.version === CACHE_VERSION && parsed.entries) {
+                    this.cache = parsed;
+                    this.dirty = false;
+                }
+            }
+            catch {
+                // Cache file missing or corrupt — start fresh
+            }
+        })();
+        return this.loadPromise;
+    }
+    /** Get a cached description for the given key. */
+    get(key) {
+        return this.cache.entries[key]?.description;
+    }
+    /** Set a cached description for the given key. */
+    set(key, description) {
+        this.cache.entries[key] = {
+            description,
+            createdAt: Date.now(),
+        };
+        this.dirty = true;
+        this.maybeEvict();
+    }
+    /** Set multiple entries at once. */
+    setMany(entries) {
+        const now = Date.now();
+        for (const [key, description] of entries) {
+            this.cache.entries[key] = { description, createdAt: now };
+        }
+        this.dirty = true;
+        this.maybeEvict();
+    }
+    /** Check if a key exists in the cache. */
+    has(key) {
+        return key in this.cache.entries;
+    }
+    /** Persist the cache to disk if dirty. Safe to call multiple times. */
+    async save() {
+        if (!this.dirty)
+            return;
+        this.savePromise = this.savePromise.then(async () => {
+            const cachePath = path.join(this.cacheDir, ".desc-cache.json");
+            const tmpPath = cachePath + ".tmp";
+            try {
+                await fs.mkdir(this.cacheDir, { recursive: true });
+                await fs.writeFile(tmpPath, JSON.stringify(this.cache), "utf-8");
+                try {
+                    await fs.rename(tmpPath, cachePath);
+                }
+                catch {
+                    await fs.unlink(cachePath).catch(() => { });
+                    await fs.rename(tmpPath, cachePath);
+                }
+                this.dirty = false;
+            }
+            catch {
+                // Best-effort save
+            }
+        });
+        return this.savePromise;
+    }
+    /** Build a cache key for a code chunk. */
+    static codeKey(content, descConfigHash) {
+        const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        return contentHash + "_" + descConfigHash.slice(0, 16);
+    }
+    /** Build a cache key for an image file. */
+    static imageKey(imageBytesHash, imageDescConfigHash) {
+        return imageBytesHash.slice(0, 16) + "_" + imageDescConfigHash.slice(0, 16);
+    }
+    /** Remove old entries to stay under the limit. */
+    maybeEvict() {
+        const keys = Object.keys(this.cache.entries);
+        if (keys.length <= MAX_ENTRIES)
+            return;
+        const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+        const entries = this.cache.entries;
+        for (const key of keys) {
+            if (entries[key].createdAt < cutoff) {
+                delete entries[key];
+            }
+        }
+        // If still over limit, delete oldest
+        if (Object.keys(entries).length > MAX_ENTRIES) {
+            const sorted = Object.entries(entries)
+                .sort(([, a], [, b]) => a.createdAt - b.createdAt);
+            const toDelete = Object.keys(entries).length - MAX_ENTRIES;
+            for (let i = 0; i < toDelete; i++) {
+                delete entries[sorted[i][0]];
+            }
+        }
+    }
+}
+//# sourceMappingURL=desc-cache.js.map

package/dist/core/interfaces.d.ts

@@ -22,12 +22,26 @@ export interface DescriptionLogger {
     warn(message: string): void;
     debug(message: string): void;
 }
+/** Progress callback invoked after each chunk is described during batch generation. */
+export type ChunkProgressFn = (chunk: Chunk, completed: number, total: number) => void;
+/** Optional progress reporting for batch description generation. */
+export interface BatchDescriptionOptions {
+    /** Total number of chunks across the whole run (may exceed `chunks.length` when called per sub-batch). */
+    total?: number;
+    /** Called once per completed chunk with the chunk, the running completed count, and `total`. */
+    onProgress?: ChunkProgressFn;
+}
 /** Generates natural-language descriptions for code chunks using an LLM. */
 export interface DescriptionProvider {
     /** Generate a description for a single chunk. */
     generateDescription(chunk: Chunk): Promise<string>;
-    /** Generate descriptions for multiple chunks concurrently. Returns a Map of chunk ID to description. */
-    generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger): Promise<Map<string, string>>;
+    /**
+     * Generate descriptions for multiple chunks concurrently. Returns a Map of chunk ID to description.
+     * @param chunks - Chunks to describe.
+     * @param logger - Optional logger for diagnostic messages.
+     * @param opts - Optional progress reporting options.
+     */
+    generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
 }
 /** Explains how a search result score was computed, including vector and keyword contributions. */
 export interface SearchExplanation {
@@ -43,6 +57,10 @@ export interface SearchExplanation {
         rawKeywordScore: number;
         /** Weight applied to keyword score during fusion (0-1). */
         keywordWeight: number;
+        /** Rank (0-indexed) in the vector store results. */
+        vectorRank?: number;
+        /** Rank (0-indexed) in the keyword index results. */
+        keywordRank?: number;
     };
     /** Query terms that matched in the keyword index, if hybrid search was used. */
     matchedTerms?: string[];
@@ -86,12 +104,14 @@ export interface EmbeddingProvider {
 }
 /** In-memory TF-IDF inverted index for keyword-based search alongside vector search. */
 export interface KeywordIndex {
+    /** Release resources and free memory. */
+    close(): void;
     /** Index a set of chunks by tokenizing their content. */
     addChunks(chunks: Chunk[]): void;
     /** Remove all entries for a given file path from the index. */
     removeByFilePath(filePath: string): void;
     /** Search the index for the top-K matching chunks. */
-    search(query: string, topK: number): SearchResult[];
+    search(query: string, topK: number, filter?: MetadataFilter): SearchResult[];
     /** Get the terms from a query that matched a specific chunk. */
     getMatchedTerms(query: string, chunkId: string): string[];
     /** Clear all indexed data. */
@@ -101,20 +121,55 @@ export interface KeywordIndex {
     /** Persist the index to disk as JSON. */
     save(filePath?: string): Promise<void>;
 }
+/** A paginated chunk summary for dump/list operations. */
+export interface ChunkSummary {
+    id: string;
+    filePath: string;
+    language: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+    description: string;
+}
+/** A file summary for list operations. */
+export interface FileSummary {
+    filePath: string;
+    language: string;
+    chunkCount: number;
+}
 /** Persistent vector storage and retrieval backend (LanceDB or in-memory). */
 export interface VectorStore {
     /** Store a batch of chunks with their embeddings. */
     addChunks(chunks: Chunk[]): Promise<void>;
     /** Search for the top-K nearest neighbor chunks by embedding similarity. */
     search(embedding: number[], topK: number): Promise<SearchResult[]>;
+    /** Search with optional metadata filtering. */
+    searchWithFilter(embedding: number[], topK: number, filter?: MetadataFilter): Promise<SearchResult[]>;
     /** Return the total number of stored chunks. */
     count(): Promise<number>;
     /** Remove all stored data. */
     clear(): Promise<void>;
     /** Delete all chunks associated with a specific file path. */
     deleteByFilePath(filePath: string): Promise<void>;
+    /** Return all unique file paths currently stored in the index. */
+    getFilePaths(): Promise<string[]>;
     /** Release any held resources and close the store. */
     close(): Promise<void>;
+    /** Retrieve a paginated list of chunks without embeddings. */
+    getChunks(offset: number, limit: number): Promise<ChunkSummary[]>;
+    /** List all distinct file paths with language and chunk count. */
+    listFiles(): Promise<FileSummary[]>;
+    /** Retrieve all chunks for a specific file path, sorted by start line. */
+    getChunksByFilePath(filePath: string): Promise<Chunk[]>;
+    /** Re-open the store, optionally pointing at a new database path. */
+    reopen?(newPath?: string): Promise<void>;
+}
+/** Filter criteria for narrowing search results by file path patterns or language. */
+export interface MetadataFilter {
+    /** Glob-style path patterns (e.g. "src/**", "lib/auth/*"). */
+    pathPatterns?: string[];
+    /** Language identifiers (e.g. ["typescript", "tsx"]). */
+    languages?: string[];
 }
 /** Callback interface for reporting indexing progress to the UI or CLI. */
 export interface IndexProgress {

package/dist/core/manifest.d.ts

@@ -2,6 +2,7 @@
  * @fileoverview File hash manifest for tracking indexing state across sessions.
  * Provides load/save with atomic writes, schema versioning, and corruption detection.
  */
+import type { RagConfig } from "./config.js";
 /** Metadata entry for a single indexed file. */
 export interface ManifestEntry {
     /** SHA-256 hash of the file content. */
@@ -16,9 +17,22 @@ export interface ManifestEntry {
     size?: number;
     /** Whether the description generation step failed for this file. */
     descriptionFailed?: boolean;
+    /**
+     * Hash of the description config (provider, model, baseUrl, prompts) that
+     * was active when descriptions were generated for this file.  Skipped when
+     * no description provider is configured.  Used to avoid re-describing
+     * files whose source content and description config are both unchanged.
+     */
+    descHash?: string;
 }
 /** Current schema version for manifest files. */
-export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_VERSION = 3;
+/**
+ * Oldest schema version still accepted as valid.
+ * Bumping this intentionally marks older manifests corrupt and forces a
+ * rebuild, so only raise it when a migration is not practical.
+ */
+export declare const MIN_SUPPORTED_SCHEMA_VERSION = 3;
 /** Persistent manifest tracking indexing state across sessions. */
 export interface FileManifest {
     /** Unix timestamp of the last full index pass. */
@@ -49,6 +63,15 @@ export declare function manifestPathFor(dbPath: string): string;
 export declare function normalizeFilePath(filePath: string): string;
 /** Compute the SHA-256 hex hash of a string. */
 export declare function computeFileHash(content: string): string;
+/**
+ * Compute a hash of the description configuration (provider, model, baseUrl,
+ * systemPrompt, image prompt, etc.) so that files are only re-described when
+ * the config actually changes.
+ *
+ * Returns `undefined` when neither `description` nor `imageDescription` is
+ * configured — callers treat this as "no descriptions needed".
+ */
+export declare function computeDescriptionConfigHash(config: RagConfig): string | undefined;
 /** Load a manifest from disk, handling missing or corrupt files gracefully. */
 export declare function loadManifest(dbPath: string): Promise<LoadedManifest>;
 /** Persist a manifest to disk with atomic write (temp file + rename, with Windows fallback). */

package/dist/core/manifest.js

@@ -6,7 +6,13 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 /** Current schema version for manifest files. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 3;
+/**
+ * Oldest schema version still accepted as valid.
+ * Bumping this intentionally marks older manifests corrupt and forces a
+ * rebuild, so only raise it when a migration is not practical.
+ */
+export const MIN_SUPPORTED_SCHEMA_VERSION = 3;
 /** Create a new empty manifest with the current schema version. */
 export function createEmptyManifest() {
     return { files: {}, schemaVersion: SCHEMA_VERSION };
@@ -23,6 +29,30 @@ export function normalizeFilePath(filePath) {
 export function computeFileHash(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+/**
+ * Compute a hash of the description configuration (provider, model, baseUrl,
+ * systemPrompt, image prompt, etc.) so that files are only re-described when
+ * the config actually changes.
+ *
+ * Returns `undefined` when neither `description` nor `imageDescription` is
+ * configured — callers treat this as "no descriptions needed".
+ */
+export function computeDescriptionConfigHash(config) {
+    const desc = config.description;
+    const img = config.imageDescription;
+    if (!desc && !img)
+        return undefined;
+    const parts = [];
+    if (desc) {
+        parts.push(`desc:${desc.provider}|${desc.model}|${desc.baseUrl}|${desc.systemPrompt}`);
+    }
+    if (img) {
+        parts.push(`img:${img.provider}|${img.model}|${img.baseUrl}|${img.prompt}`);
+    }
+    if (parts.length === 0)
+        return undefined;
+    return createHash("sha256").update(parts.join("||")).digest("hex").slice(0, 16);
+}
 /** Load a manifest from disk, handling missing or corrupt files gracefully. */
 export async function loadManifest(dbPath) {
     const filePath = manifestPathFor(dbPath);
@@ -32,14 +62,15 @@ export async function loadManifest(dbPath) {
         if (!parsed || typeof parsed !== "object" || !parsed.files || typeof parsed.files !== "object") {
             return { manifest: createEmptyManifest(), path: filePath, status: "corrupt" };
         }
+        const version = parsed.schemaVersion ?? 0;
         return {
             manifest: {
                 lastIndexedAt: typeof parsed.lastIndexedAt === "number" ? parsed.lastIndexedAt : undefined,
-                schemaVersion: parsed.schemaVersion,
+                schemaVersion: version,
                 files: parsed.files,
             },
             path: filePath,
-            status: parsed.schemaVersion === SCHEMA_VERSION ? "ok" : "corrupt",
+            status: version >= MIN_SUPPORTED_SCHEMA_VERSION ? "ok" : "corrupt",
         };
     }
     catch (error) {

package/dist/core/resolve-api-key.js

@@ -41,7 +41,7 @@ function resolveForSection(provider, section, worktree) {
     // so createEmbedder can throw a clear error about the missing key
 }
 function stripJsoncComments(text) {
-    return text.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    return text.replace(/("[^"\\]*(?:\\.[^"\\]*)*")|(\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g, (_, string) => string ?? "");
 }
 function readOpenCodeProviderKey(worktree, providerId) {
     const locations = [
@@ -57,7 +57,9 @@ function readOpenCodeProviderKey(worktree, providerId) {
             if (!existsSync(loc))
                 continue;
             const raw = readFileSync(loc, "utf-8");
-            const cleaned = stripJsoncComments(raw);
+            // Only strip JSONC comments from .jsonc files; plain JSON may contain
+            // "https://" URLs that look like line-comment markers after "//".
+            const cleaned = loc.endsWith(".jsonc") ? stripJsoncComments(raw) : raw;
             const config = JSON.parse(cleaned);
             const providerSection = config.provider;
             if (!providerSection)

package/dist/core/runtime-overrides.js

@@ -80,41 +80,43 @@ export function applyRuntimeOverrides(cfg, overrides) {
             merged.embedding.baseUrl = overrides.embedding.baseUrl;
     }
     if (overrides.description) {
+        const defaultDesc = DEFAULT_CONFIG.description;
         if (overrides.description.enabled !== undefined) {
             if (!merged.description)
-                merged.description = { enabled: true, provider: "ollama", baseUrl: "http://127.0.0.1:11434/api", model: "qwen2.5:3b", systemPrompt: "" };
+                merged.description = { ...defaultDesc };
             merged.description.enabled = overrides.description.enabled;
         }
         if (overrides.description.provider !== undefined) {
             if (!merged.description)
-                merged.description = { enabled: true, provider: "ollama", baseUrl: "http://127.0.0.1:11434/api", model: "qwen2.5:3b", systemPrompt: "" };
+                merged.description = { ...defaultDesc };
             merged.description.provider = overrides.description.provider;
         }
         if (overrides.description.model !== undefined) {
             if (!merged.description)
-                merged.description = { enabled: true, provider: "ollama", baseUrl: "http://127.0.0.1:11434/api", model: "qwen2.5:3b", systemPrompt: "" };
+                merged.description = { ...defaultDesc };
             merged.description.model = overrides.description.model;
         }
         if (overrides.description.baseUrl !== undefined) {
             if (!merged.description)
-                merged.description = { enabled: true, provider: "ollama", baseUrl: "http://127.0.0.1:11434/api", model: "qwen2.5:3b", systemPrompt: "" };
+                merged.description = { ...defaultDesc };
             merged.description.baseUrl = overrides.description.baseUrl;
         }
     }
     if (overrides.imageDescription) {
+        const defaultImg = DEFAULT_CONFIG.imageDescription;
         if (overrides.imageDescription.enabled !== undefined) {
             if (!merged.imageDescription)
-                merged.imageDescription = { enabled: false, provider: "ollama", model: "llama3.2-vision", baseUrl: "http://127.0.0.1:11434/api", timeoutMs: 60000, prompt: "" };
+                merged.imageDescription = { ...defaultImg };
             merged.imageDescription.enabled = overrides.imageDescription.enabled;
         }
         if (overrides.imageDescription.provider !== undefined) {
             if (!merged.imageDescription)
-                merged.imageDescription = { enabled: false, provider: "ollama", model: "llama3.2-vision", baseUrl: "http://127.0.0.1:11434/api", timeoutMs: 60000, prompt: "" };
+                merged.imageDescription = { ...defaultImg };
             merged.imageDescription.provider = overrides.imageDescription.provider;
         }
         if (overrides.imageDescription.model !== undefined) {
             if (!merged.imageDescription)
-                merged.imageDescription = { enabled: false, provider: "ollama", model: "llama3.2-vision", baseUrl: "http://127.0.0.1:11434/api", timeoutMs: 60000, prompt: "" };
+                merged.imageDescription = { ...defaultImg };
             merged.imageDescription.model = overrides.imageDescription.model;
         }
     }

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

@@ -0,0 +1,23 @@
+export interface SetupResult {
+    success: boolean;
+    errors: string[];
+}
+export declare function getRuntimeDir(): string;
+export declare function getNpmGlobalRoot(): string;
+export declare function getVersionFile(runtimeDir: string): string;
+export declare function readVersionFile(versionFile: string): string | null;
+/**
+ * npm-generated .cmd / .ps1 wrappers on Windows invoke `.js` files directly
+ * via file association. If the `.js` association points to a text editor
+ * (e.g. Notepad++) instead of Node.js, the CLI opens the editor instead of
+ * running. This function patches the wrappers to call `node` explicitly.
+ *
+ * Runs only on Windows. Safe to call on every setup — detects already-patched
+ * wrappers by checking for the `node` prefix.
+ */
+export declare function patchWindowsWrappers(npmGlobalRoot: string): void;
+export declare function setupRuntime(options?: {
+    force?: boolean;
+    silent?: boolean;
+    version?: string;
+}): Promise<SetupResult>;