opencode-rag-plugin 2.10.1 → 2.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/ReadMe.md +40 -28
  2. package/dist/api.js +1 -0
  3. package/dist/chunker/grammar.d.ts +4 -1
  4. package/dist/chunker/grammar.js +9 -3
  5. package/dist/chunker/skeleton.js +61 -4
  6. package/dist/cli/commands/clickhouse.d.ts +61 -0
  7. package/dist/cli/commands/clickhouse.js +335 -0
  8. package/dist/cli/commands/eval-tuner.js +1 -1
  9. package/dist/cli/commands/eval.js +1 -1
  10. package/dist/cli/commands/index-command.js +2 -1
  11. package/dist/cli/commands/index.d.ts +1 -0
  12. package/dist/cli/commands/index.js +1 -0
  13. package/dist/cli/commands/init-helpers.js +2 -2
  14. package/dist/cli/commands/init.js +49 -11
  15. package/dist/cli/commands/quirk.js +6 -6
  16. package/dist/cli/commands/status.js +70 -6
  17. package/dist/cli/commands/ui.js +2 -2
  18. package/dist/cli/index.js +2 -1
  19. package/dist/cli/types.d.ts +14 -0
  20. package/dist/core/bootstrap.d.ts +7 -0
  21. package/dist/core/bootstrap.js +40 -9
  22. package/dist/core/config.d.ts +128 -5
  23. package/dist/core/config.js +205 -8
  24. package/dist/core/interfaces.d.ts +54 -0
  25. package/dist/core/runtime-overrides.d.ts +9 -0
  26. package/dist/core/runtime-overrides.js +44 -0
  27. package/dist/core/state-sync.d.ts +91 -0
  28. package/dist/core/state-sync.js +273 -0
  29. package/dist/eval/fast-index.js +2 -2
  30. package/dist/eval/rerank-eval.js +2 -2
  31. package/dist/eval/run-branch-compare.js +2 -2
  32. package/dist/eval/run-token-test.js +2 -2
  33. package/dist/index.d.ts +5 -2
  34. package/dist/index.js +2 -1
  35. package/dist/indexer/pipeline.d.ts +6 -0
  36. package/dist/indexer/pipeline.js +173 -56
  37. package/dist/indexer/progress.d.ts +75 -0
  38. package/dist/indexer/progress.js +114 -0
  39. package/dist/indexer/stats.d.ts +14 -0
  40. package/dist/plugin.d.ts +6 -3
  41. package/dist/plugin.js +39 -20
  42. package/dist/quirks/quirk-store.d.ts +10 -0
  43. package/dist/quirks/quirk-store.js +110 -15
  44. package/dist/quirks/types.d.ts +7 -0
  45. package/dist/tui.js +128 -111
  46. package/dist/vectorstore/clickhouse.d.ts +150 -0
  47. package/dist/vectorstore/clickhouse.js +931 -0
  48. package/dist/vectorstore/dimension.d.ts +19 -0
  49. package/dist/vectorstore/dimension.js +36 -0
  50. package/dist/vectorstore/factory.d.ts +9 -3
  51. package/dist/vectorstore/factory.js +11 -2
  52. package/dist/vectorstore/lancedb.d.ts +2 -2
  53. package/dist/watcher.d.ts +29 -0
  54. package/dist/watcher.js +76 -2
  55. package/dist/web/api.d.ts +3 -4
  56. package/dist/web/api.js +18 -3
  57. package/dist/web/server.js +28 -2
  58. package/dist/web/ui/assets/{ScatterPlot3D-CKwyh1Ec.js → ScatterPlot3D-XjXIwavM.js} +5 -5
  59. package/dist/web/ui/assets/index-B-RH6fko.css +2 -0
  60. package/dist/web/ui/assets/index-FFPRbgLx.js +4 -0
  61. package/dist/web/ui/index.html +2 -2
  62. package/package.json +7 -2
  63. package/dist/web/ui/assets/index-CWcp0jNf.css +0 -2
  64. package/dist/web/ui/assets/index-DbXFrn53.js +0 -4
@@ -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 {};