opencode-rag-plugin 2.9.3 → 2.10.0

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 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
- const ragConfig = loadConfig(configPath);
331
- return checkProviderHealth(ragConfig);
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 = loadConfig(configPath);
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 };
@@ -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, findConfigFile, resolveLogConfig, DEFAULT_CONFIG } from "./config.js";
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
- // Deep-clone so resolveApiKey (below) cannot mutate the shared
80
- // DEFAULT_CONFIG singleton.
81
- cfg = structuredClone(DEFAULT_CONFIG);
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);
@@ -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
- /** Load and parse a JSON config file, deep-merge with defaults, optionally validate. */
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.
@@ -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
- /** Load and parse a JSON config file, deep-merge with defaults, optionally validate. */
628
- export function loadConfig(filePath, validate = true) {
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
- parsed = JSON.parse(raw);
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
- * Returns one result per configured model (embedding + description + image_description if enabled).
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") */
@@ -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
- * Returns one result per configured model (embedding + description + image_description if enabled).
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";
package/dist/plugin.d.ts CHANGED
@@ -9,23 +9,28 @@ import { type RagConfig } from "./core/config.js";
9
9
  import { createEmbedder } from "./embedder/factory.js";
10
10
  import { retrieve } from "./retriever/retriever.js";
11
11
  /**
12
- * Load the RAG configuration for a directory, searching in order:
13
- * opencode-rag.json, .opencode/opencode-rag.json, .opencode/rag.json.
12
+ * Load the RAG configuration for a directory: DEFAULT_CONFIG, then the global
13
+ * layer (`~/.config/opencode/opencode-rag.json`), then the first workspace
14
+ * config found (`opencode-rag.json`, `.opencode/opencode-rag.json`,
15
+ * `.opencode/rag.json`).
14
16
  *
15
- * The result is cached per directory and re-read whenever the config file
16
- * changes on disk, so an edited API key or baseUrl does not require a restart.
17
+ * The result is cached per directory and re-read whenever either config file
18
+ * changes on disk, so an edited API key, baseUrl, or global `shellGuard` switch
19
+ * does not require a restart.
17
20
  */
18
21
  export declare function getConfig(directory: string): Promise<RagConfig>;
19
22
  /**
20
- * Re-read a workspace's config file when it changed on disk.
23
+ * Re-read a workspace's config when either the global or workspace file
24
+ * changed on disk.
21
25
  *
22
26
  * Only a config that this module loaded from a file is refreshed — the cache
23
- * entry is the proof that the file is the source of truth for that workspace.
24
- * A caller that supplies its own configuration (tests, embedders) keeps it.
27
+ * entry is the proof that the files are the source of truth for that
28
+ * workspace. A caller that supplies its own configuration (tests, embedders)
29
+ * keeps it.
25
30
  *
26
31
  * Synchronous on purpose: this runs on the hot path (every effective-config
27
- * lookup) and `loadConfig` is synchronous. The pluggable-chunker side effect
28
- * (`loadChunkersFromConfig`) mutates a global registry and is therefore
32
+ * lookup) and `loadWorkspaceConfig` is synchronous. The pluggable-chunker side
33
+ * effect (`loadChunkersFromConfig`) mutates a global registry and is therefore
29
34
  * re-applied asynchronously — it is not needed by the embedding path this
30
35
  * refresh exists to fix.
31
36
  *