opencode-rag-plugin 2.10.1 → 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.
- package/ReadMe.md +40 -28
- package/dist/api.js +1 -0
- package/dist/cli/commands/clickhouse.d.ts +61 -0
- package/dist/cli/commands/clickhouse.js +335 -0
- package/dist/cli/commands/eval-tuner.js +1 -1
- package/dist/cli/commands/eval.js +1 -1
- package/dist/cli/commands/index-command.js +2 -1
- package/dist/cli/commands/index.d.ts +1 -0
- package/dist/cli/commands/index.js +1 -0
- package/dist/cli/commands/init-helpers.js +2 -2
- package/dist/cli/commands/init.js +49 -11
- package/dist/cli/commands/quirk.js +6 -6
- package/dist/cli/commands/status.js +70 -6
- package/dist/cli/commands/ui.js +2 -2
- package/dist/cli/index.js +2 -1
- package/dist/cli/types.d.ts +14 -0
- package/dist/core/bootstrap.d.ts +7 -0
- package/dist/core/bootstrap.js +40 -9
- package/dist/core/config.d.ts +128 -5
- package/dist/core/config.js +205 -8
- package/dist/core/interfaces.d.ts +54 -0
- package/dist/core/runtime-overrides.d.ts +9 -0
- package/dist/core/runtime-overrides.js +44 -0
- package/dist/core/state-sync.d.ts +91 -0
- package/dist/core/state-sync.js +273 -0
- package/dist/eval/fast-index.js +2 -2
- package/dist/eval/rerank-eval.js +2 -2
- package/dist/eval/run-branch-compare.js +2 -2
- package/dist/eval/run-token-test.js +2 -2
- package/dist/index.d.ts +5 -2
- package/dist/index.js +2 -1
- package/dist/indexer/pipeline.d.ts +6 -0
- package/dist/indexer/pipeline.js +173 -56
- package/dist/indexer/progress.d.ts +75 -0
- package/dist/indexer/progress.js +114 -0
- package/dist/indexer/stats.d.ts +14 -0
- package/dist/plugin.d.ts +6 -3
- package/dist/plugin.js +39 -20
- package/dist/quirks/quirk-store.d.ts +10 -0
- package/dist/quirks/quirk-store.js +110 -15
- package/dist/quirks/types.d.ts +7 -0
- package/dist/tui.js +128 -111
- package/dist/vectorstore/clickhouse.d.ts +150 -0
- package/dist/vectorstore/clickhouse.js +931 -0
- package/dist/vectorstore/dimension.d.ts +19 -0
- package/dist/vectorstore/dimension.js +36 -0
- package/dist/vectorstore/factory.d.ts +9 -3
- package/dist/vectorstore/factory.js +11 -2
- package/dist/vectorstore/lancedb.d.ts +2 -2
- package/dist/watcher.d.ts +29 -0
- package/dist/watcher.js +76 -2
- package/dist/web/api.d.ts +3 -4
- package/dist/web/api.js +18 -3
- package/dist/web/server.js +28 -2
- package/dist/web/ui/assets/index-B-RH6fko.css +2 -0
- package/dist/web/ui/index.html +2 -2
- package/package.json +2 -1
- package/dist/web/ui/assets/index-CWcp0jNf.css +0 -2
- /package/dist/web/ui/assets/{index-DbXFrn53.js → index-ChGi2bSp.js} +0 -0
package/dist/core/config.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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 "
|
|
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
|
-
/**
|
|
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
|
*
|
package/dist/core/config.js
CHANGED
|
@@ -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: "
|
|
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
|
-
/**
|
|
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
|
-
|
|
798
|
-
|
|
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 {};
|