opencode-rag-plugin 1.15.1 → 1.17.0

package/ReadMe.md

@@ -11,12 +11,8 @@ You don't need a dedicated GPU to run smaller embedding LLMs, as these models ca
 ## Quick Start
 
 ```bash
-# 1. Clone and install
-git clone https://github.com/MrDoe/OpenCodeRAG.git
-cd OpenCodeRAG
-npm install --legacy-peer-deps
-npm run build
-./install.sh
+# 1. Install globally (automatically sets up the OpenCode runtime)
+npm install -g opencode-rag-plugin
 
 # 2. Initialize in your project
 cd /path/to/your/project
@@ -31,6 +27,8 @@ opencode-rag query "authentication middleware"
 
 **Prerequisites:** Node.js v22+, [Ollama](https://ollama.ai) (default) or other LLM-hosters (OpenAI-, Google- or Anthropic-compatible).
 
+> **Contributors / developers:** Clone the repo and use `npm install --legacy-peer-deps; npm run build` — see [Development docs](doc/development.md).
+
 ## Key Features
 
 | Feature | Description |

package/dist/api.js

@@ -7,6 +7,7 @@ import { retrieve } from "./retriever/retriever.js";
 import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
 import { runIndexPass } from "./indexer.js";
 import { scanWorkspaceFiles } from "./content/reader.js";
+import { destroyAllPooledConnections } from "./embedder/http.js";
 /**
  * Format a list of search results into a human-readable markdown block.
  * Each result is rendered as a code block with metadata header.
@@ -41,17 +42,29 @@ export async function search(query, options = {}) {
         cwd: options.cwd,
         configPath: options.configPath,
     });
-    const topK = options.topK ?? ctx.config.retrieval.topK;
-    const rawResults = await retrieve(query, ctx.embedder, ctx.store, {
-        topK,
-        minScore: options.minScore ?? ctx.config.retrieval.minScore,
-        keywordIndex: ctx.keywordIndex,
-        keywordWeight: options.keywordWeight ?? ctx.config.retrieval.hybridSearch?.keywordWeight ?? 0.4,
-        queryPrefix: ctx.config.embedding.queryPrefix,
-        explain: options.explain,
-    });
-    const optCfg = ctx.config.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;
-    return optimizeContext(rawResults, { topK, config: optCfg });
+    try {
+        const topK = options.topK ?? ctx.config.retrieval.topK;
+        const rawResults = await retrieve(query, ctx.embedder, ctx.store, {
+            topK,
+            minScore: options.minScore ?? ctx.config.retrieval.minScore,
+            keywordIndex: ctx.keywordIndex,
+            keywordWeight: options.keywordWeight ?? ctx.config.retrieval.hybridSearch?.keywordWeight ?? 0.4,
+            hybridEnabled: ctx.config.retrieval.hybridSearch?.enabled,
+            queryPrefix: ctx.config.embedding.queryPrefix,
+            explain: options.explain,
+            filter: {
+                pathPatterns: options.pathHints,
+                languages: options.languageHints,
+            },
+        });
+        const optCfg = ctx.config.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;
+        return optimizeContext(rawResults, { topK, config: optCfg });
+    }
+    finally {
+        await ctx.store.close();
+        ctx.keywordIndex.close();
+        destroyAllPooledConnections();
+    }
 }
 /**
  * Index (or re-index) the workspace files into the vector store.
@@ -67,20 +80,27 @@ export async function indexWorkspace(cwd, options = {}) {
         cwd: workDir,
         configPath: options.configPath,
     });
-    if (options.onProgress) {
-        options.onProgress(`Indexing ${workDir}...`);
+    try {
+        if (options.onProgress) {
+            options.onProgress(`Indexing ${workDir}...`);
+        }
+        const stats = await runIndexPass({
+            cwd: workDir,
+            storePath: ctx.storePath,
+            config: ctx.config,
+            store: ctx.store,
+            embedder: ctx.embedder,
+            force: options.force ?? false,
+            keywordIndex: ctx.keywordIndex,
+            descriptionProvider: ctx.descriptionProvider,
+        });
+        return stats;
+    }
+    finally {
+        await ctx.store.close();
+        ctx.keywordIndex.close();
+        destroyAllPooledConnections();
     }
-    const stats = await runIndexPass({
-        cwd: workDir,
-        storePath: ctx.storePath,
-        config: ctx.config,
-        store: ctx.store,
-        embedder: ctx.embedder,
-        force: options.force ?? false,
-        keywordIndex: ctx.keywordIndex,
-        descriptionProvider: ctx.descriptionProvider,
-    });
-    return stats;
 }
 /**
  * Retrieve and format context chunks for a query in one call.

package/dist/chunker/base.d.ts

@@ -5,10 +5,41 @@ export declare abstract class TreeSitterChunker implements Chunker {
     abstract readonly fileExtensions: string[];
     abstract readonly grammarName: string;
     abstract readonly nodeTypes: Set<string>;
+    /**
+     * Optional path to a custom WebAssembly file for the tree-sitter grammar.
+     * If not provided, the default grammar will be loaded.
+     * @default undefined
+     */
     readonly wasmFilePath?: string;
-    private parser;
-    private parserPromise;
+    /**
+     * Maximum content length in bytes before chunking is skipped.
+     * Tree-sitter can hang on very large files (especially SVGs).
+     * Set to 0 or negative for no limit.
+     * @default 0 (no limit)
+     */
+    maxContentBytes: number;
+    /**
+     * Create a new chunker that only includes nodes of the specified types.
+     * @param types - The set of node types to include in the chunking process.
+     * @returns A new Chunker instance that filters nodes by the specified types.
+     */
     withNodeTypes(types: Set<string>): Chunker;
-    private getParser;
+    /**
+     * Returns a cached Tree-sitter parser for the chunker's language.
+     * Parsers are created once per grammar and reused across chunk() calls.
+     * @returns A Promise that resolves to a Parser instance.
+     */
+    private _createParser;
+    /**
+     * Release all cached parsers for this chunker's language.
+     * Call when the chunker is no longer needed.
+     */
+    dispose(): void;
+    /**
+     * Chunks the given content into an array of {@link Chunk} objects based on the specified node types.
+     * @param filePath - The path of the file being chunked, used for metadata.
+     * @param content - The content of the file to be chunked.
+     * @returns A Promise that resolves to an array of {@link Chunk} objects.
+     */
     chunk(filePath: string, content: string): Promise<Chunk[]>;
 }

package/dist/chunker/base.js

@@ -4,11 +4,31 @@
 import { Parser } from "web-tree-sitter";
 import { loadLanguage, loadLanguageFromPath, walkTree } from "./grammar.js";
 import { uuid } from "./uuid.js";
+/** Module-level parser pool shared across all TreeSitterChunker instances. */
+const parserPool = new Map();
+function poolKey(grammarName, wasmFilePath) {
+    return wasmFilePath ? `${grammarName}::${wasmFilePath}` : grammarName;
+}
 /** Abstract base for tree-sitter based language chunkers. */
 export class TreeSitterChunker {
+    /**
+     * Optional path to a custom WebAssembly file for the tree-sitter grammar.
+     * If not provided, the default grammar will be loaded.
+     * @default undefined
+     */
     wasmFilePath;
-    parser = null;
-    parserPromise;
+    /**
+     * Maximum content length in bytes before chunking is skipped.
+     * Tree-sitter can hang on very large files (especially SVGs).
+     * Set to 0 or negative for no limit.
+     * @default 0 (no limit)
+     */
+    maxContentBytes = 0;
+    /**
+     * Create a new chunker that only includes nodes of the specified types.
+     * @param types - The set of node types to include in the chunking process.
+     * @returns A new Chunker instance that filters nodes by the specified types.
+     */
     withNodeTypes(types) {
         const original = this;
         return {
@@ -17,11 +37,16 @@ export class TreeSitterChunker {
             async chunk(filePath, content) {
                 if (content.trim().length === 0)
                     return [];
-                const parser = await original.getParser();
+                if (original.maxContentBytes > 0 && Buffer.byteLength(content, "utf-8") > original.maxContentBytes) {
+                    throw new Error(`File exceeds ${original.maxContentBytes} byte limit for ${original.language} chunker`);
+                }
+                const parser = await original._createParser();
                 const tree = parser.parse(content);
-                if (!tree)
+                if (!tree) {
                     return [];
+                }
                 const nodes = walkTree(tree.rootNode, types, content);
+                tree.delete();
                 return nodes.map((node) => ({
                     id: uuid(),
                     content: node.text,
@@ -36,31 +61,55 @@ export class TreeSitterChunker {
             },
         };
     }
-    getParser() {
-        if (this.parser)
-            return Promise.resolve(this.parser);
-        if (!this.parserPromise) {
-            this.parserPromise = (async () => {
-                const lang = this.wasmFilePath
-                    ? await loadLanguageFromPath(this.grammarName, this.wasmFilePath)
-                    : await loadLanguage(this.grammarName);
-                const parser = new Parser();
-                parser.setLanguage(lang);
-                this.parser = parser;
-                this.parserPromise = undefined;
-                return parser;
-            })();
+    /**
+     * Returns a cached Tree-sitter parser for the chunker's language.
+     * Parsers are created once per grammar and reused across chunk() calls.
+     * @returns A Promise that resolves to a Parser instance.
+     */
+    async _createParser() {
+        const key = poolKey(this.grammarName, this.wasmFilePath);
+        const cached = parserPool.get(key);
+        if (cached)
+            return cached;
+        const lang = this.wasmFilePath
+            ? await loadLanguageFromPath(this.grammarName, this.wasmFilePath)
+            : await loadLanguage(this.grammarName);
+        const parser = new Parser();
+        parser.setLanguage(lang);
+        parserPool.set(key, parser);
+        return parser;
+    }
+    /**
+     * Release all cached parsers for this chunker's language.
+     * Call when the chunker is no longer needed.
+     */
+    dispose() {
+        const key = poolKey(this.grammarName, this.wasmFilePath);
+        const parser = parserPool.get(key);
+        if (parser) {
+            parser.delete();
+            parserPool.delete(key);
         }
-        return this.parserPromise;
     }
+    /**
+     * Chunks the given content into an array of {@link Chunk} objects based on the specified node types.
+     * @param filePath - The path of the file being chunked, used for metadata.
+     * @param content - The content of the file to be chunked.
+     * @returns A Promise that resolves to an array of {@link Chunk} objects.
+     */
     async chunk(filePath, content) {
         if (content.trim().length === 0)
             return [];
-        const parser = await this.getParser();
+        if (this.maxContentBytes > 0 && Buffer.byteLength(content, "utf-8") > this.maxContentBytes) {
+            throw new Error(`File exceeds ${this.maxContentBytes} byte limit for ${this.language} chunker`);
+        }
+        const parser = await this._createParser();
         const tree = parser.parse(content);
-        if (!tree)
+        if (!tree) {
             return [];
+        }
         const nodes = walkTree(tree.rootNode, this.nodeTypes, content);
+        tree.delete();
         return nodes.map((node) => ({
             id: uuid(),
             content: node.text,

package/dist/chunker/factory.d.ts

@@ -59,7 +59,10 @@ export declare function getRegisteredExtensions(): string[];
  * @param content - The full text content of the file.
  * @param nodeTypesOverrides - Optional language-specific node type overrides
  *   for tree-sitter based chunkers.
+ * @param options - Optional chunking options (maxSvgSizeBytes, etc.).
  * @returns An array of chunks for the file.
  */
-export declare function chunkFile(filePath: string, content: string, nodeTypesOverrides?: Record<string, string[]>): Promise<Chunk[]>;
+export declare function chunkFile(filePath: string, content: string, nodeTypesOverrides?: Record<string, string[]>, options?: {
+    maxSvgSizeBytes?: number;
+}): Promise<Chunk[]>;
 export { typescriptChunker, pythonChunker, javaChunker, goChunker, markdownChunker, cChunker, cppChunker, csharpChunker, javascriptChunker, razorChunker, jsonChunker, htmlChunker, cssChunker, xmlChunker, slnChunker, rustChunker, rubyChunker, kotlinChunker, swiftChunker, bashChunker, phpChunker, powershellChunker, iniChunker, yamlChunker, tomlChunker, dockerfileChunker, sqlChunker, texChunker, pdfChunker, fallbackChunker };

package/dist/chunker/factory.js

@@ -174,6 +174,15 @@ 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;
+        }
+    }
+}
 /**
  * Chunk a file by looking up its registered chunker, applying node-type
  * overrides if provided, and splitting oversized chunks to stay within
@@ -183,9 +192,10 @@ function splitOversized(chunks, filePath) {
  * @param content - The full text content of the file.
  * @param nodeTypesOverrides - Optional language-specific node type overrides
  *   for tree-sitter based chunkers.
+ * @param options - Optional chunking options (maxSvgSizeBytes, etc.).
  * @returns An array of chunks for the file.
  */
-export async function chunkFile(filePath, content, nodeTypesOverrides) {
+export async function chunkFile(filePath, content, nodeTypesOverrides, options) {
     let chunker = getChunker(filePath);
     if (nodeTypesOverrides && chunker instanceof TreeSitterChunker) {
         const overrideTypes = nodeTypesOverrides[chunker.language];
@@ -193,6 +203,7 @@ export async function chunkFile(filePath, content, nodeTypesOverrides) {
             chunker = chunker.withNodeTypes(new Set(overrideTypes));
         }
     }
+    applyChunkerConfig(chunker, filePath, options);
     const chunks = await chunker.chunk(filePath, content);
     if (chunks.length === 0) {
         return fallbackChunker.chunk(filePath, content);

package/dist/chunker/grammar.js

@@ -63,6 +63,9 @@ export async function initParser() {
     initPromise = Parser.init().then(() => {
         initialized = true;
         initPromise = null;
+    }).catch((err) => {
+        initPromise = null;
+        throw err;
     });
     return initPromise;
 }

package/dist/chunker/image.js

@@ -51,7 +51,7 @@ class OllamaImageVisionProvider {
         this.numCtx = config.numCtx;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, _mimeType, prompt, _abort) {
+    async describeImage(imageBase64, _mimeType, prompt, abort) {
         const body = {
             model: this.model,
             messages: [
@@ -67,7 +67,7 @@ class OllamaImageVisionProvider {
         };
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
-            const response = await postJson(`${this.baseUrl}/chat`, body, {}, this.timeoutMs, this.proxy);
+            const response = await postJson(`${this.baseUrl}/chat`, body, {}, this.timeoutMs, this.proxy, abort);
             if (!response.ok) {
                 const text = await response.text();
                 const error = new Error(`Ollama vision request failed (${response.status}): ${text}`);
@@ -109,7 +109,7 @@ class OpenAIImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, _abort) {
+    async describeImage(imageBase64, mimeType, prompt, abort) {
         const url = `${this.baseUrl}${this.baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
         const body = {
             model: this.model,
@@ -135,7 +135,7 @@ class OpenAIImageVisionProvider {
         }
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
-            const response = await postJson(url, body, headers, this.timeoutMs, this.proxy);
+            const response = await postJson(url, body, headers, this.timeoutMs, this.proxy, abort);
             if (!response.ok) {
                 const text = await response.text();
                 const error = new Error(`OpenAI vision request failed (${response.status}): ${text}`);
@@ -177,7 +177,7 @@ class AnthropicImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, _abort) {
+    async describeImage(imageBase64, mimeType, prompt, abort) {
         const body = {
             model: this.model,
             max_tokens: 2048,
@@ -201,7 +201,7 @@ class AnthropicImageVisionProvider {
         };
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
-            const response = await postJson(`${this.baseUrl}/messages`, body, headers, this.timeoutMs, this.proxy);
+            const response = await postJson(`${this.baseUrl}/messages`, body, headers, this.timeoutMs, this.proxy, abort);
             if (!response.ok) {
                 const text = await response.text();
                 const error = new Error(`Anthropic vision request failed (${response.status}): ${text}`);
@@ -243,7 +243,7 @@ class GeminiImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, _abort) {
+    async describeImage(imageBase64, mimeType, prompt, abort) {
         const body = {
             contents: [
                 {
@@ -268,7 +268,7 @@ class GeminiImageVisionProvider {
             : `${this.baseUrl}/models/${this.model}:generateContent`;
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
-            const response = await postJson(url, body, headers, this.timeoutMs, this.proxy);
+            const response = await postJson(url, body, headers, this.timeoutMs, this.proxy, abort);
             if (!response.ok) {
                 const text = await response.text();
                 const error = new Error(`Gemini vision request failed (${response.status}): ${text}`);

package/dist/chunker/pdf.js

@@ -4,6 +4,8 @@ import { pathToFileURL } from "node:url";
 import path from "node:path";
 const MAX_CHUNK_CHARS = 4000;
 const MIN_GROUP_CHARS = 300;
+const MAX_PDF_PAGES = 1000;
+const MAX_PDF_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB
 const PARAGRAPH_SPLIT = /\n\s*\n/;
 /**
  * Resolve the file URL to the `standard_fonts` directory shipped with pdfjs-dist.
@@ -18,22 +20,14 @@ function getStandardFontsUrl() {
 }
 /**
  * Create a pdfjs-dist PDF document from a buffer.
- * Attempts to load the `canvas` native module for DOMMatrix; falls back to
- * `@thednp/dommatrix` polyfill if unavailable.
+ * 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.
  */
 async function createPdfDocument(buffer) {
-    try {
-        const { DOMMatrix } = await import("canvas");
-        globalThis.DOMMatrix ??= DOMMatrix;
-        globalThis.DOMMatrixReadOnly ??= DOMMatrix;
-    }
-    catch {
-        const { default: CSSMatrix } = await import("@thednp/dommatrix");
-        globalThis.DOMMatrix ??= CSSMatrix;
-        globalThis.DOMMatrixReadOnly ??= CSSMatrix;
-    }
+    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({
         data: new Uint8Array(buffer),
@@ -50,9 +44,13 @@ async function createPdfDocument(buffer) {
  * @returns The extracted text with double-newline page separators.
  */
 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 = [];
-    for (let i = 1; i <= pdf.numPages; i++) {
+    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);

package/dist/chunker/xml.d.ts

@@ -11,6 +11,8 @@ export declare class XmlChunker extends TreeSitterChunker {
     readonly fileExtensions: string[];
     readonly grammarName = "xml";
     readonly nodeTypes: Set<string>;
+    /** Limit to prevent tree-sitter from hanging on large SVG/XML files. */
+    maxContentBytes: number;
 }
 /** Default singleton instance of {@link XmlChunker}. */
 export declare const xmlChunker: XmlChunker;

package/dist/chunker/xml.js

@@ -13,6 +13,8 @@ export class XmlChunker extends TreeSitterChunker {
     nodeTypes = new Set([
         "element",
     ]);
+    /** Limit to prevent tree-sitter from hanging on large SVG/XML files. */
+    maxContentBytes = 1_048_576;
 }
 /** Default singleton instance of {@link XmlChunker}. */
 export const xmlChunker = new XmlChunker();

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

@@ -14,7 +14,6 @@ import chokidar from "chokidar";
 import { appendDebugLog } from "../../core/fileLogger.js";
 import { createWatchPassScheduler, createWatchIgnore, runIndexPass, } from "../../indexer.js";
 import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, logIndexSummary, formatDuration, } from "../format.js";
-import { TerminalProgressTable } from "../progress.js";
 /**
  * Build a logger that suppresses console output when watchTriggered is true.
  */
@@ -98,7 +97,6 @@ export function registerIndexCommand(program) {
                 }
             }
             logCliInfo(logFilePath, "index", `${c.label("Scanning:")} ${c.file(cwd)}`);
-            const progress = new TerminalProgressTable(process.stdout);
             const runPass = async (watchTriggered = false, abortSignal, filterPaths) => {
                 const passStarted = Date.now();
                 const stats = await runIndexPass({
@@ -109,14 +107,12 @@ export function registerIndexCommand(program) {
                     embedder,
                     keywordIndex,
                     descriptionProvider,
-                    progress,
                     force: !!(options.force && !watchTriggered),
                     abortSignal,
                     dimension,
                     filterPaths,
                     logger: watchAwareLogger(logFilePath, watchTriggered ? "watch" : "index", watchTriggered),
                 });
-                progress.done();
                 if (!watchTriggered) {
                     logIndexSummary(logFilePath, stats);
                     logCliInfo(logFilePath, "index", `\n${c.success("Indexing complete.")} ${c.num(stats.finalCount)} chunks stored (${formatDuration(Date.now() - passStarted)}).`);

package/dist/cli/commands/index.d.ts

@@ -11,6 +11,6 @@ export { registerDumpCommand } from "./dump.js";
 export { registerInitCommand } from "./init.js";
 export { registerUiCommand } from "./ui.js";
 export { registerMcpCommand } from "./mcp.js";
-export { registerUpdateCommand } from "./update.js";
+export { registerSetupCommand } from "./setup.js";
 export { registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand } from "./eval.js";
 export { registerDescribeImageCommand } from "./describe-image.js";

package/dist/cli/commands/index.js

@@ -11,7 +11,7 @@ export { registerDumpCommand } from "./dump.js";
 export { registerInitCommand } from "./init.js";
 export { registerUiCommand } from "./ui.js";
 export { registerMcpCommand } from "./mcp.js";
-export { registerUpdateCommand } from "./update.js";
+export { registerSetupCommand } from "./setup.js";
 export { registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand } from "./eval.js";
 export { registerDescribeImageCommand } from "./describe-image.js";
 //# sourceMappingURL=index.js.map

package/dist/cli/commands/init-helpers.d.ts

@@ -74,6 +74,18 @@ export declare function generateSkillFile(): string;
  * @returns The merged `.gitignore` content with a trailing newline.
  */
 export declare function mergeGitignoreContent(existingContent?: string): string;
+/**
+ * Merge the OpenCodeRAG directive section into an existing `AGENTS.md`.
+ *
+ * The directive is wrapped in sentinel markers so re-runs replace the
+ * section in place rather than appending duplicates. Existing content
+ * outside the markers is always preserved. If no existing content is
+ * provided, the section alone is returned as a new file.
+ *
+ * @param existingContent - The current `AGENTS.md` content, or `undefined` if absent.
+ * @returns The merged `AGENTS.md` content with a trailing newline.
+ */
+export declare function mergeAgentsMdContent(existingContent?: string): string;
 /**
  * Get the runtime directory path (`~/.opencode`).
  *