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
package/dist/tui.js CHANGED
@@ -6,9 +6,9 @@ import { readFileSync, existsSync, writeFileSync, unlinkSync } from "node:fs";
6
6
  import { createRequire } from "node:module";
7
7
  import { dirname, join, resolve } from "node:path";
8
8
  import { fileURLToPath } from "node:url";
9
- import { loadRuntimeOverrides, saveRuntimeOverride } from "./core/runtime-overrides.js";
9
+ import { loadRuntimeOverrides, saveRuntimeOverride, deleteRuntimeOverride } from "./core/runtime-overrides.js";
10
10
  import { PROVIDER_DEFAULTS } from "./core/provider-defaults.js";
11
- import { loadConfig, updateConfigValue } from "./core/config.js";
11
+ import { findConfigFile, globalConfigPath, isProviderScopedPath, loadWorkspaceRawConfig, projectConfigPath, ensureConfigFile, updateConfigValue, updateGlobalConfigValue, } from "./core/config.js";
12
12
  import { setPendingRagInjection } from "./core/rag-injection-flag.js";
13
13
  /**
14
14
  * Lazy CommonJS require — this file is ESM ("type": "module"), so a bare
@@ -84,48 +84,44 @@ function watcherIsStale(w) {
84
84
  return true;
85
85
  return !!(w.lastChangeAt && (!w.lastSuccessAt || w.lastChangeAt > w.lastSuccessAt));
86
86
  }
87
+ /** Resolve the store directory from a raw effective config (workspace-relative or absolute `vectorStore.path`). */
88
+ function resolveStorePath(worktree, cfg) {
89
+ const vs = cfg.vectorStore;
90
+ const storeRelPath = vs?.path ?? ".opencode/rag_db";
91
+ return resolve(worktree, storeRelPath);
92
+ }
87
93
  /**
88
- * Load the full RAG status for a workspace by reading its config and
89
- * vector store manifest.
94
+ * Load the full RAG status for a workspace by reading its effective config
95
+ * (global + workspace layers) and the vector store manifest. Provider/model
96
+ * live in the global layer as often as in the workspace file, so a raw
97
+ * single-file read would show the wrong model in the sidebar.
90
98
  */
91
99
  function loadRagStatus(worktree) {
92
100
  const status = { ...DEFAULT_STATUS };
93
- for (const loc of ["opencode-rag.json", ".opencode/opencode-rag.json", ".opencode/rag.json"]) {
94
- const configPath = join(worktree, loc);
95
- if (!existsSync(configPath))
96
- continue;
97
- try {
98
- // BOM-tolerant read - a leading U+FEFF must not throw and silently skip
99
- // every config candidate (leaving the sidebar stuck on DEFAULT_STATUS).
100
- const cfg = readJsonFile(configPath);
101
- if (!cfg)
102
- continue; // unparseable (e.g. malformed JSON) - try next candidate
103
- const embedding = cfg.embedding;
104
- if (embedding) {
105
- status.provider = embedding.provider ?? status.provider;
106
- status.model = embedding.model ?? status.model;
107
- }
108
- const vs = cfg.vectorStore;
109
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
110
- const storePath = resolve(worktree, storeRelPath);
111
- const manifestPath = join(storePath, "manifest.json");
112
- if (existsSync(manifestPath)) {
113
- const manifest = readJsonFile(manifestPath);
114
- if (manifest) {
115
- const files = manifest.files;
116
- if (files && typeof files === "object") {
117
- status.chunkCount = Object.values(files).reduce((sum, entry) => sum + (entry.chunkCount ?? 0), 0);
118
- }
119
- status.lastIndexedAt = manifest.lastIndexedAt;
120
- status.indexed = status.chunkCount > 0;
101
+ try {
102
+ const cfg = loadWorkspaceRawConfig(worktree);
103
+ const embedding = cfg.embedding;
104
+ if (embedding) {
105
+ status.provider = embedding.provider ?? status.provider;
106
+ status.model = embedding.model ?? status.model;
107
+ }
108
+ const storePath = resolveStorePath(worktree, cfg);
109
+ const manifestPath = join(storePath, "manifest.json");
110
+ if (existsSync(manifestPath)) {
111
+ const manifest = readJsonFile(manifestPath);
112
+ if (manifest) {
113
+ const files = manifest.files;
114
+ if (files && typeof files === "object") {
115
+ status.chunkCount = Object.values(files).reduce((sum, entry) => sum + (entry.chunkCount ?? 0), 0);
121
116
  }
117
+ status.lastIndexedAt = manifest.lastIndexedAt;
118
+ status.indexed = status.chunkCount > 0;
122
119
  }
123
- status.watcher = loadWatcherStatus(storePath);
124
- break;
125
- }
126
- catch {
127
- continue;
128
120
  }
121
+ status.watcher = loadWatcherStatus(storePath);
122
+ }
123
+ catch {
124
+ // sidebar stays on DEFAULT_STATUS
129
125
  }
130
126
  return status;
131
127
  }
@@ -158,6 +154,14 @@ function formatKeybinding(key) {
158
154
  .map((k) => k.charAt(0).toUpperCase() + k.slice(1))
159
155
  .join("+");
160
156
  }
157
+ /**
158
+ * Default chord that opens the settings dialog.
159
+ *
160
+ * `alt+s` is encoded by every terminal as `ESC` + `s` — including VS Code's
161
+ * PowerShell terminal, where `ctrl+shift+<letter>` is swallowed until the
162
+ * Kitty keyboard protocol is negotiated. Exactly one chord is bound.
163
+ */
164
+ const DEFAULT_SETTINGS_KEYBINDING = "alt+s";
161
165
  const PLUGIN_NAME = "opencode-rag-plugin";
162
166
  /**
163
167
  * Create a TUI element node with the given tag, props, and children.
@@ -213,7 +217,7 @@ function renderSidebar(theme, version, status, tuiConfig, tokenStats) {
213
217
  : undefined;
214
218
  const fileListKey = tuiConfig?.fileListKeybinding ?? "ctrl+enter";
215
219
  const chunksKey = tuiConfig?.chunksKeybinding ?? "ctrl+alt+enter";
216
- const settingsKey = tuiConfig?.settingsKeybinding ?? "ctrl+shift+r";
220
+ const settingsKey = tuiConfig?.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING;
217
221
  return box({
218
222
  width: "100%",
219
223
  flexDirection: "column",
@@ -253,14 +257,39 @@ function renderSidebar(theme, version, status, tuiConfig, tokenStats) {
253
257
  ]);
254
258
  }
255
259
  // ── Settings dialog ────────────────────────────────────────────────
256
- /** Resolve the path to the first existing RAG config file in the worktree. */
257
- function getConfigPath(worktree) {
258
- for (const loc of ["opencode-rag.json", ".opencode/opencode-rag.json", ".opencode/rag.json"]) {
259
- const p = join(worktree, loc);
260
- if (existsSync(p))
261
- return p;
260
+ /**
261
+ * Resolve the WRITABLE workspace config file: the existing one found by
262
+ * {@link findConfigFile}, or a freshly created `.opencode/opencode-rag.json`
263
+ * — the canonical location. A workspace without any config file no longer
264
+ * blocks the dialog; the first write creates the file.
265
+ */
266
+ function getWritableConfigPath(worktree) {
267
+ const existing = findConfigFile(worktree);
268
+ if (existing)
269
+ return existing;
270
+ const created = projectConfigPath(worktree);
271
+ ensureConfigFile(created);
272
+ return created;
273
+ }
274
+ /**
275
+ * Persist a settings-dialog value to its proper layer.
276
+ *
277
+ * - Provider options (provider/model/baseUrl/apiKey of any model section) go
278
+ * into the machine-global config file ONLY — they describe this machine's
279
+ * models, not the repository, and the global file is never committed. Any
280
+ * stale per-store runtime override for that path is cleared so it cannot
281
+ * shadow the global value. The plugin re-reads the global layer by mtime.
282
+ * - Everything else stays project-scoped: workspace config file plus the
283
+ * runtime override that applies live within 5 s.
284
+ */
285
+ function persistSetting(worktree, storePath, path, value) {
286
+ if (isProviderScopedPath(path)) {
287
+ updateGlobalConfigValue(path, value);
288
+ deleteRuntimeOverride(storePath, [...path]);
289
+ return;
262
290
  }
263
- return undefined;
291
+ saveRuntimeOverride(storePath, [...path], value);
292
+ updateConfigValue(getWritableConfigPath(worktree), [...path], value);
264
293
  }
265
294
  /** Read and parse a JSON file, returning undefined on failure. */
266
295
  function readJsonFile(filePath) {
@@ -349,12 +378,18 @@ function syncWatcherStatusFile(storePath, enabled) {
349
378
  }
350
379
  }
351
380
  /**
352
- * Save a model selection to both runtime overrides and the config file.
353
- * Resolves the RAG provider name and API base URL automatically.
381
+ * Save a model selection as a machine-global provider option.
382
+ *
383
+ * provider/model/baseUrl (and the provider's apiKey) are written to the
384
+ * global config file (`~/.config/opencode/opencode-rag.json`) ONLY — never to
385
+ * the workspace config, which is routinely committed to git. The global file
386
+ * lives outside any repository, so the key is safe there. Legacy per-store
387
+ * runtime overrides for these keys are deleted so a value saved from an older
388
+ * build cannot shadow the global file.
354
389
  *
355
390
  * @returns The composite "provider/model" string if saved, or undefined for custom.
356
391
  */
357
- function saveModelSelection(storePath, configPath, selectionValue, path, providers) {
392
+ function saveModelSelection(storePath, selectionValue, path, providers) {
358
393
  const section = path[0];
359
394
  if (selectionValue === "__custom__")
360
395
  return undefined;
@@ -366,20 +401,19 @@ function saveModelSelection(storePath, configPath, selectionValue, path, provide
366
401
  const provider = providers?.find((p) => p.id === providerId);
367
402
  const ragProvider = providerIdToRagProvider(providerId);
368
403
  const baseUrl = provider ? resolveProviderBaseUrl(provider) : "";
369
- saveRuntimeOverride(storePath, [section, "provider"], ragProvider);
370
- updateConfigValue(configPath, [section, "provider"], ragProvider);
371
- saveRuntimeOverride(storePath, [section, "model"], modelId);
372
- updateConfigValue(configPath, [section, "model"], modelId);
373
- if (baseUrl) {
374
- saveRuntimeOverride(storePath, [section, "baseUrl"], baseUrl);
375
- updateConfigValue(configPath, [section, "baseUrl"], baseUrl);
376
- }
404
+ const writeProviderOption = (key, value) => {
405
+ updateGlobalConfigValue([section, key], value);
406
+ deleteRuntimeOverride(storePath, [section, key]);
407
+ };
408
+ writeProviderOption("provider", ragProvider);
409
+ writeProviderOption("model", modelId);
410
+ if (baseUrl)
411
+ writeProviderOption("baseUrl", baseUrl);
377
412
  const apiKey = provider?.options?.apiKey ?? "";
378
- if (apiKey) {
379
- // Persist the key only in the store-dir overrides, never in the workspace
380
- // config file — `opencode-rag.json` is routinely committed to git.
381
- saveRuntimeOverride(storePath, [section, "apiKey"], apiKey);
382
- }
413
+ if (apiKey)
414
+ writeProviderOption("apiKey", apiKey);
415
+ else
416
+ deleteRuntimeOverride(storePath, [section, "apiKey"]);
383
417
  return selectionValue;
384
418
  }
385
419
  /**
@@ -652,7 +686,7 @@ function buildSettingCategories(cfg, ro, providers) {
652
686
  path: ["tui", "settingsKeybinding"],
653
687
  label: "Open settings",
654
688
  type: "string",
655
- currentValue: tuiRo.settingsKeybinding ?? tuiCfg.settingsKeybinding ?? "ctrl+shift+r",
689
+ currentValue: tuiRo.settingsKeybinding ?? tuiCfg.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING,
656
690
  },
657
691
  {
658
692
  path: ["tui", "fileListKeybinding"],
@@ -686,13 +720,7 @@ function v2Bind(key) {
686
720
  /** Read token usage statistics from eval session logs (shared by the V2 path). */
687
721
  function readTokenStats(worktree) {
688
722
  try {
689
- const configPath = getConfigPath(worktree);
690
- if (!configPath)
691
- return undefined;
692
- const cfg = loadConfig(configPath);
693
- const vs = cfg.vectorStore;
694
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
695
- const storePath = resolve(worktree, storeRelPath);
723
+ const storePath = resolveStorePath(worktree, loadWorkspaceRawConfig(worktree));
696
724
  const { listSessions } = _require("./eval/storage.js");
697
725
  const sessions = listSessions(storePath);
698
726
  if (sessions.length === 0)
@@ -752,20 +780,19 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
752
780
  return;
753
781
  const { dialog, toast } = ui;
754
782
  const settingsToast = (variant, message) => toast.show({ variant, title: "Settings", message });
755
- const configPath = getConfigPath(worktree);
756
- if (!configPath) {
757
- settingsToast("error", "No config file found");
758
- return;
759
- }
760
- const cfgRaw = readJsonFile(configPath);
761
- if (!cfgRaw) {
762
- settingsToast("error", "Cannot read config");
763
- return;
764
- }
765
- const cfg = cfgRaw;
766
- const vs = cfg.vectorStore;
767
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
768
- const storePath = resolve(worktree, storeRelPath);
783
+ // Effective raw config (global < workspace, no defaults). Provider options
784
+ // usually live only in the global layer, so a single-file workspace read
785
+ // would display stale/absent values. A workspace without any config file is
786
+ // fine — the first non-provider write creates `.opencode/opencode-rag.json`.
787
+ const cfg = loadWorkspaceRawConfig(worktree);
788
+ const storePath = resolveStorePath(worktree, cfg);
789
+ /** Route one dialog value to its layer; provider options report where they went. */
790
+ const saveSetting = (path, value) => {
791
+ persistSetting(worktree, storePath, path, value);
792
+ if (isProviderScopedPath(path)) {
793
+ settingsToast("info", `Provider option saved to global config: ${globalConfigPath()}`);
794
+ }
795
+ };
769
796
  const refreshCats = () => buildSettingCategories(cfg, loadRuntimeOverrides(storePath), providers);
770
797
  const warnReindex = (path) => {
771
798
  if (path[0] === "indexing" || path[0] === "chunking")
@@ -825,17 +852,17 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
825
852
  continue;
826
853
  value = custom;
827
854
  }
828
- const saved = saveModelSelection(storePath, configPath, value, entry.path, providers);
855
+ const saved = saveModelSelection(storePath, value, entry.path, providers);
829
856
  if (saved) {
830
857
  entry.currentValue = saved;
831
858
  settingsToast("success", `${entry.label}: ${saved}`);
859
+ settingsToast("info", `Provider option saved to global config: ${globalConfigPath()}`);
832
860
  if (entry.path[0] === "embedding") {
833
- settingsToast("warning", "Embedding changed. Re-index may be required. Restart OpenCode for changes.");
861
+ settingsToast("warning", "Embedding changed. Re-index required for existing chunks.");
834
862
  }
835
863
  }
836
864
  else if (value) {
837
- saveRuntimeOverride(storePath, entry.path, value);
838
- updateConfigValue(configPath, entry.path, value);
865
+ saveSetting(entry.path, value);
839
866
  entry.currentValue = value;
840
867
  }
841
868
  onSettingsChanged?.();
@@ -843,8 +870,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
843
870
  }
844
871
  if (entry.type === "boolean") {
845
872
  const newVal = !entry.currentValue;
846
- saveRuntimeOverride(storePath, entry.path, newVal);
847
- updateConfigValue(configPath, entry.path, newVal);
873
+ saveSetting(entry.path, newVal);
848
874
  settingsToast("success", `${entry.label}: ${newVal ? "Yes" : "No"}`);
849
875
  warnReindex(entry.path);
850
876
  if (entry.path.join(".") === "openCode.autoIndex.enabled") {
@@ -868,8 +894,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
868
894
  settingsToast("error", "Enter a valid number");
869
895
  continue;
870
896
  }
871
- saveRuntimeOverride(storePath, entry.path, num);
872
- updateConfigValue(configPath, entry.path, num);
897
+ saveSetting(entry.path, num);
873
898
  settingsToast("success", `${entry.label}: ${num}`);
874
899
  warnReindex(entry.path);
875
900
  entry.currentValue = num;
@@ -882,8 +907,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
882
907
  settingsToast("error", "Value must be a JSON object");
883
908
  continue;
884
909
  }
885
- saveRuntimeOverride(storePath, entry.path, parsed);
886
- updateConfigValue(configPath, entry.path, parsed);
910
+ saveSetting(entry.path, parsed);
887
911
  settingsToast("success", `${entry.label}: updated`);
888
912
  warnReindex(entry.path);
889
913
  entry.currentValue = parsed;
@@ -894,8 +918,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
894
918
  }
895
919
  }
896
920
  else {
897
- saveRuntimeOverride(storePath, entry.path, raw);
898
- updateConfigValue(configPath, entry.path, raw);
921
+ saveSetting(entry.path, raw);
899
922
  settingsToast("success", `${entry.label}: ${raw}`);
900
923
  entry.currentValue = raw;
901
924
  onSettingsChanged?.();
@@ -927,14 +950,14 @@ async function setup(context) {
927
950
  let lastRefresh = 0;
928
951
  const REFRESH_INTERVAL_MS = Number(process.env.OPENCODE_RAG_TUI_REFRESH_MS) || 30000;
929
952
  let tuiConfig;
930
- const tuiConfigPath = worktree ? getConfigPath(worktree) : undefined;
931
- if (tuiConfigPath) {
932
- try {
933
- tuiConfig = loadConfig(tuiConfigPath).tui;
934
- }
935
- catch {
936
- // use defaults
937
- }
953
+ const rawCfg = worktree ? loadWorkspaceRawConfig(worktree) : {};
954
+ const tuiSection = rawCfg.tui;
955
+ if (tuiSection) {
956
+ tuiConfig = {
957
+ fileListKeybinding: tuiSection.fileListKeybinding ?? "ctrl+enter",
958
+ chunksKeybinding: tuiSection.chunksKeybinding ?? "ctrl+alt+enter",
959
+ settingsKeybinding: tuiSection.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING,
960
+ };
938
961
  }
939
962
  /** Refresh the cached RAG status from disk. */
940
963
  function refreshStatus() {
@@ -959,19 +982,13 @@ async function setup(context) {
959
982
  let flagStorePath;
960
983
  if (worktree) {
961
984
  try {
962
- const flagConfigPath = getConfigPath(worktree);
963
- if (flagConfigPath) {
964
- const flagCfg = loadConfig(flagConfigPath);
965
- const vs = flagCfg.vectorStore;
966
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
967
- flagStorePath = resolve(worktree, storeRelPath);
968
- }
985
+ flagStorePath = resolveStorePath(worktree, rawCfg);
969
986
  }
970
987
  catch {
971
988
  // ignore
972
989
  }
973
990
  }
974
- const settingsKey = tuiConfig?.settingsKeybinding ?? "ctrl+shift+r";
991
+ const settingsKey = tuiConfig?.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING;
975
992
  const fileListKey = tuiConfig?.fileListKeybinding ?? "ctrl+enter";
976
993
  const chunksKey = tuiConfig?.chunksKeybinding ?? "ctrl+alt+enter";
977
994
  try {
@@ -0,0 +1,150 @@
1
+ import type { BulkChunkWrite, Chunk, ChunkBrowseStore, ChunkSummary, FileSummary, MetadataFilter, SearchResult, VectorStore } from "../core/interfaces.js";
2
+ import type { RagConfig } from "../core/config.js";
3
+ /** Fully resolved ClickHouse connection/storage options. */
4
+ export interface ResolvedClickHouseOptions {
5
+ url: string;
6
+ database: string;
7
+ username: string;
8
+ password: string;
9
+ namespace: string;
10
+ chunksTable: string;
11
+ stateTable: string;
12
+ requestTimeoutMs: number;
13
+ maxOpenConnections: number;
14
+ compression: boolean;
15
+ ann: "off" | "hnsw";
16
+ annFetchMultiplier: number;
17
+ annWithRescoring: boolean;
18
+ leaseEnabled: boolean;
19
+ leaseTtlMs: number;
20
+ diskFreeFloorBytes: number;
21
+ syncDescCache: boolean;
22
+ /** Embedding model name recorded in `_meta` (diagnostics/rebuild audit). */
23
+ embeddingModel: string;
24
+ }
25
+ /** Sanitize a namespace so it is safe as a table suffix. */
26
+ export declare function sanitizeNamespace(raw: string): string;
27
+ /** Derive a stable namespace from a workspace path (name + path hash). */
28
+ export declare function deriveNamespace(workspaceDir: string): string;
29
+ /** Resolve a full ClickHouse config block (with defaults) for a workspace. */
30
+ export declare function resolveClickHouseOptions(config: RagConfig, workspaceDir: string): ResolvedClickHouseOptions;
31
+ /**
32
+ * ClickHouse-backed vector store. Instantiate through `createVectorStore()`;
33
+ * the constructor only records options and opens the client lazily.
34
+ */
35
+ export declare class ClickHouseStore implements ChunkBrowseStore {
36
+ private readonly opts;
37
+ private readonly dimensions;
38
+ /** Set on a rebuild target: all writes/reads are bound to this epoch. */
39
+ private readonly boundEpoch?;
40
+ private client;
41
+ private schemaReady;
42
+ private activeEpoch;
43
+ private writeChain;
44
+ private static modulePromise;
45
+ constructor(options: ResolvedClickHouseOptions, vectorDimension?: number, boundEpoch?: number);
46
+ private loadClientModule;
47
+ private getClient;
48
+ private command;
49
+ private select;
50
+ private table;
51
+ private insertTable;
52
+ private ensureSchema;
53
+ private initSchema;
54
+ /** Add + materialize the HNSW index on a table created before ANN was enabled. */
55
+ private ensureVectorIndex;
56
+ private currentEpoch;
57
+ /**
58
+ * Refresh the cached active epoch from `_meta` (at most every 2 s).
59
+ *
60
+ * Another machine may promote a rebuild or clear the namespace at any time;
61
+ * a handle that kept a stale epoch would read (or write) a superseded epoch
62
+ * forever — and after `optimize()` prunes it, silently see an empty store.
63
+ */
64
+ private epochCheckedAt;
65
+ private maybeRefreshEpoch;
66
+ private readMeta;
67
+ private writeMeta;
68
+ /** Generic state-bundle read used by `StateSync`. */
69
+ readState(name: string): Promise<{
70
+ data: string;
71
+ ver: string;
72
+ } | undefined>;
73
+ /** Generic state-bundle write used by `StateSync`. */
74
+ writeState(name: string, data: string, sha256?: string): Promise<void>;
75
+ /** Names currently present in the state bundle (newest row per name). */
76
+ listStateNames(): Promise<string[]>;
77
+ private withWriteLock;
78
+ addChunks(chunks: Chunk[], options?: {
79
+ dedup?: boolean;
80
+ }): Promise<void>;
81
+ addChunksBulk(items: BulkChunkWrite[]): Promise<void>;
82
+ private addChunksInternal;
83
+ private chunkToRow;
84
+ private tombstoneRow;
85
+ /** Remove all chunks for a file (tombstones; no table mutation). */
86
+ deleteByFilePath(filePath: string): Promise<void>;
87
+ /** Make every stored chunk invisible (bumps the active epoch). */
88
+ clear(): Promise<void>;
89
+ /** Start a full rebuild into a private epoch and return the target handle. */
90
+ beginRebuild(): Promise<VectorStore>;
91
+ /** Make the rebuild target visible in one atomic `_meta` write. */
92
+ promoteRebuild(): Promise<void>;
93
+ /** Abandon the rebuild target; its rows become unreachable orphans. */
94
+ discardRebuild(): Promise<void>;
95
+ search(embedding: number[], topK: number): Promise<SearchResult[]>;
96
+ searchWithFilter(embedding: number[], topK: number, filter?: MetadataFilter): Promise<SearchResult[]>;
97
+ private rowToSearchResult;
98
+ count(): Promise<number>;
99
+ getFilePaths(): Promise<string[]>;
100
+ listFiles(): Promise<FileSummary[]>;
101
+ getChunks(offset: number, limit: number): Promise<ChunkSummary[]>;
102
+ getChunksFiltered(offset: number, limit: number, lang?: string, filePrefix?: string): Promise<{
103
+ chunks: ChunkSummary[];
104
+ total: number;
105
+ }>;
106
+ getChunkById(id: string): Promise<ChunkSummary | undefined>;
107
+ getChunksByIds(ids: string[]): Promise<ChunkSummary[]>;
108
+ getChunksWithEmbeddings(limit: number): Promise<{
109
+ id: string;
110
+ filePath: string;
111
+ language: string;
112
+ startLine: number;
113
+ endLine: number;
114
+ description: string;
115
+ embedding: number[];
116
+ }[]>;
117
+ getChunksByFilePath(filePath: string): Promise<Chunk[]>;
118
+ private summaryColumns;
119
+ private parseTags;
120
+ private rowToSummary;
121
+ getVectorDimension(): Promise<number | undefined>;
122
+ /**
123
+ * Read the stored dimension without creating anything. Used by the
124
+ * bootstrap dimension probe, which must stay read-only for `status`.
125
+ */
126
+ peekDimension(): Promise<number | undefined>;
127
+ checkIntegrity(): Promise<boolean>;
128
+ /** Whether the HNSW vector index is present on the chunks table (diagnostics). */
129
+ hasVectorIndex(): Promise<boolean>;
130
+ optimize(options?: {
131
+ aggressive?: boolean;
132
+ skipIndex?: boolean;
133
+ logger?: (message: string) => void;
134
+ }): Promise<void>;
135
+ private readLeaseRow;
136
+ acquireLease(owner: string, kind: string, ttlMs: number): Promise<boolean>;
137
+ renewLease(owner: string, kind: string, ttlMs: number): Promise<boolean>;
138
+ releaseLease(owner: string, kind: string): Promise<void>;
139
+ getLease(kind: string): Promise<{
140
+ owner: string;
141
+ expiresAt: number;
142
+ } | undefined>;
143
+ close(): Promise<void>;
144
+ reopen(): Promise<void>;
145
+ /**
146
+ * Drop this project's tables. Used by `opencode-rag clear --hard` tooling and
147
+ * by tests; irreversible. Other namespaces are untouched.
148
+ */
149
+ dropProjectTables(): Promise<void>;
150
+ }