opencode-rag-plugin 2.10.1 → 2.11.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.
Files changed (64) hide show
  1. package/ReadMe.md +40 -28
  2. package/dist/api.js +1 -0
  3. package/dist/chunker/grammar.d.ts +4 -1
  4. package/dist/chunker/grammar.js +9 -3
  5. package/dist/chunker/skeleton.js +61 -4
  6. package/dist/cli/commands/clickhouse.d.ts +61 -0
  7. package/dist/cli/commands/clickhouse.js +335 -0
  8. package/dist/cli/commands/eval-tuner.js +1 -1
  9. package/dist/cli/commands/eval.js +1 -1
  10. package/dist/cli/commands/index-command.js +2 -1
  11. package/dist/cli/commands/index.d.ts +1 -0
  12. package/dist/cli/commands/index.js +1 -0
  13. package/dist/cli/commands/init-helpers.js +2 -2
  14. package/dist/cli/commands/init.js +49 -11
  15. package/dist/cli/commands/quirk.js +6 -6
  16. package/dist/cli/commands/status.js +70 -6
  17. package/dist/cli/commands/ui.js +2 -2
  18. package/dist/cli/index.js +2 -1
  19. package/dist/cli/types.d.ts +14 -0
  20. package/dist/core/bootstrap.d.ts +7 -0
  21. package/dist/core/bootstrap.js +40 -9
  22. package/dist/core/config.d.ts +128 -5
  23. package/dist/core/config.js +205 -8
  24. package/dist/core/interfaces.d.ts +54 -0
  25. package/dist/core/runtime-overrides.d.ts +9 -0
  26. package/dist/core/runtime-overrides.js +44 -0
  27. package/dist/core/state-sync.d.ts +91 -0
  28. package/dist/core/state-sync.js +273 -0
  29. package/dist/eval/fast-index.js +2 -2
  30. package/dist/eval/rerank-eval.js +2 -2
  31. package/dist/eval/run-branch-compare.js +2 -2
  32. package/dist/eval/run-token-test.js +2 -2
  33. package/dist/index.d.ts +5 -2
  34. package/dist/index.js +2 -1
  35. package/dist/indexer/pipeline.d.ts +6 -0
  36. package/dist/indexer/pipeline.js +173 -56
  37. package/dist/indexer/progress.d.ts +75 -0
  38. package/dist/indexer/progress.js +114 -0
  39. package/dist/indexer/stats.d.ts +14 -0
  40. package/dist/plugin.d.ts +6 -3
  41. package/dist/plugin.js +39 -20
  42. package/dist/quirks/quirk-store.d.ts +10 -0
  43. package/dist/quirks/quirk-store.js +110 -15
  44. package/dist/quirks/types.d.ts +7 -0
  45. package/dist/tui.js +128 -111
  46. package/dist/vectorstore/clickhouse.d.ts +150 -0
  47. package/dist/vectorstore/clickhouse.js +931 -0
  48. package/dist/vectorstore/dimension.d.ts +19 -0
  49. package/dist/vectorstore/dimension.js +36 -0
  50. package/dist/vectorstore/factory.d.ts +9 -3
  51. package/dist/vectorstore/factory.js +11 -2
  52. package/dist/vectorstore/lancedb.d.ts +2 -2
  53. package/dist/watcher.d.ts +29 -0
  54. package/dist/watcher.js +76 -2
  55. package/dist/web/api.d.ts +3 -4
  56. package/dist/web/api.js +18 -3
  57. package/dist/web/server.js +28 -2
  58. package/dist/web/ui/assets/{ScatterPlot3D-CKwyh1Ec.js → ScatterPlot3D-XjXIwavM.js} +5 -5
  59. package/dist/web/ui/assets/index-B-RH6fko.css +2 -0
  60. package/dist/web/ui/assets/index-FFPRbgLx.js +4 -0
  61. package/dist/web/ui/index.html +2 -2
  62. package/package.json +7 -2
  63. package/dist/web/ui/assets/index-CWcp0jNf.css +0 -2
  64. package/dist/web/ui/assets/index-DbXFrn53.js +0 -4
@@ -10,9 +10,10 @@ import fs from "node:fs";
10
10
  import { c, resolveCliContext, logCliError, logCliInfo, formatTimestamp, formatRelativeAge } from "../format.js";
11
11
  import { getIndexStatusSummary } from "../../indexer.js";
12
12
  import { findKeywordIndexGaps } from "../../indexer/keyword-rehydration.js";
13
- import { deriveWatcherHealth } from "../../watcher.js";
13
+ import { deriveWatcherHealth, discoverWatcherStates } from "../../watcher.js";
14
14
  import { getPackageMetadata } from "../helpers.js";
15
15
  import { checkForUpdate } from "../../core/version-check.js";
16
+ import { deriveNamespace, sanitizeNamespace } from "../../vectorstore/clickhouse.js";
16
17
  /**
17
18
  * Check for a stale index.lock file and clean it up if the owning process is dead.
18
19
  *
@@ -63,6 +64,7 @@ export function registerStatusCommand(program) {
63
64
  .command("status")
64
65
  .description("Show indexing status")
65
66
  .option("-c, --config <path>", "path to config file")
67
+ .option("--quick", "skip the workspace scan (Up-to-date/Pending files are then unknown, not zero)")
66
68
  .action(async (options) => {
67
69
  try {
68
70
  const cwd = process.cwd();
@@ -72,9 +74,41 @@ export function registerStatusCommand(program) {
72
74
  logFilePath = ctx.logFilePath;
73
75
  checkStaleLock(storePath, logFilePath);
74
76
  const count = await store.count();
75
- const summary = await getIndexStatusSummary(cwd, storePath, config, store, true);
77
+ // Scan by default: a skipped scan used to print "Up-to-date files: 0 /
78
+ // Pending files: 0" — two numbers that were never computed. With
79
+ // --quick the summary's `scanned` flag makes the display say so.
80
+ const summary = await getIndexStatusSummary(cwd, storePath, config, store, options.quick === true);
76
81
  logCliInfo(logFilePath, "status", `\n${c.heading("Indexed chunks:")} ${c.num(count)}`);
77
- logCliInfo(logFilePath, "status", `${c.label("Store path:")} ${c.file(storePath)}`);
82
+ const provider = config.vectorStore.provider ?? "lancedb";
83
+ if (provider === "clickhouse") {
84
+ const ch = config.vectorStore.clickhouse;
85
+ const namespace = ch?.namespace?.trim()
86
+ ? sanitizeNamespace(ch.namespace)
87
+ : deriveNamespace(cwd);
88
+ const annMode = ch?.ann === "hnsw" ? "hnsw ANN" : "exact scans";
89
+ logCliInfo(logFilePath, "status", `${c.label("Vector store:")} ${c.value("clickhouse")} ${c.file(`${ch?.url ?? ""}/${ch?.database ?? ""}`)} ` +
90
+ `(namespace ${c.value(namespace)}, ${annMode})`);
91
+ if (ch?.ann === "hnsw") {
92
+ const hasIndex = store.hasVectorIndex;
93
+ if (hasIndex) {
94
+ const present = await hasIndex.call(store).catch(() => false);
95
+ logCliInfo(logFilePath, "status", `${c.label("ANN index:")} ${present ? c.success("present") : c.warn("missing")} (vector_similarity)`);
96
+ }
97
+ }
98
+ logCliInfo(logFilePath, "status", `${c.label("Local cache:")} ${c.file(storePath)} (disposable)`);
99
+ try {
100
+ const lease = await store.getLease?.("index");
101
+ if (lease) {
102
+ logCliInfo(logFilePath, "status", `${c.label("Index lease:")} ${c.value(lease.owner)} (expires ${formatTimestamp(lease.expiresAt)})`);
103
+ }
104
+ }
105
+ catch {
106
+ // lease diagnostics are best effort
107
+ }
108
+ }
109
+ else {
110
+ logCliInfo(logFilePath, "status", `${c.label("Store path:")} ${c.file(storePath)}`);
111
+ }
78
112
  logCliInfo(logFilePath, "status", `${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
79
113
  logCliInfo(logFilePath, "status", `${c.label("Embedding model:")} ${c.value(config.embedding.model)}`);
80
114
  const storeDimension = await store.getVectorDimension?.();
@@ -98,15 +132,30 @@ export function registerStatusCommand(program) {
98
132
  logCliInfo(logFilePath, "status", `${c.label("Manifest status:")} ${summary.manifestStatus}`);
99
133
  logCliInfo(logFilePath, "status", `${c.label("Manifest entries:")} ${c.num(summary.manifestEntries)}`);
100
134
  logCliInfo(logFilePath, "status", `${c.label("Last indexed:")} ${c.value(formatTimestamp(summary.lastIndexedAt))}`);
101
- logCliInfo(logFilePath, "status", `${c.label("Up-to-date files:")} ${c.num(summary.upToDateFiles)}`);
102
- logCliInfo(logFilePath, "status", `${c.label("Pending files:")} ${c.num(summary.pendingFiles)}`);
135
+ if (summary.scanned) {
136
+ logCliInfo(logFilePath, "status", `${c.label("Up-to-date files:")} ${c.num(summary.upToDateFiles)}`);
137
+ logCliInfo(logFilePath, "status", `${c.label("Pending files:")} ${c.num(summary.pendingFiles)}`);
138
+ }
139
+ else {
140
+ logCliInfo(logFilePath, "status", `${c.label("Up-to-date files:")} ${c.dim("n/a (not scanned)")}`);
141
+ logCliInfo(logFilePath, "status", `${c.label("Pending files:")} ${c.dim("n/a (not scanned — rerun without --quick)")}`);
142
+ }
103
143
  logCliInfo(logFilePath, "status", `${c.label("Indexed chunks:")} ${c.num(summary.storeChunkCount)}`);
104
144
  logCliInfo(logFilePath, "status", `${c.label("Expected chunks:")} ${c.num(summary.manifestExpectedChunks)}`);
105
145
  logCliInfo(logFilePath, "status", `${c.label("Orphan chunks:")} ${c.num(summary.orphanChunks)}`);
146
+ if (summary.quirkChunks !== undefined) {
147
+ // Quirk rows are owned by quirks.jsonl — count them so
148
+ // Indexed = Expected + Orphan + Quirk reconciles and the reader can
149
+ // tell a sweepable orphan from a legitimately owned row.
150
+ logCliInfo(logFilePath, "status", `${c.label("Quirk chunks:")} ${c.num(summary.quirkChunks)} ${c.dim("(owned by quirks.jsonl)")}`);
151
+ }
106
152
  if (summary.orphanChunks > 0) {
107
153
  logCliInfo(logFilePath, "status", `${c.label("Unaccounted rows:")} ${c.warn("yes")} — stored chunks no manifest entry owns (files whose embedding never completed). Run 'opencode-rag index' to sweep them.`);
108
154
  }
109
- // Read watcher status from the background auto-indexer
155
+ // Read watcher status from the background auto-indexer. The watcher
156
+ // writes into ITS OWN store dir, so also discover watchers running in
157
+ // other store dirs (a plugin whose store was changed under it after
158
+ // load keeps watching elsewhere — this is where that shows up).
110
159
  const watcherStatusPath = path.join(storePath, "watcher-status.json");
111
160
  let watchModeDisplay;
112
161
  let watcherWarning;
@@ -139,6 +188,21 @@ export function registerStatusCommand(program) {
139
188
  if (watcherWarning) {
140
189
  logCliInfo(logFilePath, "status", `${c.label("Watcher health:")} ${c.warn(`stale — ${watcherWarning}`)} ${c.dim("(run 'opencode-rag index' or check .opencode/opencode-rag.log)")}`);
141
190
  }
191
+ try {
192
+ const others = discoverWatcherStates(storePath, cwd).filter((w) => path.resolve(w.storePath) !== path.resolve(storePath));
193
+ for (const w of others) {
194
+ if (w.alive && w.lock) {
195
+ logCliInfo(logFilePath, "status", `${c.label("Watcher elsewhere:")} ${c.warn("active")} pid ${w.lock.pid} in ${c.file(w.storePath)} ${c.dim("(the running OpenCode plugin indexes THAT store — restart OpenCode after a vectorStore/embedding config change)")}`);
196
+ }
197
+ else if (w.status?.lastRunAt || w.status?.lastSuccessAt) {
198
+ const last = w.status.lastSuccessAt ?? w.status.lastRunAt;
199
+ logCliInfo(logFilePath, "status", `${c.label("Watcher (old):")} ${c.dim(`stopped — last run ${formatRelativeAge(last)} in ${w.storePath}`)}`);
200
+ }
201
+ }
202
+ }
203
+ catch {
204
+ // watcher discovery is best effort
205
+ }
142
206
  const kiCount = config.retrieval.hybridSearch?.enabled
143
207
  ? keywordIndex?.count() ?? 0
144
208
  : 0;
@@ -32,10 +32,10 @@ export function registerUiCommand(program) {
32
32
  const port = parseInt(options.port ?? String(config.ui?.port ?? 3210), 10);
33
33
  const openBrowser = options.open !== false && (config.ui?.openBrowser ?? true);
34
34
  const { startWebUi } = await import("../../web/server.js");
35
- const { findConfigFile } = await import("../../core/config.js");
35
+ const { findConfigFile, projectConfigPath } = await import("../../core/config.js");
36
36
  const configPath = options.config
37
37
  ? path.resolve(cwd, options.config)
38
- : findConfigFile(cwd);
38
+ : findConfigFile(cwd) ?? projectConfigPath(cwd);
39
39
  const server = await startWebUi(storePath, port, cwd, config.embedding.vectorDimension ?? 384, config, configPath);
40
40
  const url = `http://127.0.0.1:${server.port}/?token=${server.token}`;
41
41
  logCliInfo(logFilePath, "ui", `\n${c.heading("OpenCodeRAG Web UI")}`);
package/dist/cli/index.js CHANGED
@@ -15,7 +15,7 @@ import { realpathSync } from "node:fs";
15
15
  import { basename, dirname } from "node:path";
16
16
  import { fileURLToPath } from "node:url";
17
17
  import { getPackageMetadata } from "./helpers.js";
18
- import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerEvalGateCommand, registerEvalDecideCommand, registerEvalTuneCommand, registerDescribeImageCommand, registerDecideCommand, registerQuirkCommand, } from "./commands/index.js";
18
+ import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerClickHouseCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerEvalGateCommand, registerEvalDecideCommand, registerEvalTuneCommand, registerDescribeImageCommand, registerDecideCommand, registerQuirkCommand, } from "./commands/index.js";
19
19
  /**
20
20
  * The top-level Commander program instance that defines the `opencode-rag` CLI.
21
21
  *
@@ -58,6 +58,7 @@ registerEvalGateCommand(program);
58
58
  registerEvalDecideCommand(program);
59
59
  registerEvalTuneCommand(program);
60
60
  registerInitCommand(program);
61
+ registerClickHouseCommand(program);
61
62
  registerQuirkCommand(program);
62
63
  // ── Auto-run detection ──────────────────────────────────────────
63
64
  /**
@@ -22,6 +22,8 @@ export interface CliOptions {
22
22
  yes?: boolean;
23
23
  /** Print a machine-readable JSON summary as the last line of the `index` command. */
24
24
  json?: boolean;
25
+ /** Skip the workspace scan in `status` (Up-to-date/Pending files then report unknown, not zero). */
26
+ quick?: boolean;
25
27
  /** Optional system prompt to steer an image description toward specific features. */
26
28
  systemPrompt?: string;
27
29
  }
@@ -33,6 +35,18 @@ export interface InitOptions {
33
35
  skipInstall?: boolean;
34
36
  /** Skip provider connectivity and model availability check. */
35
37
  skipHealthCheck?: boolean;
38
+ /** Vector-store backend to write into the config (`lancedb` or `clickhouse`). */
39
+ vectorStore?: string;
40
+ /** ClickHouse endpoint for `--vector-store clickhouse`. */
41
+ clickhouseUrl?: string;
42
+ /** ClickHouse database for `--vector-store clickhouse`. */
43
+ clickhouseDatabase?: string;
44
+ /** ClickHouse user for `--vector-store clickhouse`. */
45
+ clickhouseUser?: string;
46
+ /** ClickHouse password env var name for `--vector-store clickhouse`. */
47
+ clickhousePasswordEnv?: string;
48
+ /** ClickHouse project namespace (table suffix) for `--vector-store clickhouse`. */
49
+ clickhouseNamespace?: string;
36
50
  }
37
51
  /** Shape of the `package.json` metadata required by CLI helpers. */
38
52
  export interface PackageMetadata {
@@ -3,6 +3,7 @@
3
3
  * creates embedder, vector store, keyword index, and description provider.
4
4
  */
5
5
  import { type RagConfig } from "./config.js";
6
+ import { StateSync } from "./state-sync.js";
6
7
  import type { EmbeddingProvider, RerankProvider, VectorStore, KeywordIndex as IKeywordIndex, DescriptionProvider } from "./interfaces.js";
7
8
  /** Options for bootstrapping the RAG pipeline context. */
8
9
  export interface BootstrapOptions {
@@ -39,6 +40,12 @@ export interface RagContext {
39
40
  logFilePath: string;
40
41
  /** Resolved path to the config file, or undefined when built-in defaults are used. */
41
42
  configPath?: string;
43
+ /**
44
+ * Durable-state synchronizer. For ClickHouse this hydrates the local cache
45
+ * from `state_<namespace>` and flushes changes back; for LanceDB it is a
46
+ * no-op, so the local directory stays the source of truth.
47
+ */
48
+ stateSync?: StateSync;
42
49
  }
43
50
  /** Bootstrap the full RAG pipeline context: load config, resolve API keys, create embedder, vector store, keyword index, and description provider. */
44
51
  export declare function resolveRagContext(opts?: BootstrapOptions): Promise<RagContext>;
@@ -10,7 +10,9 @@ import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js"
10
10
  import { createDescriptionProvider } from "../describer/factory.js";
11
11
  import { createVectorStore } from "../vectorstore/factory.js";
12
12
  import { getRerankerFor } from "../reranker/factory.js";
13
- import { readStoreDimension } from "../vectorstore/lancedb.js";
13
+ import { readConfiguredStoreDimension } from "../vectorstore/dimension.js";
14
+ import { loadRuntimeOverrides, applyRuntimeOverrides } from "./runtime-overrides.js";
15
+ import { StateSync } from "./state-sync.js";
14
16
  import { KeywordIndex } from "../retriever/keyword-index.js";
15
17
  import { reconcileQuirks } from "../quirks/quirk-store.js";
16
18
  /**
@@ -28,7 +30,7 @@ import { reconcileQuirks } from "../quirks/quirk-store.js";
28
30
  * @param skipProbe - When true, never call the provider (read-only commands).
29
31
  * @returns The resolved dimension.
30
32
  */
31
- async function resolveDimension(embedder, storePath, skipProbe, configured) {
33
+ async function resolveDimension(embedder, storePath, skipProbe, configured, config, workspaceDir) {
32
34
  if (configured && configured > 0) {
33
35
  return configured;
34
36
  }
@@ -37,7 +39,7 @@ async function resolveDimension(embedder, storePath, skipProbe, configured) {
37
39
  if (probe.dimension !== undefined) {
38
40
  return probe.dimension;
39
41
  }
40
- const storeDimension = await readStoreDimension(storePath);
42
+ const storeDimension = await readConfiguredStoreDimension(config, storePath, workspaceDir);
41
43
  if (storeDimension !== undefined) {
42
44
  console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
43
45
  `using the existing store's dimension ${storeDimension}.`);
@@ -47,7 +49,7 @@ async function resolveDimension(embedder, storePath, skipProbe, configured) {
47
49
  "falling back to 384. Set embedding.vectorDimension explicitly if the provider produces a different size.");
48
50
  return 384;
49
51
  }
50
- return (await readStoreDimension(storePath)) ?? 384;
52
+ return (await readConfiguredStoreDimension(config, storePath, workspaceDir)) ?? 384;
51
53
  }
52
54
  /** Load the keyword index from disk, or create a new empty one if loading fails. */
53
55
  async function loadKeywordIndex(storePath) {
@@ -85,18 +87,46 @@ export async function resolveRagContext(opts = {}) {
85
87
  await loadChunkersFromConfig(cfg, baseDir);
86
88
  }
87
89
  const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
88
- const embedder = createEmbedder(cfg);
90
+ // Apply runtime overrides (the store's runtime-overrides.json) BEFORE
91
+ // building the embedder/store, exactly like the plugin does at startup.
92
+ // Without this the CLI's effective config diverges from the plugin's:
93
+ // `status` printed "off" while a live watcher ran, and `query` searched
94
+ // with different retrieval settings than the agent's tools. vectorStore
95
+ // has no override keys, so storePath is safe to resolve first.
89
96
  const storePath = path.resolve(workDir, cfg.vectorStore.path);
90
- const dimension = await resolveDimension(embedder, storePath, opts.skipProbe ?? false, cfg.embedding.vectorDimension);
97
+ try {
98
+ const overrides = loadRuntimeOverrides(storePath);
99
+ if (Object.keys(overrides).length > 0) {
100
+ cfg = applyRuntimeOverrides(cfg, overrides);
101
+ // Overrides can change embedding.baseUrl/provider — re-run the key
102
+ // resolution in the same order the plugin uses (apply → resolve).
103
+ resolveApiKey(cfg, workDir);
104
+ }
105
+ }
106
+ catch {
107
+ // Overrides are best-effort; a corrupt file must not break the CLI.
108
+ }
109
+ const embedder = createEmbedder(cfg);
110
+ const dimension = await resolveDimension(embedder, storePath, opts.skipProbe ?? false, cfg.embedding.vectorDimension, cfg, workDir);
91
111
  // Warn (but do not block) when the existing store schema disagrees with the
92
112
  // resolved dimension: the next index pass rebuilds automatically, and search
93
- // callers would otherwise see only cryptic LanceDB errors.
94
- const storeDimension = await readStoreDimension(storePath);
113
+ // callers would otherwise see only cryptic backend errors.
114
+ const storeDimension = await readConfiguredStoreDimension(cfg, storePath, workDir);
95
115
  if (storeDimension !== undefined && storeDimension !== dimension) {
96
116
  console.warn(`[bootstrap] Store was built with vector dimension ${storeDimension} but the current embedder produces ${dimension} — ` +
97
117
  "run 'opencode-rag index' to rebuild the index with the current model.");
98
118
  }
99
- const store = createVectorStore(cfg, storePath, dimension);
119
+ const store = createVectorStore(cfg, storePath, dimension, workDir);
120
+ // Durable-state sync: no-op for LanceDB (the local directory is the source
121
+ // of truth); for ClickHouse the local directory is a disposable cache that
122
+ // is hydrated from `state_<namespace>` before anything reads it.
123
+ const stateSync = new StateSync({ store, storePath, config: cfg });
124
+ try {
125
+ await stateSync.hydrate();
126
+ }
127
+ catch (err) {
128
+ console.warn(`[bootstrap] State hydration failed: ${err.message}`);
129
+ }
100
130
  const keywordIndex = opts.skipKeywordIndex
101
131
  ? new KeywordIndex(storePath)
102
132
  : await loadKeywordIndex(storePath);
@@ -138,6 +168,7 @@ export async function resolveRagContext(opts = {}) {
138
168
  dimension,
139
169
  logFilePath,
140
170
  configPath,
171
+ stateSync,
141
172
  };
142
173
  }
143
174
  //# sourceMappingURL=bootstrap.js.map
@@ -21,6 +21,62 @@ export interface ProxyConfig {
21
21
  /** Comma-separated list of hosts that bypass the proxy. */
22
22
  noProxy?: string;
23
23
  }
24
+ /**
25
+ * ClickHouse vector-store settings (used when `vectorStore.provider` is
26
+ * `"clickhouse"`). The local `vectorStore.path` remains a disposable cache
27
+ * for manifest/keyword-index/quirks files; the durable copies live in the
28
+ * project's `state_<namespace>` table.
29
+ */
30
+ export interface ClickHouseConfig {
31
+ /** HTTP(S) endpoint of the ClickHouse server (default `http://localhost:8123`). */
32
+ url: string;
33
+ /** Database that holds the per-project tables; created on first use. */
34
+ database: string;
35
+ /** ClickHouse user name. */
36
+ username: string;
37
+ /** Password. Prefer `passwordEnv` so the secret stays out of the repo file. */
38
+ password?: string;
39
+ /** Name of the environment variable holding the password (wins over `password` when set). */
40
+ passwordEnv?: string;
41
+ /**
42
+ * Project namespace appended to the table names (`chunks_<ns>`, `state_<ns>`).
43
+ * Defaults to a sanitized workspace directory name plus a short path hash;
44
+ * set it explicitly when several machines must share one project index.
45
+ */
46
+ namespace?: string;
47
+ /** Request timeout in milliseconds (default 30 000). */
48
+ requestTimeoutMs?: number;
49
+ /** Maximum HTTP connections in the client pool (default 10). */
50
+ maxOpenConnections?: number;
51
+ /** Enable gzip request/response compression (default true). */
52
+ compression?: boolean;
53
+ /** Durable workspace state bundled into `state_<ns>`. */
54
+ state?: {
55
+ /** Also sync `.desc-cache.json`. It is only a cache, so this defaults to false. */
56
+ syncDescCache?: boolean;
57
+ };
58
+ /** Advisory single-writer lease shared by all machines using this namespace. */
59
+ lease?: {
60
+ /** Default true. */
61
+ enabled?: boolean;
62
+ /** Lease lifetime; renewed at a third of the TTL (default 90 seconds). */
63
+ ttlSeconds?: number;
64
+ };
65
+ /** Refuse a full rebuild when the server has less free space than this (default 5 GiB). */
66
+ diskFreeFloorBytes?: number;
67
+ /**
68
+ * Vector index mode. `"off"` (default) uses exact `cosineDistance` scans.
69
+ * `"hnsw"` creates a `vector_similarity` index — requires ClickHouse >= 25.8
70
+ * (26.x is verified). The index is bound to the dimension it was created
71
+ * with; changing the embedding model then requires dropping the project
72
+ * tables and re-indexing.
73
+ */
74
+ ann?: "off" | "hnsw";
75
+ /** Over-fetch factor for filtered ANN searches (default 4, max 1000). */
76
+ annFetchMultiplier?: number;
77
+ /** Recompute final distances from the full-precision vectors (default true). */
78
+ annWithRescoring?: boolean;
79
+ }
24
80
  /** Configuration for automatic background re-indexing on file changes. */
25
81
  export interface AutoIndexConfig {
26
82
  /** Whether auto-indexing is enabled. */
@@ -409,7 +465,13 @@ export interface TuiConfig {
409
465
  fileListKeybinding: string;
410
466
  /** Keybinding to toggle the chunk viewer panel. */
411
467
  chunksKeybinding: string;
412
- /** Keybinding to open the RAG settings dialog. Must be distinguishable by the terminal (see docs). */
468
+ /**
469
+ * Keybinding to open the RAG settings dialog. Defaults to `alt+s`, which
470
+ * every terminal delivers (ESC + `s`), including VS Code's PowerShell
471
+ * terminal. A `ctrl+shift+<letter>` chord only works where the Kitty
472
+ * keyboard protocol is negotiated; when one is configured, the TUI also
473
+ * registers `ctrl+alt+s` / `alt+s` fallbacks (see docs).
474
+ */
413
475
  settingsKeybinding: string;
414
476
  }
415
477
  /** Configuration for the standalone MCP (Model Context Protocol) server. */
@@ -601,10 +663,17 @@ export interface RagConfig {
601
663
  };
602
664
  /** Vector storage backend configuration. */
603
665
  vectorStore: {
604
- /** Filesystem path or memory:// URI for the vector database. */
666
+ /**
667
+ * Filesystem path or `memory://` URI for a local vector database. With
668
+ * `provider: "clickhouse"` this is only a **disposable local cache** for
669
+ * the manifest, keyword index, quirks and other workspace state — the
670
+ * durable copies live in ClickHouse.
671
+ */
605
672
  path: string;
606
- /** Backend provider ("lancedb" or "memory"). */
607
- provider?: "lancedb" | "memory";
673
+ /** Backend provider ("lancedb", "memory", or "clickhouse"). */
674
+ provider?: "lancedb" | "memory" | "clickhouse";
675
+ /** ClickHouse connection settings (required when provider is "clickhouse"). */
676
+ clickhouse?: ClickHouseConfig;
608
677
  };
609
678
  /** Retrieval settings for query-time search. */
610
679
  retrieval: {
@@ -752,7 +821,15 @@ export interface ConfigValidationResult {
752
821
  }
753
822
  /** Validate a configuration object and return any warnings. */
754
823
  export declare function validateConfig(config: RagConfig): ConfigValidationResult;
755
- /** Config file locations to search, in order of precedence. */
824
+ /**
825
+ * Config file locations to search, in order of precedence.
826
+ *
827
+ * `.opencode/opencode-rag.json` is the canonical workspace location — every
828
+ * writer (TUI, `init`, `clickhouse setup`, the Web UI) creates and updates it
829
+ * there. The root-level `opencode-rag.json` is the legacy location, still read
830
+ * for compatibility (and migrated into `.opencode/` by `opencode-rag init`);
831
+ * `.opencode/rag.json` is a legacy alias inside `.opencode/`.
832
+ */
756
833
  export declare const CONFIG_FILE_CANDIDATES: string[];
757
834
  /**
758
835
  * Find the first existing config file in a directory.
@@ -770,6 +847,44 @@ export declare function findConfigFile(directory: string): string | undefined;
770
847
  export declare function globalConfigPath(envVars?: NodeJS.ProcessEnv, homeDir?: string): string;
771
848
  /** Return the global config path when that file exists. */
772
849
  export declare function findGlobalConfigFile(envVars?: NodeJS.ProcessEnv, homeDir?: string): string | undefined;
850
+ /**
851
+ * The canonical workspace config path `<directory>/.opencode/opencode-rag.json`.
852
+ * Exists or not — this is where writers CREATE the workspace config, keeping
853
+ * the project root clean. Use {@link findConfigFile} to read the effective one.
854
+ */
855
+ export declare function projectConfigPath(directory: string): string;
856
+ /**
857
+ * Move a legacy root-level `opencode-rag.json` into `.opencode/`.
858
+ *
859
+ * Only runs when the legacy file exists and the canonical file does not — an
860
+ * existing `.opencode/opencode-rag.json` always wins, so the legacy file is
861
+ * left alone rather than silently merged.
862
+ *
863
+ * @returns The new path when the file was moved, otherwise undefined.
864
+ */
865
+ export declare function migrateLegacyProjectConfig(directory: string): string | undefined;
866
+ /** Create an empty (`{}`) config file — and its parent directory — when absent. */
867
+ export declare function ensureConfigFile(filePath: string): void;
868
+ /**
869
+ * Write a value into the machine-global config file, creating it on demand.
870
+ *
871
+ * Provider options (embedding/description/... provider, model, baseUrl,
872
+ * apiKey) describe which models THIS MACHINE serves, not what the repository
873
+ * is, so they belong here rather than in a per-project file — and the global
874
+ * file is never committed, making it safe for API keys. The plugin re-reads
875
+ * this layer by mtime, so changes apply without a restart.
876
+ */
877
+ export declare function updateGlobalConfigValue(path_: readonly string[], value: unknown): boolean;
878
+ /**
879
+ * Whether a dotted config path is a machine-global provider option
880
+ * (section ∈ {@link PROVIDER_OPTION_SECTIONS}, leaf ∈ {@link PROVIDER_OPTION_LEAVES};
881
+ * `imageDescription.onDemand.*` counts via the `onDemand` group).
882
+ *
883
+ * Writers route these to {@link updateGlobalConfigValue} so provider/model/
884
+ * key/baseUrl never land in a per-project config file; every other path stays
885
+ * project-scoped.
886
+ */
887
+ export declare function isProviderScopedPath(path_: readonly string[]): boolean;
773
888
  /** Config layers that apply to a workspace (lowest precedence first). */
774
889
  export declare function resolveConfigPaths(directory: string): {
775
890
  global?: string;
@@ -797,6 +912,14 @@ export declare function loadConfigLayers(filePaths: readonly string[], validate?
797
912
  * using {@link loadConfig} so their chosen file stays authoritative.
798
913
  */
799
914
  export declare function loadWorkspaceConfig(directory: string, validate?: boolean): RagConfig;
915
+ /**
916
+ * Raw JSON layers (global < workspace) deep-merged WITHOUT defaults.
917
+ *
918
+ * For display surfaces (TUI sidebar/settings dialog) that must show what the
919
+ * USER configured rather than what `DEFAULT_CONFIG` contains. Malformed
920
+ * layers are skipped here — `loadWorkspaceConfig` reports the error elsewhere.
921
+ */
922
+ export declare function loadWorkspaceRawConfig(directory: string): Record<string, unknown>;
800
923
  /**
801
924
  * Top-level sections that a workspace actually configures.
802
925
  *