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
@@ -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
  *
@@ -2,7 +2,7 @@
2
2
  * @fileoverview Configuration types and defaults for OpenCodeRAG. Defines RagConfig,
3
3
  * all sub-config interfaces, DEFAULT_CONFIG, validateConfig, and loadConfig.
4
4
  */
5
- import { existsSync, readFileSync, writeFileSync } from "node:fs";
5
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
6
6
  import path from "node:path";
7
7
  import { homedir } from "node:os";
8
8
  import { env } from "node:process";
@@ -127,6 +127,23 @@ export const DEFAULT_CONFIG = {
127
127
  vectorStore: {
128
128
  path: "./.opencode/rag_db",
129
129
  provider: "lancedb",
130
+ clickhouse: {
131
+ url: "http://localhost:8123",
132
+ database: "OpenCodeRAG",
133
+ username: "default",
134
+ password: "",
135
+ passwordEnv: "OPENCODERAG_CLICKHOUSE_PASSWORD",
136
+ namespace: "",
137
+ requestTimeoutMs: 30_000,
138
+ maxOpenConnections: 10,
139
+ compression: true,
140
+ state: { syncDescCache: false },
141
+ lease: { enabled: true, ttlSeconds: 90 },
142
+ diskFreeFloorBytes: 5 * 1024 * 1024 * 1024,
143
+ ann: "off",
144
+ annFetchMultiplier: 4,
145
+ annWithRescoring: true,
146
+ },
130
147
  },
131
148
  retrieval: {
132
149
  topK: 20,
@@ -360,7 +377,7 @@ export const DEFAULT_CONFIG = {
360
377
  tui: {
361
378
  fileListKeybinding: "ctrl+enter",
362
379
  chunksKeybinding: "ctrl+alt+enter",
363
- settingsKeybinding: "ctrl+shift+r",
380
+ settingsKeybinding: "alt+s",
364
381
  },
365
382
  logging: {
366
383
  level: "info",
@@ -401,6 +418,47 @@ export function validateConfig(config) {
401
418
  catch {
402
419
  warnings.push(`embedding.baseUrl "${config.embedding.baseUrl}" is not a valid URL`);
403
420
  }
421
+ const vectorProvider = config.vectorStore.provider ?? "lancedb";
422
+ if (!["lancedb", "memory", "clickhouse"].includes(vectorProvider)) {
423
+ warnings.push(`vectorStore.provider "${vectorProvider}" — expected "lancedb", "memory" or "clickhouse"`);
424
+ }
425
+ if (vectorProvider === "clickhouse") {
426
+ const ch = config.vectorStore.clickhouse;
427
+ if (!ch) {
428
+ warnings.push("vectorStore.clickhouse settings are required when provider is \"clickhouse\"");
429
+ }
430
+ else {
431
+ try {
432
+ new URL(ch.url);
433
+ }
434
+ catch {
435
+ warnings.push(`vectorStore.clickhouse.url "${ch.url}" is not a valid URL`);
436
+ }
437
+ if (!ch.database)
438
+ warnings.push("vectorStore.clickhouse.database must not be empty");
439
+ if (!ch.username)
440
+ warnings.push("vectorStore.clickhouse.username must not be empty");
441
+ if (ch.password && !ch.passwordEnv) {
442
+ warnings.push("vectorStore.clickhouse.password is stored in plaintext — prefer passwordEnv");
443
+ }
444
+ if (ch.namespace && !/^[A-Za-z0-9_]{1,40}$/.test(ch.namespace)) {
445
+ warnings.push("vectorStore.clickhouse.namespace may only contain letters, digits and underscores (max 40)");
446
+ }
447
+ if (ch.ann === "hnsw") {
448
+ // The index is dimension-bound; the store refuses to switch dimensions
449
+ // until its tables are dropped and rebuilt.
450
+ if (ch.annFetchMultiplier != null && (ch.annFetchMultiplier < 1 || ch.annFetchMultiplier > 1000)) {
451
+ warnings.push("vectorStore.clickhouse.annFetchMultiplier must be between 1 and 1000");
452
+ }
453
+ }
454
+ if (ch.requestTimeoutMs != null && ch.requestTimeoutMs <= 0) {
455
+ warnings.push("vectorStore.clickhouse.requestTimeoutMs must be > 0");
456
+ }
457
+ if (ch.lease?.ttlSeconds != null && ch.lease.ttlSeconds < 10) {
458
+ warnings.push("vectorStore.clickhouse.lease.ttlSeconds must be >= 10");
459
+ }
460
+ }
461
+ }
404
462
  if (config.indexing.chunkOverlap < 0) {
405
463
  warnings.push("indexing.chunkOverlap must be >= 0");
406
464
  }
@@ -645,10 +703,18 @@ export function validateConfig(config) {
645
703
  }
646
704
  return { valid: warnings.length === 0, warnings };
647
705
  }
648
- /** Config file locations to search, in order of precedence. */
706
+ /**
707
+ * Config file locations to search, in order of precedence.
708
+ *
709
+ * `.opencode/opencode-rag.json` is the canonical workspace location — every
710
+ * writer (TUI, `init`, `clickhouse setup`, the Web UI) creates and updates it
711
+ * there. The root-level `opencode-rag.json` is the legacy location, still read
712
+ * for compatibility (and migrated into `.opencode/` by `opencode-rag init`);
713
+ * `.opencode/rag.json` is a legacy alias inside `.opencode/`.
714
+ */
649
715
  export const CONFIG_FILE_CANDIDATES = [
650
- "opencode-rag.json",
651
716
  ".opencode/opencode-rag.json",
717
+ "opencode-rag.json",
652
718
  ".opencode/rag.json",
653
719
  ];
654
720
  /**
@@ -682,6 +748,97 @@ export function findGlobalConfigFile(envVars = env, homeDir = homedir()) {
682
748
  const candidate = globalConfigPath(envVars, homeDir);
683
749
  return existsSync(candidate) ? candidate : undefined;
684
750
  }
751
+ /**
752
+ * The canonical workspace config path `<directory>/.opencode/opencode-rag.json`.
753
+ * Exists or not — this is where writers CREATE the workspace config, keeping
754
+ * the project root clean. Use {@link findConfigFile} to read the effective one.
755
+ */
756
+ export function projectConfigPath(directory) {
757
+ return path.join(directory, ".opencode", "opencode-rag.json");
758
+ }
759
+ /**
760
+ * Move a legacy root-level `opencode-rag.json` into `.opencode/`.
761
+ *
762
+ * Only runs when the legacy file exists and the canonical file does not — an
763
+ * existing `.opencode/opencode-rag.json` always wins, so the legacy file is
764
+ * left alone rather than silently merged.
765
+ *
766
+ * @returns The new path when the file was moved, otherwise undefined.
767
+ */
768
+ export function migrateLegacyProjectConfig(directory) {
769
+ const legacy = path.join(directory, "opencode-rag.json");
770
+ const target = projectConfigPath(directory);
771
+ if (!existsSync(legacy) || existsSync(target))
772
+ return undefined;
773
+ try {
774
+ mkdirSync(path.dirname(target), { recursive: true });
775
+ renameSync(legacy, target);
776
+ return target;
777
+ }
778
+ catch {
779
+ return undefined;
780
+ }
781
+ }
782
+ /** Create an empty (`{}`) config file — and its parent directory — when absent. */
783
+ export function ensureConfigFile(filePath) {
784
+ if (existsSync(filePath))
785
+ return;
786
+ mkdirSync(path.dirname(filePath), { recursive: true });
787
+ writeFileSync(filePath, "{}", "utf-8");
788
+ }
789
+ /**
790
+ * Write a value into the machine-global config file, creating it on demand.
791
+ *
792
+ * Provider options (embedding/description/... provider, model, baseUrl,
793
+ * apiKey) describe which models THIS MACHINE serves, not what the repository
794
+ * is, so they belong here rather than in a per-project file — and the global
795
+ * file is never committed, making it safe for API keys. The plugin re-reads
796
+ * this layer by mtime, so changes apply without a restart.
797
+ */
798
+ export function updateGlobalConfigValue(path_, value) {
799
+ try {
800
+ ensureConfigFile(globalConfigPath());
801
+ }
802
+ catch {
803
+ return false;
804
+ }
805
+ return updateConfigValue(globalConfigPath(), [...path_], value);
806
+ }
807
+ /** Config sections whose model/endpoint settings are machine-global provider options. */
808
+ const PROVIDER_OPTION_SECTIONS = new Set([
809
+ "embedding",
810
+ "description",
811
+ "imageDescription",
812
+ "decision",
813
+ "reranking",
814
+ ]);
815
+ /** Leaf keys that select or authenticate a provider/model. */
816
+ const PROVIDER_OPTION_LEAVES = new Set([
817
+ "provider",
818
+ "model",
819
+ "baseUrl",
820
+ "apiKey",
821
+ "vectorDimension",
822
+ ]);
823
+ /**
824
+ * Whether a dotted config path is a machine-global provider option
825
+ * (section ∈ {@link PROVIDER_OPTION_SECTIONS}, leaf ∈ {@link PROVIDER_OPTION_LEAVES};
826
+ * `imageDescription.onDemand.*` counts via the `onDemand` group).
827
+ *
828
+ * Writers route these to {@link updateGlobalConfigValue} so provider/model/
829
+ * key/baseUrl never land in a per-project config file; every other path stays
830
+ * project-scoped.
831
+ */
832
+ export function isProviderScopedPath(path_) {
833
+ if (path_.length < 2)
834
+ return false;
835
+ if (!PROVIDER_OPTION_SECTIONS.has(path_[0]))
836
+ return false;
837
+ const segments = path_[0] === "imageDescription" && path_[1] === "onDemand" ? path_.slice(2) : path_.slice(1);
838
+ const leaf = segments[segments.length - 1];
839
+ return leaf !== undefined && segments.every((s) => PROVIDER_OPTION_LEAVES.has(s) || s === "onDemand")
840
+ && PROVIDER_OPTION_LEAVES.has(leaf);
841
+ }
685
842
  /** Config layers that apply to a workspace (lowest precedence first). */
686
843
  export function resolveConfigPaths(directory) {
687
844
  return { global: findGlobalConfigFile(), workspace: findConfigFile(directory) };
@@ -755,6 +912,28 @@ export function loadWorkspaceConfig(directory, validate = true) {
755
912
  const layers = [global, workspace].filter((p) => p !== undefined);
756
913
  return loadConfigLayers(layers, validate);
757
914
  }
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 function loadWorkspaceRawConfig(directory) {
923
+ const { global, workspace } = resolveConfigPaths(directory);
924
+ let merged = {};
925
+ for (const filePath of [global, workspace]) {
926
+ if (!filePath)
927
+ continue;
928
+ try {
929
+ merged = mergeConfigObjects(merged, parseConfigFile(filePath));
930
+ }
931
+ catch {
932
+ // skip a malformed layer; keep whatever the healthy layers contributed
933
+ }
934
+ }
935
+ return merged;
936
+ }
758
937
  /**
759
938
  * Top-level sections that a workspace actually configures.
760
939
  *
@@ -793,10 +972,28 @@ function buildConfig(parsed, validate) {
793
972
  ...DEFAULT_CONFIG.indexing,
794
973
  ...parsed.indexing,
795
974
  },
796
- vectorStore: {
797
- ...DEFAULT_CONFIG.vectorStore,
798
- ...parsed.vectorStore,
799
- },
975
+ vectorStore: (() => {
976
+ const base = DEFAULT_CONFIG.vectorStore;
977
+ const user = (safeObj(parsed.vectorStore) ?? {});
978
+ const chBase = base.clickhouse;
979
+ const chUser = (safeObj(user.clickhouse) ?? {});
980
+ return {
981
+ ...base,
982
+ ...user,
983
+ clickhouse: {
984
+ ...chBase,
985
+ ...chUser,
986
+ state: {
987
+ ...chBase.state,
988
+ ...(safeObj(chUser.state) ?? {}),
989
+ },
990
+ lease: {
991
+ ...chBase.lease,
992
+ ...(safeObj(chUser.lease) ?? {}),
993
+ },
994
+ },
995
+ };
996
+ })(),
800
997
  retrieval: {
801
998
  ...DEFAULT_CONFIG.retrieval,
802
999
  ...parsed.retrieval,
@@ -361,6 +361,60 @@ export interface VectorStore {
361
361
  * writes, so the pipeline rebuilds the index instead.
362
362
  */
363
363
  getVectorDimension?(): Promise<number | undefined>;
364
+ /**
365
+ * Start a full rebuild into a private target and return the handle that
366
+ * should receive the new chunks. Stores that support atomic promotion
367
+ * (ClickHouse epochs) implement this; stores that do not keep the
368
+ * pipeline's temporary-directory path. `promoteRebuild` makes the new data
369
+ * visible, `discardRebuild` leaves the current data untouched.
370
+ */
371
+ beginRebuild?(): Promise<VectorStore>;
372
+ /** Make the target created by `beginRebuild` visible (atomic where supported). */
373
+ promoteRebuild?(): Promise<void>;
374
+ /** Abandon the target created by `beginRebuild`, keeping the current data. */
375
+ discardRebuild?(): Promise<void>;
376
+ /**
377
+ * Advisory single-writer lease for a workspace namespace, used to keep two
378
+ * machines from running an index pass (or watcher) against the same store
379
+ * at the same time. Machines without a lease primitive keep their local
380
+ * file locks.
381
+ */
382
+ acquireLease?(owner: string, kind: string, ttlMs: number): Promise<boolean>;
383
+ /** Extend a lease held by `owner`. Returns false when it was lost. */
384
+ renewLease?(owner: string, kind: string, ttlMs: number): Promise<boolean>;
385
+ /** Release a lease held by `owner` (best effort). */
386
+ releaseLease?(owner: string, kind: string): Promise<void>;
387
+ /** Read the current lease holder for diagnostics. */
388
+ getLease?(kind: string): Promise<{
389
+ owner: string;
390
+ expiresAt: number;
391
+ } | undefined>;
392
+ }
393
+ /**
394
+ * A `VectorStore` that can also serve the web UI's browse endpoints. The
395
+ * methods are separate from `VectorStore` so lightweight test doubles and the
396
+ * in-memory store do not have to implement pagination/count queries.
397
+ */
398
+ export interface ChunkBrowseStore extends VectorStore {
399
+ /** Retrieve a paginated list of chunks, optionally filtered by language or file-path prefix. */
400
+ getChunksFiltered(offset: number, limit: number, lang?: string, filePrefix?: string): Promise<{
401
+ chunks: ChunkSummary[];
402
+ total: number;
403
+ }>;
404
+ /** Look up a single chunk by its ID. Returns undefined when not found. */
405
+ getChunkById(id: string): Promise<ChunkSummary | undefined>;
406
+ /** Fetch chunks by their IDs (bounded to 100 ids). */
407
+ getChunksByIds(ids: string[]): Promise<ChunkSummary[]>;
408
+ /** Fetch chunks with their embedding vectors included (for embedding projection). */
409
+ getChunksWithEmbeddings(limit: number): Promise<{
410
+ id: string;
411
+ filePath: string;
412
+ language: string;
413
+ startLine: number;
414
+ endLine: number;
415
+ description: string;
416
+ embedding: number[];
417
+ }[]>;
364
418
  }
365
419
  /** Filter criteria for narrowing search results by file path, language, kind, or extension. */
366
420
  export interface MetadataFilter {
@@ -66,5 +66,14 @@ export interface RuntimeOverrides {
66
66
  export declare function loadRuntimeOverrides(storePath: string): RuntimeOverrides;
67
67
  /** Save a single runtime override value at a dotted path. Creates intermediate objects as needed. */
68
68
  export declare function saveRuntimeOverride(storePath: string, path: string[], value: boolean | number | string | Record<string, unknown>): void;
69
+ /**
70
+ * Remove a runtime override at a dotted path.
71
+ *
72
+ * Used when an option's persisted home moves (provider options now live in
73
+ * the global config file): a stale override here would silently shadow the
74
+ * file value forever. Prunes parent objects left empty; tolerates missing
75
+ * intermediate keys.
76
+ */
77
+ export declare function deleteRuntimeOverride(storePath: string, path: string[]): void;
69
78
  /** Deep-merge runtime overrides into a config object. Returns a new object without mutating the original. */
70
79
  export declare function applyRuntimeOverrides(cfg: RagConfig, overrides: RuntimeOverrides): RagConfig;
@@ -43,6 +43,50 @@ export function saveRuntimeOverride(storePath, path, value) {
43
43
  // silently ignore write errors
44
44
  }
45
45
  }
46
+ /**
47
+ * Remove a runtime override at a dotted path.
48
+ *
49
+ * Used when an option's persisted home moves (provider options now live in
50
+ * the global config file): a stale override here would silently shadow the
51
+ * file value forever. Prunes parent objects left empty; tolerates missing
52
+ * intermediate keys.
53
+ */
54
+ export function deleteRuntimeOverride(storePath, path) {
55
+ const overridePath = join(storePath, "runtime-overrides.json");
56
+ if (!existsSync(overridePath) || path.length === 0)
57
+ return;
58
+ const overrides = loadRuntimeOverrides(storePath);
59
+ const ancestors = [];
60
+ let target = overrides;
61
+ for (const key of path.slice(0, -1)) {
62
+ const next = target[key];
63
+ if (!next || typeof next !== "object" || Array.isArray(next))
64
+ return; // nothing to delete
65
+ ancestors.push(target);
66
+ target = next;
67
+ }
68
+ const leaf = path[path.length - 1];
69
+ if (!(leaf in target))
70
+ return;
71
+ delete target[leaf];
72
+ // Prune containers that became empty, deepest first (never the root).
73
+ for (let i = ancestors.length - 1; i >= 0; i--) {
74
+ const parent = ancestors[i];
75
+ const child = ancestors[i + 1] ? parent[path[i]] : target;
76
+ if (child && typeof child === "object" && Object.keys(child).length === 0) {
77
+ delete parent[path[i]];
78
+ }
79
+ else {
80
+ break;
81
+ }
82
+ }
83
+ try {
84
+ writeFileSync(overridePath, JSON.stringify(overrides, null, 2), "utf-8");
85
+ }
86
+ catch {
87
+ // silently ignore write errors
88
+ }
89
+ }
46
90
  /** Deep-merge runtime overrides into a config object. Returns a new object without mutating the original. */
47
91
  export function applyRuntimeOverrides(cfg, overrides) {
48
92
  if (!overrides || Object.keys(overrides).length === 0)
@@ -0,0 +1,91 @@
1
+ import type { RagConfig } from "./config.js";
2
+ import type { VectorStore } from "./interfaces.js";
3
+ /** State names and their local cache files. */
4
+ declare const STATE_FILES: {
5
+ readonly manifest: {
6
+ readonly file: "manifest.json";
7
+ readonly required: true;
8
+ };
9
+ readonly "keyword-index": {
10
+ readonly file: "keyword-index.json";
11
+ readonly required: false;
12
+ };
13
+ readonly quirks: {
14
+ readonly file: "quirks.jsonl";
15
+ readonly required: false;
16
+ readonly merge: true;
17
+ };
18
+ readonly "runtime-overrides": {
19
+ readonly file: "runtime-overrides.json";
20
+ readonly required: false;
21
+ };
22
+ readonly "doc-progress": {
23
+ readonly file: "doc-progress.json";
24
+ readonly required: false;
25
+ };
26
+ readonly ".desc-cache": {
27
+ readonly file: ".desc-cache.json";
28
+ readonly required: false;
29
+ readonly cache: true;
30
+ };
31
+ };
32
+ type StateName = keyof typeof STATE_FILES;
33
+ interface SyncRecord {
34
+ sha256: string;
35
+ }
36
+ interface SyncVersions {
37
+ [name: string]: SyncRecord | undefined;
38
+ }
39
+ export interface StateSyncOptions {
40
+ store: VectorStore;
41
+ /** Local cache directory (`vectorStore.path`). */
42
+ storePath: string;
43
+ config: RagConfig;
44
+ /** Optional logger override (tests). */
45
+ warn?: (message: string) => void;
46
+ }
47
+ /**
48
+ * Merge two JSONL quirk logs by id, keeping the record with the later
49
+ * `lastObserved` (falling back to the later `updatedAt`, then the local copy).
50
+ *
51
+ * A record carrying `deletedAt` is a deletion tombstone: it is final. A live
52
+ * record never overrides a tombstone (quirk ids are never reused, so any live
53
+ * copy of a deleted id is stale), which is what makes the union propagate a
54
+ * deletion instead of resurrecting it.
55
+ *
56
+ * Output is sorted by id so identical inputs hash identically.
57
+ */
58
+ export declare function mergeQuirkJsonl(local: string, remote: string): string;
59
+ /**
60
+ * Synchronise the durable workspace state with a central store.
61
+ *
62
+ * Inactive (a no-op) for every provider except `"clickhouse"`.
63
+ */
64
+ export declare class StateSync {
65
+ private readonly storePath;
66
+ private readonly enabled;
67
+ private readonly syncDescCache;
68
+ private readonly warn;
69
+ private readonly remote;
70
+ constructor(options: StateSyncOptions);
71
+ /** True when this instance actually talks to a central state table. */
72
+ get active(): boolean;
73
+ private entries;
74
+ private versionsPath;
75
+ private loadVersions;
76
+ private saveVersions;
77
+ private localPath;
78
+ /**
79
+ * Pull durable state into the local cache. Call before anything reads the
80
+ * manifest/keyword index/quirks (bootstrap does this).
81
+ */
82
+ hydrate(): Promise<void>;
83
+ /**
84
+ * Upload changed state files. No-op names are ignored.
85
+ *
86
+ * @param names - State names to flush; defaults to every syncable file.
87
+ * @param existingVersions - Reuse a versions map already loaded by `hydrate`.
88
+ */
89
+ flush(names?: StateName[], existingVersions?: SyncVersions): Promise<void>;
90
+ }
91
+ export {};