opencode-rag-plugin 2.9.3 → 2.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ReadMe.md +27 -2
- package/dist/cli/commands/init-helpers.js +7 -0
- package/dist/cli/commands/init.js +7 -4
- package/dist/core/bootstrap.js +13 -10
- package/dist/core/config.d.ts +99 -1
- package/dist/core/config.js +148 -5
- package/dist/embedder/health.d.ts +8 -2
- package/dist/embedder/health.js +12 -5
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/indexer/pipeline.d.ts +26 -0
- package/dist/indexer/pipeline.js +59 -11
- package/dist/plugin.d.ts +14 -9
- package/dist/plugin.js +50 -28
- package/dist/safety/shell-guard.d.ts +157 -0
- package/dist/safety/shell-guard.js +412 -0
- package/dist/tui.js +24 -20
- package/dist/v2/v2-adapter.d.ts +49 -3
- package/dist/v2/v2-adapter.js +63 -7
- package/dist/vectorstore/lancedb.d.ts +25 -2
- package/dist/vectorstore/lancedb.js +180 -15
- package/package.json +1 -1
package/ReadMe.md
CHANGED
|
@@ -50,6 +50,7 @@ workspace, and `opencode-rag update` upgrades to a newer release.
|
|
|
50
50
|
| **Hybrid search** | Vector similarity + TF×IDF keyword fusion — the keyword index is repaired from the store whenever it drifts behind it, so the BM25 half never covers only part of the corpus |
|
|
51
51
|
| **Retrieval calibration** | `opencode-rag eval:tune` sweeps the fusion weights against the labelled golden set and reports (or writes) the best configuration for your embedder and corpus |
|
|
52
52
|
| **Decision model** | Local [tev1](https://ollama.com/library/tev1) classification — `make_decision` labels, routes, and scores short text with probabilities (40–150 ms warm); optional pre-ask routing so the agent asks fewer questions |
|
|
53
|
+
| **Shell guard** | Optional pre-execution vetting of every `shell`/`bash` command by the local decision model — flagged commands ask for confirmation, clean ones run normally (fail-open by default) |
|
|
53
54
|
| **OpenCode plugin** | Auto-inject context, read-tool override, TUI settings, Ctrl+Enter to add RAG context, MCP registration on `init` |
|
|
54
55
|
| **Incremental indexing** | File-hash manifest, background watcher, auto-rebuild on corruption |
|
|
55
56
|
| **Privacy-first** | All processing stays local (when using Ollama) |
|
|
@@ -77,7 +78,7 @@ Launch with `opencode-rag ui`. See [Web UI documentation](doc/webui.md) for deta
|
|
|
77
78
|
|---|---|
|
|
78
79
|
| [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
|
|
79
80
|
| [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
|
|
80
|
-
| [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, plugin |
|
|
81
|
+
| [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, shell guard, plugin |
|
|
81
82
|
| [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
|
|
82
83
|
| [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
|
|
83
84
|
| [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
|
|
@@ -146,6 +147,30 @@ ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
|
|
|
146
147
|
|
|
147
148
|
`opencode-rag decide` exposes the same engine from the CLI, and `init` creates a dedicated `make-decision` agent skill. See [Plugin documentation](doc/plugin.md#make_decision) and [Configuration](doc/configuration.md#decision).
|
|
148
149
|
|
|
150
|
+
## Shell Guard (Optional)
|
|
151
|
+
|
|
152
|
+
The same local decision model can vet **every shell command before it runs**. With `shellGuard.enabled: true`, each `shell`/`bash` call is classified for destructive and malicious intent; a command whose `p(destructive)` or `p(malicious)` reaches the threshold is escalated to OpenCode's confirmation prompt with the full verdict — otherwise it executes unchanged.
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"shellGuard": {
|
|
157
|
+
"enabled": true,
|
|
158
|
+
"threshold": 0.5,
|
|
159
|
+
"timeoutMs": 10000,
|
|
160
|
+
"onError": "allow"
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- **Off by default** — enabling adds one local model call to the critical path of every shell command.
|
|
166
|
+
- **Machine-wide** — put the block in `~/.config/opencode/opencode-rag.json` (the global layer, see [Configuration](doc/configuration.md#config-file-discovery)) and every workspace inherits it; a workspace config can still override or disable it.
|
|
167
|
+
- **Fail-open by default** (`onError: "allow"`): if the classifier is down or times out, the command runs and a warning is logged. Set `onError: "ask"` to require confirmation instead.
|
|
168
|
+
- **Verdict cache** (10 min, 256 entries): repeated identical commands are answered instantly; the key includes the provider/model, so switching models invalidates it, and cached probabilities are re-scored against the current threshold on every call.
|
|
169
|
+
- **Config edits apply without a restart** — the guard re-reads `opencode-rag.json` when it changes.
|
|
170
|
+
- **Backend** defaults to the `decision` section, and any `/v1/systemone` endpoint works — e.g. llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`.
|
|
171
|
+
|
|
172
|
+
Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. See [Configuration](doc/configuration.md#shellguard) and [Plugin documentation](doc/plugin.md#shell-guard-command-vetting).
|
|
173
|
+
|
|
149
174
|
## Image Indexing
|
|
150
175
|
|
|
151
176
|
OpenCodeRAG can index image files (PNG, JPEG, WebP, etc.) by sending them to a vision-capable LLM and storing the generated text descriptions as searchable vector chunks. This makes visual assets discoverable via natural language queries (e.g., "login screen screenshot", "architecture diagram").
|
|
@@ -326,7 +351,7 @@ Retrieval quality has its own harness: `opencode-rag eval:gate` runs the labelle
|
|
|
326
351
|
|
|
327
352
|
## Privacy & Security
|
|
328
353
|
|
|
329
|
-
**100% local by default.** By default, embeddings are generated locally via Ollama. The vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure to use a third-party API.
|
|
354
|
+
**100% local by default.** By default, embeddings are generated locally via Ollama. The vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure to use a third-party API. The optional [Shell Guard](#shell-guard-optional) likewise sends command text only to the decision-model endpoint you configure (local Ollama or a local proxy).
|
|
330
355
|
|
|
331
356
|
## License
|
|
332
357
|
|
|
@@ -657,6 +657,13 @@ export function generateDefaultConfigJson(tuning, existingConfigRaw) {
|
|
|
657
657
|
keepAlive: DEFAULT_CONFIG.decision.keepAlive,
|
|
658
658
|
routeBeforeAsking: DEFAULT_CONFIG.decision.routeBeforeAsking,
|
|
659
659
|
},
|
|
660
|
+
shellGuard: {
|
|
661
|
+
enabled: DEFAULT_CONFIG.shellGuard.enabled,
|
|
662
|
+
threshold: DEFAULT_CONFIG.shellGuard.threshold,
|
|
663
|
+
timeoutMs: DEFAULT_CONFIG.shellGuard.timeoutMs,
|
|
664
|
+
onError: DEFAULT_CONFIG.shellGuard.onError,
|
|
665
|
+
cacheTtlMs: DEFAULT_CONFIG.shellGuard.cacheTtlMs,
|
|
666
|
+
},
|
|
660
667
|
description: {
|
|
661
668
|
enabled: DEFAULT_CONFIG.description.enabled,
|
|
662
669
|
provider: DEFAULT_CONFIG.description.provider,
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import path from "node:path";
|
|
13
13
|
import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync } from "node:fs";
|
|
14
|
-
import { loadConfig, findConfigFile } from "../../core/config.js";
|
|
14
|
+
import { loadConfig, findConfigFile, loadWorkspaceConfig, configuredSections } from "../../core/config.js";
|
|
15
15
|
import { checkProviderHealth, pullOllamaModels } from "../../embedder/health.js";
|
|
16
16
|
import { destroyAllPooledConnections } from "../../embedder/http.js";
|
|
17
17
|
import { c } from "../format.js";
|
|
@@ -327,8 +327,11 @@ export async function runWorkspaceInit(options = {}) {
|
|
|
327
327
|
? null
|
|
328
328
|
: (async () => {
|
|
329
329
|
console.log(`\n${c.heading("Checking provider connectivity...")}\n`);
|
|
330
|
-
|
|
331
|
-
|
|
330
|
+
// Effective config (global < workspace) and the sections the user
|
|
331
|
+
// actually configured: models that are merely on by default are
|
|
332
|
+
// never probed or offered for `ollama pull`.
|
|
333
|
+
const ragConfig = loadWorkspaceConfig(cwd);
|
|
334
|
+
return checkProviderHealth(ragConfig, configuredSections(cwd));
|
|
332
335
|
})();
|
|
333
336
|
const installPromise = options.skipInstall
|
|
334
337
|
? null
|
|
@@ -346,7 +349,7 @@ export async function runWorkspaceInit(options = {}) {
|
|
|
346
349
|
}
|
|
347
350
|
const missingOllama = results.filter((r) => r.status === "missing" && r.provider === "ollama");
|
|
348
351
|
if (missingOllama.length > 0) {
|
|
349
|
-
const ragConfig =
|
|
352
|
+
const ragConfig = loadWorkspaceConfig(cwd);
|
|
350
353
|
const pullEntries = missingOllama.map((r) => {
|
|
351
354
|
if (r.type === "embedding") {
|
|
352
355
|
return { model: r.model, baseUrl: ragConfig.embedding.baseUrl, proxy: ragConfig.embedding.proxy };
|
package/dist/core/bootstrap.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* creates embedder, vector store, keyword index, and description provider.
|
|
4
4
|
*/
|
|
5
5
|
import path from "node:path";
|
|
6
|
-
import { loadConfig,
|
|
6
|
+
import { loadConfig, loadWorkspaceConfig, resolveConfigPaths, resolveLogConfig } from "./config.js";
|
|
7
7
|
import { resolveApiKey } from "./resolve-api-key.js";
|
|
8
8
|
import { loadChunkersFromConfig } from "../chunker/loader.js";
|
|
9
9
|
import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
|
|
@@ -63,23 +63,26 @@ async function loadKeywordIndex(storePath) {
|
|
|
63
63
|
export async function resolveRagContext(opts = {}) {
|
|
64
64
|
const workDir = opts.cwd ?? process.cwd();
|
|
65
65
|
let configPath;
|
|
66
|
+
let cfg;
|
|
66
67
|
if (opts.configPath) {
|
|
67
68
|
configPath = path.resolve(workDir, opts.configPath);
|
|
68
|
-
}
|
|
69
|
-
else {
|
|
70
|
-
configPath = findConfigFile(workDir);
|
|
71
|
-
}
|
|
72
|
-
let cfg;
|
|
73
|
-
if (configPath) {
|
|
74
69
|
cfg = loadConfig(configPath);
|
|
75
70
|
resolveApiKey(cfg, workDir);
|
|
76
71
|
await loadChunkersFromConfig(cfg, path.dirname(configPath));
|
|
77
72
|
}
|
|
78
73
|
else {
|
|
79
|
-
//
|
|
80
|
-
|
|
81
|
-
|
|
74
|
+
// Defaults < global (~/.config/opencode/opencode-rag.json) < workspace.
|
|
75
|
+
const paths = resolveConfigPaths(workDir);
|
|
76
|
+
configPath = paths.workspace;
|
|
77
|
+
cfg = loadWorkspaceConfig(workDir);
|
|
82
78
|
resolveApiKey(cfg, workDir);
|
|
79
|
+
const baseDir = paths.workspace
|
|
80
|
+
? path.dirname(paths.workspace)
|
|
81
|
+
: paths.global
|
|
82
|
+
? path.dirname(paths.global)
|
|
83
|
+
: undefined;
|
|
84
|
+
if (baseDir)
|
|
85
|
+
await loadChunkersFromConfig(cfg, baseDir);
|
|
83
86
|
}
|
|
84
87
|
const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
|
|
85
88
|
const embedder = createEmbedder(cfg);
|
package/dist/core/config.d.ts
CHANGED
|
@@ -210,6 +210,56 @@ export interface DecisionConfig {
|
|
|
210
210
|
/** Base delay in ms between retries (exponential backoff). */
|
|
211
211
|
retryBaseDelayMs?: number;
|
|
212
212
|
}
|
|
213
|
+
/**
|
|
214
|
+
* Configuration for the optional shell-command safety guard.
|
|
215
|
+
*
|
|
216
|
+
* Every `shell`/`bash` command is classified by a local decision model
|
|
217
|
+
* (tev1 / Clef / Jev via `/v1/systemone`) before it runs. A command whose
|
|
218
|
+
* `destructive` or `malicious` probability reaches `threshold` is escalated to
|
|
219
|
+
* OpenCode's permission prompt; a clean command executes unchanged.
|
|
220
|
+
*
|
|
221
|
+
* The guard reuses the `decision` backend unless `provider`/`baseUrl`/`model`
|
|
222
|
+
* override it here. It is applied through OpenCode V2's permission
|
|
223
|
+
* `evaluate` hook, so it needs no rule changes in `opencode.json`.
|
|
224
|
+
*/
|
|
225
|
+
export interface ShellGuardConfig {
|
|
226
|
+
/**
|
|
227
|
+
* Master gate. Default false — the guard is opt-in because every shell
|
|
228
|
+
* command then waits for the local decision model.
|
|
229
|
+
*/
|
|
230
|
+
enabled: boolean;
|
|
231
|
+
/** Decision provider override (defaults to `decision.provider`). */
|
|
232
|
+
provider?: string;
|
|
233
|
+
/** Endpoint override (defaults to `decision.baseUrl`). */
|
|
234
|
+
baseUrl?: string;
|
|
235
|
+
/** Model override (defaults to `decision.model`). */
|
|
236
|
+
model?: string;
|
|
237
|
+
/**
|
|
238
|
+
* Flag a command when `p(destructive)` or `p(malicious)` reaches this
|
|
239
|
+
* probability (0-1). Default 0.5. Lower = more prompts; tune against the
|
|
240
|
+
* `shell.guard` debug-log lines.
|
|
241
|
+
*/
|
|
242
|
+
threshold: number;
|
|
243
|
+
/**
|
|
244
|
+
* Abort a classification after this many ms and apply `onError`. Default
|
|
245
|
+
* 10000. Kept short because the check sits on the critical path of every
|
|
246
|
+
* shell command.
|
|
247
|
+
*/
|
|
248
|
+
timeoutMs: number;
|
|
249
|
+
/**
|
|
250
|
+
* What to do when the classifier fails (timeout, endpoint down, malformed
|
|
251
|
+
* answer). `"allow"` (default) executes the command and logs a warning;
|
|
252
|
+
* `"ask"` escalates to the confirmation prompt.
|
|
253
|
+
*/
|
|
254
|
+
onError?: "allow" | "ask";
|
|
255
|
+
/**
|
|
256
|
+
* Verdict cache TTL in ms. Default 600000 (10 min). 0 disables the cache.
|
|
257
|
+
* Repeated identical commands are answered instantly.
|
|
258
|
+
*/
|
|
259
|
+
cacheTtlMs: number;
|
|
260
|
+
/** Maximum cached verdicts before the oldest are evicted. Default 256. */
|
|
261
|
+
maxCacheEntries?: number;
|
|
262
|
+
}
|
|
213
263
|
export interface UiConfig {
|
|
214
264
|
/** HTTP port for the UI server. */
|
|
215
265
|
port: number;
|
|
@@ -651,6 +701,8 @@ export interface RagConfig {
|
|
|
651
701
|
imageDescription?: ImageDescriptionConfig;
|
|
652
702
|
/** Decision-model (tev1) config for the `make_decision` tool. */
|
|
653
703
|
decision?: DecisionConfig;
|
|
704
|
+
/** Optional shell-command safety guard (decision-model vetting + confirmation prompt). */
|
|
705
|
+
shellGuard?: ShellGuardConfig;
|
|
654
706
|
/** Automated documentation mode config. */
|
|
655
707
|
documentationMode?: DocumentationModeConfig;
|
|
656
708
|
/** Wiki mode config that instructs the AI agent to maintain a persistent knowledge wiki. */
|
|
@@ -707,8 +759,54 @@ export declare const CONFIG_FILE_CANDIDATES: string[];
|
|
|
707
759
|
* @returns The absolute path to the config file, or undefined if none found.
|
|
708
760
|
*/
|
|
709
761
|
export declare function findConfigFile(directory: string): string | undefined;
|
|
710
|
-
/**
|
|
762
|
+
/**
|
|
763
|
+
* Resolve the machine-wide config file path.
|
|
764
|
+
*
|
|
765
|
+
* `$XDG_CONFIG_HOME/opencode/opencode-rag.json`, falling back to
|
|
766
|
+
* `~/.config/opencode/opencode-rag.json`. The global file is a BASE layer:
|
|
767
|
+
* every workspace config is merged on top of it, so machine-wide defaults
|
|
768
|
+
* (e.g. `shellGuard.enabled`) do not need to be repeated per project.
|
|
769
|
+
*/
|
|
770
|
+
export declare function globalConfigPath(envVars?: NodeJS.ProcessEnv, homeDir?: string): string;
|
|
771
|
+
/** Return the global config path when that file exists. */
|
|
772
|
+
export declare function findGlobalConfigFile(envVars?: NodeJS.ProcessEnv, homeDir?: string): string | undefined;
|
|
773
|
+
/** Config layers that apply to a workspace (lowest precedence first). */
|
|
774
|
+
export declare function resolveConfigPaths(directory: string): {
|
|
775
|
+
global?: string;
|
|
776
|
+
workspace?: string;
|
|
777
|
+
};
|
|
778
|
+
/**
|
|
779
|
+
* Load and parse a JSON config file, deep-merge with defaults, optionally validate.
|
|
780
|
+
*
|
|
781
|
+
* This is the single-file loader: the given file is authoritative. Workspace
|
|
782
|
+
* loading with the global base layer goes through {@link loadWorkspaceConfig}.
|
|
783
|
+
*/
|
|
711
784
|
export declare function loadConfig(filePath: string, validate?: boolean): RagConfig;
|
|
785
|
+
/**
|
|
786
|
+
* Load several config files, later files overriding earlier ones.
|
|
787
|
+
*
|
|
788
|
+
* Raw JSON layers are deep-merged BEFORE the per-section defaults merge, so a
|
|
789
|
+
* layer that omits a section cannot reset a value supplied by a lower layer.
|
|
790
|
+
*/
|
|
791
|
+
export declare function loadConfigLayers(filePaths: readonly string[], validate?: boolean): RagConfig;
|
|
792
|
+
/**
|
|
793
|
+
* Load the effective config for a workspace: defaults < global < workspace.
|
|
794
|
+
*
|
|
795
|
+
* A workspace with no local config still gets the global layer; with neither
|
|
796
|
+
* file present the result is `DEFAULT_CONFIG`. Explicit `--config` callers keep
|
|
797
|
+
* using {@link loadConfig} so their chosen file stays authoritative.
|
|
798
|
+
*/
|
|
799
|
+
export declare function loadWorkspaceConfig(directory: string, validate?: boolean): RagConfig;
|
|
800
|
+
/**
|
|
801
|
+
* Top-level sections that a workspace actually configures.
|
|
802
|
+
*
|
|
803
|
+
* Read from the raw JSON layers (global + workspace), NOT from the merged
|
|
804
|
+
* config, so a section that exists only in `DEFAULT_CONFIG` is not reported.
|
|
805
|
+
* Health checks use this to probe only the models a user asked for: the
|
|
806
|
+
* default-on `description` / `imageDescription` models are not "configured"
|
|
807
|
+
* just because defaults enable them.
|
|
808
|
+
*/
|
|
809
|
+
export declare function configuredSections(directory: string): Set<string>;
|
|
712
810
|
/**
|
|
713
811
|
* Persist a probed embedding vector dimension into the config JSON file.
|
|
714
812
|
* Sets `embedding.vectorDimension` so subsequent startups skip the probe.
|
package/dist/core/config.js
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { existsSync, readFileSync, writeFileSync } from "node:fs";
|
|
6
6
|
import path from "node:path";
|
|
7
|
+
import { homedir } from "node:os";
|
|
7
8
|
import { env } from "node:process";
|
|
8
9
|
import { normalizeParserOverrides } from "./parser-overrides.js";
|
|
9
10
|
export const DEFAULT_CONFIG = {
|
|
@@ -202,6 +203,14 @@ export const DEFAULT_CONFIG = {
|
|
|
202
203
|
retryMax: 2,
|
|
203
204
|
retryBaseDelayMs: 500,
|
|
204
205
|
},
|
|
206
|
+
shellGuard: {
|
|
207
|
+
enabled: false,
|
|
208
|
+
threshold: 0.5,
|
|
209
|
+
timeoutMs: 10000,
|
|
210
|
+
onError: "allow",
|
|
211
|
+
cacheTtlMs: 600000,
|
|
212
|
+
maxCacheEntries: 256,
|
|
213
|
+
},
|
|
205
214
|
description: {
|
|
206
215
|
enabled: true,
|
|
207
216
|
provider: "ollama",
|
|
@@ -371,7 +380,7 @@ export function validateConfig(config) {
|
|
|
371
380
|
const KNOWN_TOP_KEYS = new Set([
|
|
372
381
|
"embedding", "indexing", "vectorStore", "retrieval", "reranking",
|
|
373
382
|
"openCode", "chunkers", "chunking", "description",
|
|
374
|
-
"imageDescription", "decision", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
|
|
383
|
+
"imageDescription", "decision", "shellGuard", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
|
|
375
384
|
]);
|
|
376
385
|
const topKeys = new Set(Object.keys(config));
|
|
377
386
|
for (const key of topKeys) {
|
|
@@ -584,6 +593,37 @@ export function validateConfig(config) {
|
|
|
584
593
|
warnings.push(`decision.baseUrl "${config.decision.baseUrl}" is not a valid URL`);
|
|
585
594
|
}
|
|
586
595
|
}
|
|
596
|
+
if (config.shellGuard) {
|
|
597
|
+
const sg = config.shellGuard;
|
|
598
|
+
if (typeof sg.threshold !== "number" || !Number.isFinite(sg.threshold) || sg.threshold < 0 || sg.threshold > 1) {
|
|
599
|
+
warnings.push("shellGuard.threshold must be a number between 0 and 1");
|
|
600
|
+
}
|
|
601
|
+
if (typeof sg.timeoutMs !== "number" || !Number.isFinite(sg.timeoutMs) || sg.timeoutMs <= 0) {
|
|
602
|
+
warnings.push("shellGuard.timeoutMs must be > 0");
|
|
603
|
+
}
|
|
604
|
+
if (sg.onError != null && sg.onError !== "allow" && sg.onError !== "ask") {
|
|
605
|
+
warnings.push(`shellGuard.onError "${sg.onError}" — expected "allow" or "ask"`);
|
|
606
|
+
}
|
|
607
|
+
if (typeof sg.cacheTtlMs !== "number" || !Number.isFinite(sg.cacheTtlMs) || sg.cacheTtlMs < 0) {
|
|
608
|
+
warnings.push("shellGuard.cacheTtlMs must be >= 0");
|
|
609
|
+
}
|
|
610
|
+
if (sg.maxCacheEntries != null && (typeof sg.maxCacheEntries !== "number" || !Number.isFinite(sg.maxCacheEntries) || sg.maxCacheEntries < 0)) {
|
|
611
|
+
warnings.push("shellGuard.maxCacheEntries must be >= 0");
|
|
612
|
+
}
|
|
613
|
+
for (const key of ["provider", "baseUrl", "model"]) {
|
|
614
|
+
if (sg[key] != null && typeof sg[key] !== "string") {
|
|
615
|
+
warnings.push(`shellGuard.${key} must be a string when set`);
|
|
616
|
+
}
|
|
617
|
+
}
|
|
618
|
+
if (sg.baseUrl != null) {
|
|
619
|
+
try {
|
|
620
|
+
new URL(sg.baseUrl);
|
|
621
|
+
}
|
|
622
|
+
catch {
|
|
623
|
+
warnings.push(`shellGuard.baseUrl "${sg.baseUrl}" is not a valid URL`);
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
}
|
|
587
627
|
if (config.reranking?.enabled) {
|
|
588
628
|
const rr = config.reranking;
|
|
589
629
|
if (!rr.baseUrl)
|
|
@@ -624,15 +664,36 @@ export function findConfigFile(directory) {
|
|
|
624
664
|
}
|
|
625
665
|
return undefined;
|
|
626
666
|
}
|
|
627
|
-
/**
|
|
628
|
-
|
|
667
|
+
/**
|
|
668
|
+
* Resolve the machine-wide config file path.
|
|
669
|
+
*
|
|
670
|
+
* `$XDG_CONFIG_HOME/opencode/opencode-rag.json`, falling back to
|
|
671
|
+
* `~/.config/opencode/opencode-rag.json`. The global file is a BASE layer:
|
|
672
|
+
* every workspace config is merged on top of it, so machine-wide defaults
|
|
673
|
+
* (e.g. `shellGuard.enabled`) do not need to be repeated per project.
|
|
674
|
+
*/
|
|
675
|
+
export function globalConfigPath(envVars = env, homeDir = homedir()) {
|
|
676
|
+
const xdg = envVars.XDG_CONFIG_HOME?.trim();
|
|
677
|
+
const base = xdg && xdg.length > 0 ? xdg : path.join(homeDir, ".config");
|
|
678
|
+
return path.join(base, "opencode", "opencode-rag.json");
|
|
679
|
+
}
|
|
680
|
+
/** Return the global config path when that file exists. */
|
|
681
|
+
export function findGlobalConfigFile(envVars = env, homeDir = homedir()) {
|
|
682
|
+
const candidate = globalConfigPath(envVars, homeDir);
|
|
683
|
+
return existsSync(candidate) ? candidate : undefined;
|
|
684
|
+
}
|
|
685
|
+
/** Config layers that apply to a workspace (lowest precedence first). */
|
|
686
|
+
export function resolveConfigPaths(directory) {
|
|
687
|
+
return { global: findGlobalConfigFile(), workspace: findConfigFile(directory) };
|
|
688
|
+
}
|
|
689
|
+
/** Read and parse one config file (BOM-tolerant); throws a descriptive error. */
|
|
690
|
+
function parseConfigFile(filePath) {
|
|
629
691
|
let raw;
|
|
630
|
-
let parsed;
|
|
631
692
|
try {
|
|
632
693
|
raw = readFileSync(filePath, "utf-8");
|
|
633
694
|
if (raw.charCodeAt(0) === 0xfeff)
|
|
634
695
|
raw = raw.slice(1);
|
|
635
|
-
|
|
696
|
+
return JSON.parse(raw);
|
|
636
697
|
}
|
|
637
698
|
catch (err) {
|
|
638
699
|
const code = err.code;
|
|
@@ -644,6 +705,84 @@ export function loadConfig(filePath, validate = true) {
|
|
|
644
705
|
}
|
|
645
706
|
throw err;
|
|
646
707
|
}
|
|
708
|
+
}
|
|
709
|
+
/** True for plain JSON objects (arrays and `null` are replacements, not merges). */
|
|
710
|
+
function isPlainObject(value) {
|
|
711
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
712
|
+
}
|
|
713
|
+
/** Recursively merge `override` onto `base`; arrays and primitives replace. */
|
|
714
|
+
function mergeConfigObjects(base, override) {
|
|
715
|
+
const merged = { ...base };
|
|
716
|
+
for (const [key, value] of Object.entries(override)) {
|
|
717
|
+
const current = merged[key];
|
|
718
|
+
merged[key] = isPlainObject(value) && isPlainObject(current)
|
|
719
|
+
? mergeConfigObjects(current, value)
|
|
720
|
+
: value;
|
|
721
|
+
}
|
|
722
|
+
return merged;
|
|
723
|
+
}
|
|
724
|
+
/**
|
|
725
|
+
* Load and parse a JSON config file, deep-merge with defaults, optionally validate.
|
|
726
|
+
*
|
|
727
|
+
* This is the single-file loader: the given file is authoritative. Workspace
|
|
728
|
+
* loading with the global base layer goes through {@link loadWorkspaceConfig}.
|
|
729
|
+
*/
|
|
730
|
+
export function loadConfig(filePath, validate = true) {
|
|
731
|
+
return buildConfig(parseConfigFile(filePath), validate);
|
|
732
|
+
}
|
|
733
|
+
/**
|
|
734
|
+
* Load several config files, later files overriding earlier ones.
|
|
735
|
+
*
|
|
736
|
+
* Raw JSON layers are deep-merged BEFORE the per-section defaults merge, so a
|
|
737
|
+
* layer that omits a section cannot reset a value supplied by a lower layer.
|
|
738
|
+
*/
|
|
739
|
+
export function loadConfigLayers(filePaths, validate = true) {
|
|
740
|
+
let merged = {};
|
|
741
|
+
for (const filePath of filePaths) {
|
|
742
|
+
merged = mergeConfigObjects(merged, parseConfigFile(filePath));
|
|
743
|
+
}
|
|
744
|
+
return buildConfig(merged, validate);
|
|
745
|
+
}
|
|
746
|
+
/**
|
|
747
|
+
* Load the effective config for a workspace: defaults < global < workspace.
|
|
748
|
+
*
|
|
749
|
+
* A workspace with no local config still gets the global layer; with neither
|
|
750
|
+
* file present the result is `DEFAULT_CONFIG`. Explicit `--config` callers keep
|
|
751
|
+
* using {@link loadConfig} so their chosen file stays authoritative.
|
|
752
|
+
*/
|
|
753
|
+
export function loadWorkspaceConfig(directory, validate = true) {
|
|
754
|
+
const { global, workspace } = resolveConfigPaths(directory);
|
|
755
|
+
const layers = [global, workspace].filter((p) => p !== undefined);
|
|
756
|
+
return loadConfigLayers(layers, validate);
|
|
757
|
+
}
|
|
758
|
+
/**
|
|
759
|
+
* Top-level sections that a workspace actually configures.
|
|
760
|
+
*
|
|
761
|
+
* Read from the raw JSON layers (global + workspace), NOT from the merged
|
|
762
|
+
* config, so a section that exists only in `DEFAULT_CONFIG` is not reported.
|
|
763
|
+
* Health checks use this to probe only the models a user asked for: the
|
|
764
|
+
* default-on `description` / `imageDescription` models are not "configured"
|
|
765
|
+
* just because defaults enable them.
|
|
766
|
+
*/
|
|
767
|
+
export function configuredSections(directory) {
|
|
768
|
+
const { global, workspace } = resolveConfigPaths(directory);
|
|
769
|
+
const sections = new Set();
|
|
770
|
+
for (const filePath of [global, workspace]) {
|
|
771
|
+
if (!filePath)
|
|
772
|
+
continue;
|
|
773
|
+
try {
|
|
774
|
+
const parsed = parseConfigFile(filePath);
|
|
775
|
+
for (const key of Object.keys(parsed))
|
|
776
|
+
sections.add(key);
|
|
777
|
+
}
|
|
778
|
+
catch {
|
|
779
|
+
// Malformed layer: loadConfig reports it; health checks stay best-effort.
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
return sections;
|
|
783
|
+
}
|
|
784
|
+
/** Merge raw config layers onto DEFAULT_CONFIG and validate. */
|
|
785
|
+
function buildConfig(parsed, validate) {
|
|
647
786
|
const safeObj = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
|
|
648
787
|
const cfg = {
|
|
649
788
|
embedding: {
|
|
@@ -716,6 +855,10 @@ export function loadConfig(filePath, validate = true) {
|
|
|
716
855
|
...DEFAULT_CONFIG.decision,
|
|
717
856
|
...(safeObj(parsed.decision) ?? {}),
|
|
718
857
|
},
|
|
858
|
+
shellGuard: {
|
|
859
|
+
...DEFAULT_CONFIG.shellGuard,
|
|
860
|
+
...(safeObj(parsed.shellGuard) ?? {}),
|
|
861
|
+
},
|
|
719
862
|
documentationMode: {
|
|
720
863
|
...DEFAULT_CONFIG.documentationMode,
|
|
721
864
|
...(safeObj(parsed.documentationMode) ?? {}),
|
|
@@ -18,9 +18,15 @@ export interface HealthCheckResult {
|
|
|
18
18
|
}
|
|
19
19
|
/**
|
|
20
20
|
* Check connectivity and model availability for all configured providers.
|
|
21
|
-
*
|
|
21
|
+
*
|
|
22
|
+
* The embedding model is always checked — indexing cannot work without it.
|
|
23
|
+
* Optional models are checked only when the feature is enabled AND its section
|
|
24
|
+
* is actually configured: `configuredSections` comes from the raw config
|
|
25
|
+
* layers, so a model that is only enabled by `DEFAULT_CONFIG` is never probed
|
|
26
|
+
* (and never offered for `ollama pull`). Omit the set to check every enabled
|
|
27
|
+
* model (used by callers that are not init/setup).
|
|
22
28
|
*/
|
|
23
|
-
export declare function checkProviderHealth(config: RagConfig): Promise<HealthCheckResult[]>;
|
|
29
|
+
export declare function checkProviderHealth(config: RagConfig, configuredSections?: ReadonlySet<string>): Promise<HealthCheckResult[]>;
|
|
24
30
|
/** A model entry to pull from an Ollama server. */
|
|
25
31
|
interface PullModelEntry {
|
|
26
32
|
/** Model name (e.g. "nomic-embed-text") */
|
package/dist/embedder/health.js
CHANGED
|
@@ -3,24 +3,31 @@ import { isZenProvider, resolveZenBaseUrl } from "../core/zen.js";
|
|
|
3
3
|
import { fetchWithProxy, postJson } from "./http.js";
|
|
4
4
|
/**
|
|
5
5
|
* Check connectivity and model availability for all configured providers.
|
|
6
|
-
*
|
|
6
|
+
*
|
|
7
|
+
* The embedding model is always checked — indexing cannot work without it.
|
|
8
|
+
* Optional models are checked only when the feature is enabled AND its section
|
|
9
|
+
* is actually configured: `configuredSections` comes from the raw config
|
|
10
|
+
* layers, so a model that is only enabled by `DEFAULT_CONFIG` is never probed
|
|
11
|
+
* (and never offered for `ollama pull`). Omit the set to check every enabled
|
|
12
|
+
* model (used by callers that are not init/setup).
|
|
7
13
|
*/
|
|
8
|
-
export async function checkProviderHealth(config) {
|
|
14
|
+
export async function checkProviderHealth(config, configuredSections) {
|
|
9
15
|
const timeoutMs = config.embedding.timeoutMs ?? 120000;
|
|
16
|
+
const configured = (section) => !configuredSections || configuredSections.has(section);
|
|
10
17
|
const checks = [
|
|
11
18
|
checkEmbeddingModel(config, timeoutMs),
|
|
12
19
|
];
|
|
13
|
-
if (config.description?.enabled) {
|
|
20
|
+
if (config.description?.enabled && configured("description")) {
|
|
14
21
|
checks.push(checkDescriptionModel(config, timeoutMs));
|
|
15
22
|
}
|
|
16
|
-
if (config.imageDescription?.enabled) {
|
|
23
|
+
if (config.imageDescription?.enabled && configured("imageDescription")) {
|
|
17
24
|
checks.push(checkImageDescriptionModel(config, timeoutMs));
|
|
18
25
|
const onDemand = resolveOnDemandImageConfig(config.imageDescription);
|
|
19
26
|
if (onDemand.provider !== config.imageDescription.provider || onDemand.model !== config.imageDescription.model) {
|
|
20
27
|
checks.push(checkOnDemandImageDescriptionModel(onDemand));
|
|
21
28
|
}
|
|
22
29
|
}
|
|
23
|
-
if (config.reranking?.enabled) {
|
|
30
|
+
if (config.reranking?.enabled && configured("reranking")) {
|
|
24
31
|
checks.push(checkRerankModel(config));
|
|
25
32
|
}
|
|
26
33
|
return Promise.all(checks);
|
package/dist/index.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ export { LanceDbStore } from "./vectorstore/lancedb.js";
|
|
|
18
18
|
export { InMemoryVectorStore } from "./vectorstore/memory.js";
|
|
19
19
|
export { retrieve } from "./retriever/retriever.js";
|
|
20
20
|
export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
|
|
21
|
-
export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
|
|
21
|
+
export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths, configuredSections, findGlobalConfigFile, globalConfigPath, DEFAULT_CONFIG } from "./core/config.js";
|
|
22
22
|
export { createBackgroundIndexer } from "./watcher.js";
|
|
23
23
|
export { createWatchIgnore } from "./indexer.js";
|
|
24
24
|
export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
|
package/dist/index.js
CHANGED
|
@@ -17,7 +17,7 @@ export { LanceDbStore } from "./vectorstore/lancedb.js";
|
|
|
17
17
|
export { InMemoryVectorStore } from "./vectorstore/memory.js";
|
|
18
18
|
export { retrieve } from "./retriever/retriever.js";
|
|
19
19
|
export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
|
|
20
|
-
export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
|
|
20
|
+
export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths, configuredSections, findGlobalConfigFile, globalConfigPath, DEFAULT_CONFIG } from "./core/config.js";
|
|
21
21
|
export { createBackgroundIndexer } from "./watcher.js";
|
|
22
22
|
export { createWatchIgnore } from "./indexer.js";
|
|
23
23
|
export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
|
|
@@ -50,6 +50,32 @@ export interface Logger {
|
|
|
50
50
|
* @param options - Configuration for the index pass.
|
|
51
51
|
* @returns Aggregate statistics for the pass.
|
|
52
52
|
*/
|
|
53
|
+
/** Minimum gap between two regular (non-aggressive) store optimize runs. */
|
|
54
|
+
export declare const MIN_OPTIMIZE_INTERVAL_MS: number;
|
|
55
|
+
/**
|
|
56
|
+
* Decide whether a regular store optimize may run now, and stamp the attempt.
|
|
57
|
+
*
|
|
58
|
+
* LanceDB's `Table.optimize()` always rewrites the ANN index (it decides the
|
|
59
|
+
* index is stale and rebuilds it), and one IVF_FLAT build is a full,
|
|
60
|
+
* uncompressed copy of the vector column - 12k chunks x 4096 float32 is about
|
|
61
|
+
* 190 MB. The watch loop optimized at the end of EVERY pass, so a busy session
|
|
62
|
+
* left one dead build per pass behind: on 2026-10-26 the store carried 15 builds
|
|
63
|
+
* (2.5 GB) against 380 MB of live data. Optimizing at most every
|
|
64
|
+
* {@link MIN_OPTIMIZE_INTERVAL_MS} bounds that to the builds of the last
|
|
65
|
+
* interval, and the version prune inside the same call reclaims the rest.
|
|
66
|
+
*
|
|
67
|
+
* Aggressive runs (a private temp store during a full rebuild) always return
|
|
68
|
+
* true.
|
|
69
|
+
*
|
|
70
|
+
* @param options - `force` bypasses the throttle; `now` overrides the clock (tests).
|
|
71
|
+
* @returns True when the caller should run the optimize.
|
|
72
|
+
*/
|
|
73
|
+
export declare function optimizeDue(options?: {
|
|
74
|
+
force?: boolean;
|
|
75
|
+
now?: number;
|
|
76
|
+
}): boolean;
|
|
77
|
+
/** Reset the optimize throttle (tests only). */
|
|
78
|
+
export declare function resetOptimizeThrottle(): void;
|
|
53
79
|
export declare function runIndexPass(options: RunIndexPassOptions): Promise<IndexRunStats>;
|
|
54
80
|
/**
|
|
55
81
|
* Warning text for description settings that leave chain-of-thought enabled,
|