opencode-rag-plugin 2.10.0 → 2.11.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.
Files changed (60) hide show
  1. package/ReadMe.md +40 -28
  2. package/dist/api.js +1 -0
  3. package/dist/cli/commands/clickhouse.d.ts +61 -0
  4. package/dist/cli/commands/clickhouse.js +335 -0
  5. package/dist/cli/commands/eval-tuner.js +1 -1
  6. package/dist/cli/commands/eval.js +1 -1
  7. package/dist/cli/commands/index-command.js +2 -1
  8. package/dist/cli/commands/index.d.ts +1 -0
  9. package/dist/cli/commands/index.js +1 -0
  10. package/dist/cli/commands/init-helpers.js +2 -2
  11. package/dist/cli/commands/init.js +49 -11
  12. package/dist/cli/commands/quirk.js +6 -6
  13. package/dist/cli/commands/status.js +70 -6
  14. package/dist/cli/commands/ui.js +2 -2
  15. package/dist/cli/index.js +2 -1
  16. package/dist/cli/types.d.ts +14 -0
  17. package/dist/core/bootstrap.d.ts +7 -0
  18. package/dist/core/bootstrap.js +40 -9
  19. package/dist/core/config.d.ts +128 -5
  20. package/dist/core/config.js +205 -8
  21. package/dist/core/interfaces.d.ts +54 -0
  22. package/dist/core/runtime-overrides.d.ts +9 -0
  23. package/dist/core/runtime-overrides.js +44 -0
  24. package/dist/core/state-sync.d.ts +91 -0
  25. package/dist/core/state-sync.js +273 -0
  26. package/dist/eval/fast-index.js +2 -2
  27. package/dist/eval/rerank-eval.js +2 -2
  28. package/dist/eval/run-branch-compare.js +2 -2
  29. package/dist/eval/run-token-test.js +2 -2
  30. package/dist/index.d.ts +5 -2
  31. package/dist/index.js +2 -1
  32. package/dist/indexer/pipeline.d.ts +32 -0
  33. package/dist/indexer/pipeline.js +230 -65
  34. package/dist/indexer/progress.d.ts +75 -0
  35. package/dist/indexer/progress.js +114 -0
  36. package/dist/indexer/stats.d.ts +14 -0
  37. package/dist/plugin.d.ts +6 -3
  38. package/dist/plugin.js +39 -20
  39. package/dist/quirks/quirk-store.d.ts +10 -0
  40. package/dist/quirks/quirk-store.js +110 -15
  41. package/dist/quirks/types.d.ts +7 -0
  42. package/dist/tui.js +134 -113
  43. package/dist/vectorstore/clickhouse.d.ts +150 -0
  44. package/dist/vectorstore/clickhouse.js +931 -0
  45. package/dist/vectorstore/dimension.d.ts +19 -0
  46. package/dist/vectorstore/dimension.js +36 -0
  47. package/dist/vectorstore/factory.d.ts +9 -3
  48. package/dist/vectorstore/factory.js +11 -2
  49. package/dist/vectorstore/lancedb.d.ts +27 -4
  50. package/dist/vectorstore/lancedb.js +180 -15
  51. package/dist/watcher.d.ts +29 -0
  52. package/dist/watcher.js +76 -2
  53. package/dist/web/api.d.ts +3 -4
  54. package/dist/web/api.js +18 -3
  55. package/dist/web/server.js +28 -2
  56. package/dist/web/ui/assets/index-B-RH6fko.css +2 -0
  57. package/dist/web/ui/index.html +2 -2
  58. package/package.json +2 -1
  59. package/dist/web/ui/assets/index-CWcp0jNf.css +0 -2
  60. /package/dist/web/ui/assets/{index-DbXFrn53.js → index-ChGi2bSp.js} +0 -0
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
@@ -65,20 +65,18 @@ function loadWatcherStatus(storePath) {
65
65
  const statusPath = join(storePath, "watcher-status.json");
66
66
  if (!existsSync(statusPath))
67
67
  return { running: false, lastRunAt: undefined, disabled: true };
68
- try {
69
- const raw = JSON.parse(readFileSync(statusPath, "utf-8"));
70
- return {
71
- running: raw.running === true,
72
- lastRunAt: typeof raw.lastRunAt === "number" ? raw.lastRunAt : undefined,
73
- lastSuccessAt: typeof raw.lastSuccessAt === "number" ? raw.lastSuccessAt : undefined,
74
- lastChangeAt: typeof raw.lastChangeAt === "number" ? raw.lastChangeAt : undefined,
75
- consecutiveFailures: typeof raw.consecutiveFailures === "number" ? raw.consecutiveFailures : undefined,
76
- lastError: typeof raw.lastError === "string" ? raw.lastError : undefined,
77
- };
78
- }
79
- catch {
68
+ // BOM-tolerant read (readJsonFile) - a BOM'd status file must not report "disabled".
69
+ const raw = readJsonFile(statusPath);
70
+ if (!raw)
80
71
  return { running: false, lastRunAt: undefined, disabled: true };
81
- }
72
+ return {
73
+ running: raw.running === true,
74
+ lastRunAt: typeof raw.lastRunAt === "number" ? raw.lastRunAt : undefined,
75
+ lastSuccessAt: typeof raw.lastSuccessAt === "number" ? raw.lastSuccessAt : undefined,
76
+ lastChangeAt: typeof raw.lastChangeAt === "number" ? raw.lastChangeAt : undefined,
77
+ consecutiveFailures: typeof raw.consecutiveFailures === "number" ? raw.consecutiveFailures : undefined,
78
+ lastError: typeof raw.lastError === "string" ? raw.lastError : undefined,
79
+ };
82
80
  }
83
81
  /** True when the watched index may be stale (failed passes or pending changes). */
84
82
  function watcherIsStale(w) {
@@ -86,29 +84,32 @@ function watcherIsStale(w) {
86
84
  return true;
87
85
  return !!(w.lastChangeAt && (!w.lastSuccessAt || w.lastChangeAt > w.lastSuccessAt));
88
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
+ }
89
93
  /**
90
- * Load the full RAG status for a workspace by reading its config and
91
- * 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.
92
98
  */
93
99
  function loadRagStatus(worktree) {
94
100
  const status = { ...DEFAULT_STATUS };
95
- for (const loc of ["opencode-rag.json", ".opencode/opencode-rag.json", ".opencode/rag.json"]) {
96
- const configPath = join(worktree, loc);
97
- if (!existsSync(configPath))
98
- continue;
99
- try {
100
- const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
101
- const embedding = cfg.embedding;
102
- if (embedding) {
103
- status.provider = embedding.provider ?? status.provider;
104
- status.model = embedding.model ?? status.model;
105
- }
106
- const vs = cfg.vectorStore;
107
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
108
- const storePath = resolve(worktree, storeRelPath);
109
- const manifestPath = join(storePath, "manifest.json");
110
- if (existsSync(manifestPath)) {
111
- const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
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) {
112
113
  const files = manifest.files;
113
114
  if (files && typeof files === "object") {
114
115
  status.chunkCount = Object.values(files).reduce((sum, entry) => sum + (entry.chunkCount ?? 0), 0);
@@ -116,12 +117,11 @@ function loadRagStatus(worktree) {
116
117
  status.lastIndexedAt = manifest.lastIndexedAt;
117
118
  status.indexed = status.chunkCount > 0;
118
119
  }
119
- status.watcher = loadWatcherStatus(storePath);
120
- break;
121
- }
122
- catch {
123
- continue;
124
120
  }
121
+ status.watcher = loadWatcherStatus(storePath);
122
+ }
123
+ catch {
124
+ // sidebar stays on DEFAULT_STATUS
125
125
  }
126
126
  return status;
127
127
  }
@@ -154,6 +154,14 @@ function formatKeybinding(key) {
154
154
  .map((k) => k.charAt(0).toUpperCase() + k.slice(1))
155
155
  .join("+");
156
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";
157
165
  const PLUGIN_NAME = "opencode-rag-plugin";
158
166
  /**
159
167
  * Create a TUI element node with the given tag, props, and children.
@@ -209,7 +217,7 @@ function renderSidebar(theme, version, status, tuiConfig, tokenStats) {
209
217
  : undefined;
210
218
  const fileListKey = tuiConfig?.fileListKeybinding ?? "ctrl+enter";
211
219
  const chunksKey = tuiConfig?.chunksKeybinding ?? "ctrl+alt+enter";
212
- const settingsKey = tuiConfig?.settingsKeybinding ?? "ctrl+shift+r";
220
+ const settingsKey = tuiConfig?.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING;
213
221
  return box({
214
222
  width: "100%",
215
223
  flexDirection: "column",
@@ -249,14 +257,39 @@ function renderSidebar(theme, version, status, tuiConfig, tokenStats) {
249
257
  ]);
250
258
  }
251
259
  // ── Settings dialog ────────────────────────────────────────────────
252
- /** Resolve the path to the first existing RAG config file in the worktree. */
253
- function getConfigPath(worktree) {
254
- for (const loc of ["opencode-rag.json", ".opencode/opencode-rag.json", ".opencode/rag.json"]) {
255
- const p = join(worktree, loc);
256
- if (existsSync(p))
257
- 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;
258
290
  }
259
- return undefined;
291
+ saveRuntimeOverride(storePath, [...path], value);
292
+ updateConfigValue(getWritableConfigPath(worktree), [...path], value);
260
293
  }
261
294
  /** Read and parse a JSON file, returning undefined on failure. */
262
295
  function readJsonFile(filePath) {
@@ -345,12 +378,18 @@ function syncWatcherStatusFile(storePath, enabled) {
345
378
  }
346
379
  }
347
380
  /**
348
- * Save a model selection to both runtime overrides and the config file.
349
- * 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.
350
389
  *
351
390
  * @returns The composite "provider/model" string if saved, or undefined for custom.
352
391
  */
353
- function saveModelSelection(storePath, configPath, selectionValue, path, providers) {
392
+ function saveModelSelection(storePath, selectionValue, path, providers) {
354
393
  const section = path[0];
355
394
  if (selectionValue === "__custom__")
356
395
  return undefined;
@@ -362,20 +401,19 @@ function saveModelSelection(storePath, configPath, selectionValue, path, provide
362
401
  const provider = providers?.find((p) => p.id === providerId);
363
402
  const ragProvider = providerIdToRagProvider(providerId);
364
403
  const baseUrl = provider ? resolveProviderBaseUrl(provider) : "";
365
- saveRuntimeOverride(storePath, [section, "provider"], ragProvider);
366
- updateConfigValue(configPath, [section, "provider"], ragProvider);
367
- saveRuntimeOverride(storePath, [section, "model"], modelId);
368
- updateConfigValue(configPath, [section, "model"], modelId);
369
- if (baseUrl) {
370
- saveRuntimeOverride(storePath, [section, "baseUrl"], baseUrl);
371
- updateConfigValue(configPath, [section, "baseUrl"], baseUrl);
372
- }
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);
373
412
  const apiKey = provider?.options?.apiKey ?? "";
374
- if (apiKey) {
375
- // Persist the key only in the store-dir overrides, never in the workspace
376
- // config file — `opencode-rag.json` is routinely committed to git.
377
- saveRuntimeOverride(storePath, [section, "apiKey"], apiKey);
378
- }
413
+ if (apiKey)
414
+ writeProviderOption("apiKey", apiKey);
415
+ else
416
+ deleteRuntimeOverride(storePath, [section, "apiKey"]);
379
417
  return selectionValue;
380
418
  }
381
419
  /**
@@ -648,7 +686,7 @@ function buildSettingCategories(cfg, ro, providers) {
648
686
  path: ["tui", "settingsKeybinding"],
649
687
  label: "Open settings",
650
688
  type: "string",
651
- currentValue: tuiRo.settingsKeybinding ?? tuiCfg.settingsKeybinding ?? "ctrl+shift+r",
689
+ currentValue: tuiRo.settingsKeybinding ?? tuiCfg.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING,
652
690
  },
653
691
  {
654
692
  path: ["tui", "fileListKeybinding"],
@@ -682,13 +720,7 @@ function v2Bind(key) {
682
720
  /** Read token usage statistics from eval session logs (shared by the V2 path). */
683
721
  function readTokenStats(worktree) {
684
722
  try {
685
- const configPath = getConfigPath(worktree);
686
- if (!configPath)
687
- return undefined;
688
- const cfg = loadConfig(configPath);
689
- const vs = cfg.vectorStore;
690
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
691
- const storePath = resolve(worktree, storeRelPath);
723
+ const storePath = resolveStorePath(worktree, loadWorkspaceRawConfig(worktree));
692
724
  const { listSessions } = _require("./eval/storage.js");
693
725
  const sessions = listSessions(storePath);
694
726
  if (sessions.length === 0)
@@ -748,20 +780,19 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
748
780
  return;
749
781
  const { dialog, toast } = ui;
750
782
  const settingsToast = (variant, message) => toast.show({ variant, title: "Settings", message });
751
- const configPath = getConfigPath(worktree);
752
- if (!configPath) {
753
- settingsToast("error", "No config file found");
754
- return;
755
- }
756
- const cfgRaw = readJsonFile(configPath);
757
- if (!cfgRaw) {
758
- settingsToast("error", "Cannot read config");
759
- return;
760
- }
761
- const cfg = cfgRaw;
762
- const vs = cfg.vectorStore;
763
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
764
- 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
+ };
765
796
  const refreshCats = () => buildSettingCategories(cfg, loadRuntimeOverrides(storePath), providers);
766
797
  const warnReindex = (path) => {
767
798
  if (path[0] === "indexing" || path[0] === "chunking")
@@ -821,17 +852,17 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
821
852
  continue;
822
853
  value = custom;
823
854
  }
824
- const saved = saveModelSelection(storePath, configPath, value, entry.path, providers);
855
+ const saved = saveModelSelection(storePath, value, entry.path, providers);
825
856
  if (saved) {
826
857
  entry.currentValue = saved;
827
858
  settingsToast("success", `${entry.label}: ${saved}`);
859
+ settingsToast("info", `Provider option saved to global config: ${globalConfigPath()}`);
828
860
  if (entry.path[0] === "embedding") {
829
- settingsToast("warning", "Embedding changed. Re-index may be required. Restart OpenCode for changes.");
861
+ settingsToast("warning", "Embedding changed. Re-index required for existing chunks.");
830
862
  }
831
863
  }
832
864
  else if (value) {
833
- saveRuntimeOverride(storePath, entry.path, value);
834
- updateConfigValue(configPath, entry.path, value);
865
+ saveSetting(entry.path, value);
835
866
  entry.currentValue = value;
836
867
  }
837
868
  onSettingsChanged?.();
@@ -839,8 +870,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
839
870
  }
840
871
  if (entry.type === "boolean") {
841
872
  const newVal = !entry.currentValue;
842
- saveRuntimeOverride(storePath, entry.path, newVal);
843
- updateConfigValue(configPath, entry.path, newVal);
873
+ saveSetting(entry.path, newVal);
844
874
  settingsToast("success", `${entry.label}: ${newVal ? "Yes" : "No"}`);
845
875
  warnReindex(entry.path);
846
876
  if (entry.path.join(".") === "openCode.autoIndex.enabled") {
@@ -864,8 +894,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
864
894
  settingsToast("error", "Enter a valid number");
865
895
  continue;
866
896
  }
867
- saveRuntimeOverride(storePath, entry.path, num);
868
- updateConfigValue(configPath, entry.path, num);
897
+ saveSetting(entry.path, num);
869
898
  settingsToast("success", `${entry.label}: ${num}`);
870
899
  warnReindex(entry.path);
871
900
  entry.currentValue = num;
@@ -878,8 +907,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
878
907
  settingsToast("error", "Value must be a JSON object");
879
908
  continue;
880
909
  }
881
- saveRuntimeOverride(storePath, entry.path, parsed);
882
- updateConfigValue(configPath, entry.path, parsed);
910
+ saveSetting(entry.path, parsed);
883
911
  settingsToast("success", `${entry.label}: updated`);
884
912
  warnReindex(entry.path);
885
913
  entry.currentValue = parsed;
@@ -890,8 +918,7 @@ async function openSettingsDialogV2(context, worktree, providers, onSettingsChan
890
918
  }
891
919
  }
892
920
  else {
893
- saveRuntimeOverride(storePath, entry.path, raw);
894
- updateConfigValue(configPath, entry.path, raw);
921
+ saveSetting(entry.path, raw);
895
922
  settingsToast("success", `${entry.label}: ${raw}`);
896
923
  entry.currentValue = raw;
897
924
  onSettingsChanged?.();
@@ -923,14 +950,14 @@ async function setup(context) {
923
950
  let lastRefresh = 0;
924
951
  const REFRESH_INTERVAL_MS = Number(process.env.OPENCODE_RAG_TUI_REFRESH_MS) || 30000;
925
952
  let tuiConfig;
926
- const tuiConfigPath = worktree ? getConfigPath(worktree) : undefined;
927
- if (tuiConfigPath) {
928
- try {
929
- tuiConfig = loadConfig(tuiConfigPath).tui;
930
- }
931
- catch {
932
- // use defaults
933
- }
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
+ };
934
961
  }
935
962
  /** Refresh the cached RAG status from disk. */
936
963
  function refreshStatus() {
@@ -955,19 +982,13 @@ async function setup(context) {
955
982
  let flagStorePath;
956
983
  if (worktree) {
957
984
  try {
958
- const flagConfigPath = getConfigPath(worktree);
959
- if (flagConfigPath) {
960
- const flagCfg = loadConfig(flagConfigPath);
961
- const vs = flagCfg.vectorStore;
962
- const storeRelPath = vs?.path ?? ".opencode/rag_db";
963
- flagStorePath = resolve(worktree, storeRelPath);
964
- }
985
+ flagStorePath = resolveStorePath(worktree, rawCfg);
965
986
  }
966
987
  catch {
967
988
  // ignore
968
989
  }
969
990
  }
970
- const settingsKey = tuiConfig?.settingsKeybinding ?? "ctrl+shift+r";
991
+ const settingsKey = tuiConfig?.settingsKeybinding ?? DEFAULT_SETTINGS_KEYBINDING;
971
992
  const fileListKey = tuiConfig?.fileListKeybinding ?? "ctrl+enter";
972
993
  const chunksKey = tuiConfig?.chunksKeybinding ?? "ctrl+alt+enter";
973
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
+ }