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
@@ -0,0 +1,335 @@
1
+ import path from "node:path";
2
+ import { copyFileSync, existsSync, mkdirSync } from "node:fs";
3
+ import { createInterface } from "node:readline/promises";
4
+ import { loadWorkspaceConfig, globalConfigPath, findConfigFile, projectConfigPath } from "../../core/config.js";
5
+ import { ClickHouseStore, deriveNamespace, resolveClickHouseOptions, sanitizeNamespace, } from "../../vectorstore/clickhouse.js";
6
+ import { readJsonObject, writeJsonFile } from "../helpers.js";
7
+ import { c } from "../format.js";
8
+ /**
9
+ * Merge a ClickHouse `vectorStore` block into an existing config object.
10
+ * Exported for tests; preserves every unrelated top-level key and the old
11
+ * cache path when ClickHouse was already active.
12
+ */
13
+ export function mergeClickHouseConfig(existing, input) {
14
+ const base = existing ?? {};
15
+ const current = (base.vectorStore ?? {});
16
+ const currentClickhouse = (current.clickhouse ?? {});
17
+ const cachePath = current.provider === "clickhouse" && typeof current.path === "string"
18
+ ? current.path
19
+ : "./.opencode/rag_ch";
20
+ const clickhouse = {
21
+ ...currentClickhouse,
22
+ url: input.url,
23
+ database: input.database,
24
+ username: input.username,
25
+ };
26
+ delete clickhouse.password;
27
+ if (input.storeInlinePassword && input.password)
28
+ clickhouse.password = input.password;
29
+ if (input.passwordEnv)
30
+ clickhouse.passwordEnv = input.passwordEnv;
31
+ else
32
+ delete clickhouse.passwordEnv;
33
+ if (input.namespace)
34
+ clickhouse.namespace = sanitizeNamespace(input.namespace);
35
+ else
36
+ delete clickhouse.namespace;
37
+ clickhouse.ann = input.ann;
38
+ if (input.ann === "hnsw") {
39
+ clickhouse.annFetchMultiplier = 4;
40
+ clickhouse.annWithRescoring = true;
41
+ }
42
+ return {
43
+ ...base,
44
+ vectorStore: {
45
+ ...current,
46
+ path: cachePath,
47
+ provider: "clickhouse",
48
+ clickhouse,
49
+ },
50
+ };
51
+ }
52
+ /** Parse "major.minor.patch.build" into a comparable pair. */
53
+ function parseVersion(version) {
54
+ const parts = version.split(".").map((part) => Number.parseInt(part, 10));
55
+ const major = parts[0];
56
+ const minor = parts[1];
57
+ return {
58
+ major: major !== undefined && Number.isFinite(major) ? major : 0,
59
+ minor: minor !== undefined && Number.isFinite(minor) ? minor : 0,
60
+ };
61
+ }
62
+ /** ClickHouse >= 25.8 has the `vector_similarity` HNSW index. */
63
+ function supportsAnn(version) {
64
+ const { major, minor } = parseVersion(version);
65
+ return major > 25 || (major === 25 && minor >= 8);
66
+ }
67
+ /** Prompt for a line with a default value. */
68
+ async function promptLine(rl, question, fallback) {
69
+ const answer = (await rl.question(`${question}${fallback ? ` [${fallback}]` : ""}: `)).trim();
70
+ return answer.length > 0 ? answer : fallback;
71
+ }
72
+ /**
73
+ * Prompt for a password without echoing it.
74
+ *
75
+ * Readline's internal `_writeToOutput` hook is muted while the answer is read —
76
+ * an active readline interface otherwise echoes every keystroke, even when the
77
+ * caller switches the stream to raw mode.
78
+ */
79
+ export async function promptHidden(rl, question) {
80
+ const mutable = rl;
81
+ const original = mutable._writeToOutput;
82
+ process.stdout.write(question);
83
+ if (typeof mutable._writeToOutput === "function") {
84
+ mutable._writeToOutput = () => { };
85
+ }
86
+ try {
87
+ return (await rl.question("")).trim();
88
+ }
89
+ finally {
90
+ mutable._writeToOutput = original;
91
+ process.stdout.write("\n");
92
+ }
93
+ }
94
+ /** Compose `scheme://host:port` from a user-supplied URL and port. */
95
+ export function composeClickHouseUrl(rawUrl, port) {
96
+ const parsed = new URL(rawUrl);
97
+ if (port.trim())
98
+ parsed.port = port.trim();
99
+ return parsed.toString().replace(/\/+$/, "");
100
+ }
101
+ /** Probe the server and return its version, or throw a readable error. */
102
+ async function probeServer(url, username, password) {
103
+ const { createClient } = await import("@clickhouse/client");
104
+ const client = createClient({
105
+ url,
106
+ username,
107
+ password,
108
+ database: "default",
109
+ request_timeout: 10_000,
110
+ });
111
+ try {
112
+ const result = await client.query({ query: "SELECT version() AS v", format: "JSONEachRow" });
113
+ const rows = await result.json();
114
+ return rows[0]?.v ?? "unknown";
115
+ }
116
+ finally {
117
+ await client.close().catch(() => { });
118
+ }
119
+ }
120
+ /** Create the database and project tables (and the ANN index when requested). */
121
+ async function initializeStore(input, cwd) {
122
+ const cfg = loadWorkspaceConfig(cwd);
123
+ cfg.vectorStore.provider = "clickhouse";
124
+ cfg.vectorStore.clickhouse = {
125
+ ...(cfg.vectorStore.clickhouse ?? {}),
126
+ url: input.url,
127
+ database: input.database,
128
+ username: input.username,
129
+ password: input.password,
130
+ passwordEnv: "",
131
+ namespace: input.namespace,
132
+ ann: input.ann,
133
+ annFetchMultiplier: 4,
134
+ annWithRescoring: true,
135
+ };
136
+ const options = resolveClickHouseOptions(cfg, cwd);
137
+ const store = new ClickHouseStore(options, input.dimension);
138
+ try {
139
+ const dimension = await store.getVectorDimension();
140
+ const ann = await store.hasVectorIndex();
141
+ const count = await store.count();
142
+ console.log(`\n ${c.success("Initialized:")} ${input.database}.${options.chunksTable}`);
143
+ console.log(` ${c.label("State table:")} ${input.database}.${options.stateTable}`);
144
+ console.log(` ${c.label("Dimension:")} ${dimension ?? input.dimension}`);
145
+ console.log(` ${c.label("ANN:")} ${ann ? "hnsw (vector_similarity)" : input.ann === "hnsw" ? "missing" : "off (exact scans)"}`);
146
+ console.log(` ${c.label("Chunks:")} ${count}`);
147
+ }
148
+ finally {
149
+ await store.close().catch(() => { });
150
+ }
151
+ }
152
+ /** Run the interactive (or flag-driven) ClickHouse setup. */
153
+ export async function runClickHouseSetup(options = {}) {
154
+ const cwd = options.cwd ?? process.cwd();
155
+ const interactive = Boolean(process.stdin.isTTY) && !options.yes;
156
+ const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
157
+ try {
158
+ const cfg = loadWorkspaceConfig(cwd);
159
+ const defaultDimension = cfg.embedding.vectorDimension && cfg.embedding.vectorDimension > 0
160
+ ? String(cfg.embedding.vectorDimension)
161
+ : "384";
162
+ const scopeDefault = options.scope === "global" || options.scope === "workspace" ? options.scope : "workspace";
163
+ const rawUrl = interactive
164
+ ? await promptLine(rl, "ClickHouse URL", options.url ?? "http://localhost:8123")
165
+ : options.url ?? "http://localhost:8123";
166
+ const defaultPort = (() => {
167
+ try {
168
+ return new URL(rawUrl).port || "8123";
169
+ }
170
+ catch {
171
+ return "8123";
172
+ }
173
+ })();
174
+ const port = interactive ? await promptLine(rl, "Port", options.port ?? defaultPort) : options.port ?? defaultPort;
175
+ let url;
176
+ try {
177
+ url = composeClickHouseUrl(rawUrl, port);
178
+ }
179
+ catch {
180
+ throw new Error(`Invalid ClickHouse URL: "${rawUrl}"`);
181
+ }
182
+ const database = interactive
183
+ ? await promptLine(rl, "Database", options.database ?? cfg.vectorStore.clickhouse?.database ?? "OpenCodeRAG")
184
+ : options.database ?? cfg.vectorStore.clickhouse?.database ?? "OpenCodeRAG";
185
+ const username = interactive
186
+ ? await promptLine(rl, "Username", options.username ?? cfg.vectorStore.clickhouse?.username ?? "default")
187
+ : options.username ?? cfg.vectorStore.clickhouse?.username ?? "default";
188
+ let password = options.password ?? "";
189
+ if (!password && interactive)
190
+ password = await promptHidden(rl, "Password: ");
191
+ if (!password) {
192
+ const envName = options.passwordEnv ?? cfg.vectorStore.clickhouse?.passwordEnv ?? "OPENCODERAG_CLICKHOUSE_PASSWORD";
193
+ password = process.env[envName] ?? "";
194
+ if (!password) {
195
+ throw new Error("A ClickHouse password is required — pass --password, set the password env var, or run the command interactively.");
196
+ }
197
+ }
198
+ // 1. Probe the server before writing anything.
199
+ let version;
200
+ try {
201
+ version = await probeServer(url, username, password);
202
+ }
203
+ catch (err) {
204
+ throw new Error(`Could not connect/authenticate to ${url}: ${err.message}` +
205
+ (process.env.HTTP_PROXY || process.env.HTTPS_PROXY
206
+ ? "\nIf an internal hostname is involved, make sure NO_PROXY includes it."
207
+ : ""));
208
+ }
209
+ const annSupported = supportsAnn(version);
210
+ console.log(`\n ${c.success("Connected:")} ClickHouse ${version}${annSupported ? " (ANN available)" : " (no ANN, needs 25.8+)"}\n`);
211
+ const scope = interactive
212
+ ? (await promptLine(rl, "Write the config to workspace or global", scopeDefault)).toLowerCase() === "global"
213
+ ? "global"
214
+ : "workspace"
215
+ : scopeDefault;
216
+ const derived = deriveNamespace(cwd);
217
+ const namespaceDefault = options.namespace ?? (scope === "global" ? "" : cfg.vectorStore.clickhouse?.namespace ?? derived);
218
+ const namespace = interactive
219
+ ? await promptLine(rl, scope === "global" ? "Namespace (blank = per-workspace tables)" : "Namespace", namespaceDefault)
220
+ : namespaceDefault;
221
+ const dimension = interactive
222
+ ? Number.parseInt(await promptLine(rl, "Embedding dimension (ANN index is bound to it)", options.dimension ?? defaultDimension), 10)
223
+ : Number.parseInt(options.dimension ?? defaultDimension, 10);
224
+ if (!Number.isFinite(dimension) || dimension < 2 || dimension > 16000) {
225
+ throw new Error(`Invalid embedding dimension: ${options.dimension ?? defaultDimension}`);
226
+ }
227
+ const annDefault = options.ann ?? (annSupported ? "hnsw" : "off");
228
+ let ann;
229
+ if (interactive) {
230
+ const answer = await promptLine(rl, "Enable the HNSW ANN index (hnsw/off)", annDefault);
231
+ ann = answer.toLowerCase() === "off" ? "off" : "hnsw";
232
+ }
233
+ else {
234
+ ann = annDefault === "hnsw" ? "hnsw" : "off";
235
+ }
236
+ if (ann === "hnsw" && !annSupported) {
237
+ throw new Error(`ANN requires ClickHouse >= 25.8 — ${url} runs ${version}. Use --ann off.`);
238
+ }
239
+ const storeEnvDefault = options.passwordEnv ?? cfg.vectorStore.clickhouse?.passwordEnv ?? "OPENCODERAG_CLICKHOUSE_PASSWORD";
240
+ let storeInlinePassword = options.storePassword ?? false;
241
+ let passwordEnv = storeEnvDefault;
242
+ if (interactive) {
243
+ storeInlinePassword = /^y/i.test(await promptLine(rl, "Store the password in the config file (plaintext)", "n"));
244
+ if (!storeInlinePassword) {
245
+ passwordEnv = await promptLine(rl, "Password env var name", storeEnvDefault);
246
+ }
247
+ }
248
+ if (!storeInlinePassword && !passwordEnv) {
249
+ throw new Error("Set a password env var name or use --store-password.");
250
+ }
251
+ // 2. Initialize the database/tables before writing the config.
252
+ const setupInput = {
253
+ url,
254
+ database,
255
+ username,
256
+ password,
257
+ passwordEnv,
258
+ namespace: namespace ? sanitizeNamespace(namespace) : "",
259
+ ann,
260
+ dimension,
261
+ storeInlinePassword,
262
+ };
263
+ if (!options.skipInit) {
264
+ await initializeStore(setupInput, cwd);
265
+ }
266
+ // 3. Write the config (workspace or the machine-global user config).
267
+ const targetPath = scope === "global"
268
+ ? globalConfigPath()
269
+ : findOrCreateWorkspaceConfig(cwd);
270
+ const existing = readJsonObject(targetPath);
271
+ const next = mergeClickHouseConfig(existing, setupInput);
272
+ if (interactive) {
273
+ const write = await promptLine(rl, `Write this vectorStore block to ${targetPath}`, "y");
274
+ if (!/^y/i.test(write)) {
275
+ console.log(" (config not written)");
276
+ return;
277
+ }
278
+ }
279
+ if (existsSync(targetPath)) {
280
+ copyFileSync(targetPath, `${targetPath}.bak`);
281
+ }
282
+ mkdirSync(path.dirname(targetPath), { recursive: true });
283
+ writeJsonFile(targetPath, next);
284
+ console.log(`\n ${c.success("Config written:")} ${targetPath}`);
285
+ console.log(` ${c.label("Backend:")} clickhouse ${url}/${database}`);
286
+ console.log(` ${c.label("Namespace:")} ${setupInput.namespace || "(derived per workspace)"}`);
287
+ console.log(` ${c.label("ANN:")} ${ann}`);
288
+ if (!storeInlinePassword) {
289
+ const setCommand = process.platform === "win32"
290
+ ? `[Environment]::SetEnvironmentVariable("${passwordEnv}", "<password>", "User")`
291
+ : `export ${passwordEnv}="<password>" # add to ~/.bashrc or ~/.zshrc`;
292
+ console.log(`\n ${c.warn("Set the password before using it:")}\n ${setCommand}`);
293
+ }
294
+ console.log(`\n Next: ${c.value("opencode-rag index")} (then ${c.value("opencode-rag status")})\n`);
295
+ }
296
+ finally {
297
+ rl?.close();
298
+ }
299
+ }
300
+ /** Use an existing workspace config file, or the canonical `.opencode/opencode-rag.json` for a new one. */
301
+ function findOrCreateWorkspaceConfig(cwd) {
302
+ return findConfigFile(cwd) ?? projectConfigPath(cwd);
303
+ }
304
+ /** Register the `clickhouse` command group. */
305
+ export function registerClickHouseCommand(program) {
306
+ const group = program
307
+ .command("clickhouse")
308
+ .description("Manage the ClickHouse vector store");
309
+ group
310
+ .command("setup")
311
+ .description("Interactively configure and initialize a ClickHouse vector store")
312
+ .option("--url <url>", "ClickHouse endpoint (e.g. http://localhost:8123)")
313
+ .option("--port <port>", "ClickHouse HTTP port (default 8123)")
314
+ .option("--database <name>", "database name (default OpenCodeRAG)")
315
+ .option("--username <name>", "ClickHouse user (default default)")
316
+ .option("--password <password>", "password (prefer the prompt or an env var)")
317
+ .option("--password-env <name>", "env var holding the password")
318
+ .option("--namespace <name>", "project namespace / table suffix (blank = per-workspace)")
319
+ .option("--ann <mode>", "ANN mode: hnsw or off")
320
+ .option("--dimension <n>", "embedding dimension the ANN index is bound to")
321
+ .option("--scope <scope>", "write the config to workspace or global")
322
+ .option("--store-password", "write the password into the config file (plaintext)")
323
+ .option("--skip-init", "only write the config; do not create the database/tables")
324
+ .option("--yes", "non-interactive: use the flags/defaults without prompting")
325
+ .action(async (options) => {
326
+ try {
327
+ await runClickHouseSetup(options);
328
+ }
329
+ catch (err) {
330
+ console.error(`\n${c.error("ClickHouse setup failed:")} ${err.message}\n`);
331
+ process.exitCode = 1;
332
+ }
333
+ });
334
+ }
335
+ //# sourceMappingURL=clickhouse.js.map
@@ -189,7 +189,7 @@ export function registerEvalTuneCommand(program) {
189
189
  let written = false;
190
190
  if (options.write) {
191
191
  if (!ctx.configPath) {
192
- throw new Error("No config file to write to — pass --config <path> or run this in a workspace with opencode-rag.json.");
192
+ throw new Error("No config file to write to — pass --config <path> or run this in a workspace with .opencode/opencode-rag.json.");
193
193
  }
194
194
  const tuned = applyTuningToConfig(ctx.config, best);
195
195
  const hybridWeights = tuned.retrieval.hybridSearch ?? { enabled: true, keywordWeight: best.keywordWeight };
@@ -377,7 +377,7 @@ export function registerEvalDecideCommand(program) {
377
377
  };
378
378
  }
379
379
  if (!decisionCfg) {
380
- console.error(c.error("\nNo enabled decision config. Set `decision.enabled` in opencode-rag.json or pass --base-url/--model.\n"));
380
+ console.error(c.error("\nNo enabled decision config. Set `decision.enabled` in .opencode/opencode-rag.json or pass --base-url/--model.\n"));
381
381
  await cleanupContext(ctx);
382
382
  process.exit(2);
383
383
  }
@@ -59,7 +59,7 @@ export function registerIndexCommand(program) {
59
59
  const cwd = process.cwd();
60
60
  let logFilePath = path.resolve(cwd, ".opencode", "opencode-rag.log");
61
61
  const ctx = await resolveCliContext(options, logFilePath);
62
- const { config, embedder, store, storePath, keywordIndex, descriptionProvider, dimension } = ctx;
62
+ const { config, embedder, store, storePath, keywordIndex, descriptionProvider, dimension, stateSync } = ctx;
63
63
  logFilePath = ctx.logFilePath;
64
64
  // ── Abort controller for graceful Ctrl+C during the initial pass ──
65
65
  const abortController = new AbortController();
@@ -111,6 +111,7 @@ export function registerIndexCommand(program) {
111
111
  embedder,
112
112
  keywordIndex,
113
113
  descriptionProvider,
114
+ stateSync,
114
115
  force: !!(options.force && !watchTriggered),
115
116
  abortSignal,
116
117
  dimension,
@@ -9,6 +9,7 @@ export { registerListCommand } from "./list.js";
9
9
  export { registerShowCommand } from "./show.js";
10
10
  export { registerDumpCommand } from "./dump.js";
11
11
  export { registerInitCommand } from "./init.js";
12
+ export { registerClickHouseCommand } from "./clickhouse.js";
12
13
  export { registerUiCommand } from "./ui.js";
13
14
  export { registerMcpCommand } from "./mcp.js";
14
15
  export { registerSetupCommand } from "./setup.js";
@@ -9,6 +9,7 @@ export { registerListCommand } from "./list.js";
9
9
  export { registerShowCommand } from "./show.js";
10
10
  export { registerDumpCommand } from "./dump.js";
11
11
  export { registerInitCommand } from "./init.js";
12
+ export { registerClickHouseCommand } from "./clickhouse.js";
12
13
  export { registerUiCommand } from "./ui.js";
13
14
  export { registerMcpCommand } from "./mcp.js";
14
15
  export { registerSetupCommand } from "./setup.js";
@@ -283,7 +283,7 @@ export function generateSkillFile() {
283
283
  "- `find_usages` is essential before refactoring — it shows every reference",
284
284
  "- Pass `systemPrompt` to `describe_image` when you need specific details (e.g. `\"focus on the chart's axes and values\"`)",
285
285
  "- If no results appear, the workspace may not be indexed yet — run `opencode-rag index`",
286
- "- Image descriptions are generated at index time using the configured vision provider; ensure `imageDescription` is configured in `opencode-rag.json` if your project includes images",
286
+ "- Image descriptions are generated at index time using the configured vision provider; ensure `imageDescription` is configured in `.opencode/opencode-rag.json` (its provider/model options live in the global config) if your project includes images",
287
287
  "",
288
288
  ].join("\n");
289
289
  }
@@ -308,7 +308,7 @@ export function generateDecisionSkillFile() {
308
308
  "",
309
309
  "### Prerequisites",
310
310
  "",
311
- "- `decision.enabled` must be `true` in `opencode-rag.json` (off by default).",
311
+ "- `decision.enabled` must be `true` in `.opencode/opencode-rag.json` (off by default).",
312
312
  "- Requires Ollama >= 0.35 with a pulled tev1 model (`ollama pull tev1` or `ollama pull tev1:0.8b`).",
313
313
  "- Keep `state` short — the effective context is ~2k tokens. Pass the relevant excerpt, not a whole file.",
314
314
  "",
@@ -11,7 +11,7 @@
11
11
  */
12
12
  import path from "node:path";
13
13
  import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync } from "node:fs";
14
- import { loadConfig, findConfigFile, loadWorkspaceConfig, configuredSections } from "../../core/config.js";
14
+ import { loadConfig, findConfigFile, loadWorkspaceConfig, configuredSections, migrateLegacyProjectConfig, projectConfigPath } from "../../core/config.js";
15
15
  import { checkProviderHealth, pullOllamaModels } from "../../embedder/health.js";
16
16
  import { destroyAllPooledConnections } from "../../embedder/http.js";
17
17
  import { c } from "../format.js";
@@ -41,6 +41,12 @@ export function registerInitCommand(program) {
41
41
  .option("-f, --force", "overwrite existing files")
42
42
  .option("--skip-install", "skip installing workspace-local plugin dependencies")
43
43
  .option("--skip-health-check", "skip provider connectivity and model availability check")
44
+ .option("--vector-store <provider>", "vector store backend to write (lancedb | clickhouse)")
45
+ .option("--clickhouse-url <url>", "ClickHouse endpoint (default http://localhost:8123)")
46
+ .option("--clickhouse-database <name>", "ClickHouse database (default OpenCodeRAG)")
47
+ .option("--clickhouse-user <name>", "ClickHouse user (default default)")
48
+ .option("--clickhouse-password-env <name>", "env var holding the ClickHouse password")
49
+ .option("--clickhouse-namespace <name>", "project namespace / table suffix")
44
50
  .action((options) => runWorkspaceInit(options));
45
51
  }
46
52
  /**
@@ -57,10 +63,13 @@ export async function runWorkspaceInit(options = {}) {
57
63
  try {
58
64
  const cwd = process.cwd();
59
65
  const packageMetadata = getPackageMetadata();
60
- // Use findConfigFile so an existing config in .opencode/rag.json (or
61
- // .opencode/opencode-rag.json) is respected instead of being shadowed
62
- // by a new root-level opencode-rag.json.
63
- const configPath = findConfigFile(cwd) ?? path.join(cwd, "opencode-rag.json");
66
+ // The workspace config now lives in `.opencode/`: move a legacy
67
+ // root-level opencode-rag.json there (only when the canonical file is
68
+ // absent), then respect whatever config exists — `.opencode/rag.json`
69
+ // included — instead of shadowing it with a new file.
70
+ const migratedConfigPath = migrateLegacyProjectConfig(cwd);
71
+ const configPath = findConfigFile(cwd) ?? projectConfigPath(cwd);
72
+ const configLabel = path.relative(cwd, configPath).replace(/\\/g, "/");
64
73
  const opencodeDir = path.join(cwd, ".opencode");
65
74
  const gitignorePath = path.join(opencodeDir, ".gitignore");
66
75
  const opencodeConfigPath = path.join(opencodeDir, "opencode.json");
@@ -73,6 +82,9 @@ export async function runWorkspaceInit(options = {}) {
73
82
  const legacyTuiConfigPath = path.join(opencodeDir, "tui.json");
74
83
  const opencodePackagePath = path.join(opencodeDir, "package.json");
75
84
  console.log(`\n${c.heading("Initializing OpenCodeRAG in workspace...")}\n`);
85
+ if (migratedConfigPath) {
86
+ console.log(` ${c.updated("Moved:")} opencode-rag.json → .opencode/opencode-rag.json\n`);
87
+ }
76
88
  if (!existsSync(opencodeDir)) {
77
89
  mkdirSync(opencodeDir, { recursive: true });
78
90
  console.log(` ${c.created("Created:")} .opencode/`);
@@ -293,9 +305,11 @@ export async function runWorkspaceInit(options = {}) {
293
305
  }
294
306
  return generateDefaultConfigJson(detectedTuning, existingRaw);
295
307
  };
308
+ let configWritten = false;
296
309
  if (!configExists) {
297
310
  writeFileSync(configPath, await configContent(), "utf-8");
298
- console.log(` ${c.created("Created:")} opencode-rag.json`);
311
+ configWritten = true;
312
+ console.log(` ${c.created("Created:")} ${configLabel}`);
299
313
  }
300
314
  else {
301
315
  // NEVER overwrite existing config without interactive confirmation
@@ -304,24 +318,47 @@ export async function runWorkspaceInit(options = {}) {
304
318
  const readline = await import("node:readline");
305
319
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
306
320
  const answer = await new Promise((resolve) => {
307
- rl.question(` ${c.warn("opencode-rag.json already exists.")} Overwrite with default config? A backup will be saved. (y/N) `, resolve);
321
+ rl.question(` ${c.warn(`${configLabel} already exists.`)} Overwrite with default config? A backup will be saved. (y/N) `, resolve);
308
322
  });
309
323
  rl.close();
310
324
  overwrite = /^y(?:es)?$/i.test(answer.trim());
311
325
  }
312
326
  if (overwrite) {
313
327
  copyFileSync(configPath, `${configPath}.bak`);
314
- console.log(` ${c.dim("Backup:")} opencode-rag.json.bak`);
328
+ console.log(` ${c.dim("Backup:")} ${configLabel}.bak`);
315
329
  writeFileSync(configPath, await configContent(), "utf-8");
316
- console.log(` ${c.updated("Updated:")} opencode-rag.json`);
330
+ configWritten = true;
331
+ console.log(` ${c.updated("Updated:")} ${configLabel}`);
317
332
  }
318
333
  else {
319
- console.log(` ${c.exists("Exists:")} opencode-rag.json (preserved)`);
334
+ console.log(` ${c.exists("Exists:")} ${configLabel} (preserved)`);
320
335
  if (!process.stdin.isTTY && options.force) {
321
- console.log(` ${c.warn("Skipped overwrite:")} non-interactive shell. Edit opencode-rag.json manually or re-run in a TTY.`);
336
+ console.log(` ${c.warn("Skipped overwrite:")} non-interactive shell. Edit ${configLabel} manually or re-run in a TTY.`);
322
337
  }
323
338
  }
324
339
  }
340
+ // ── Optional central ClickHouse backend ──
341
+ if (configWritten && options.vectorStore === "clickhouse") {
342
+ const raw = readJsonObject(configPath) ?? {};
343
+ const current = (raw.vectorStore ?? {});
344
+ const currentClickhouse = current.clickhouse && typeof current.clickhouse === "object"
345
+ ? current.clickhouse
346
+ : {};
347
+ raw.vectorStore = {
348
+ ...current,
349
+ provider: "clickhouse",
350
+ clickhouse: {
351
+ ...currentClickhouse,
352
+ url: options.clickhouseUrl ?? "http://localhost:8123",
353
+ database: options.clickhouseDatabase ?? "OpenCodeRAG",
354
+ username: options.clickhouseUser ?? "default",
355
+ passwordEnv: options.clickhousePasswordEnv ?? "OPENCODERAG_CLICKHOUSE_PASSWORD",
356
+ ...(options.clickhouseNamespace ? { namespace: options.clickhouseNamespace } : {}),
357
+ },
358
+ };
359
+ writeJsonFile(configPath, raw);
360
+ console.log(` ${c.created("Configured:")} clickhouse backend (${options.clickhouseUrl ?? "http://localhost:8123"})`);
361
+ }
325
362
  // ── Provider health check + dependency install (parallel) ──
326
363
  const healthPromise = options.skipHealthCheck
327
364
  ? null
@@ -447,6 +484,7 @@ export function isLikelyProjectRoot(cwd) {
447
484
  "Cargo.toml",
448
485
  "go.mod",
449
486
  "opencode-rag.json",
487
+ ".opencode/opencode-rag.json",
450
488
  ];
451
489
  return markers.some((marker) => existsSync(path.join(cwd, marker)));
452
490
  }
@@ -21,7 +21,7 @@ export function registerQuirkCommand(program) {
21
21
  try {
22
22
  const ctx = await resolveCliContext(options, resolveLogPath());
23
23
  const { config, embedder, store, keywordIndex } = ctx;
24
- const quirk = await addQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, {
24
+ const quirk = await addQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath, flushState: () => ctx.stateSync?.flush(["quirks"]) ?? Promise.resolve() }, {
25
25
  content,
26
26
  quirkType: options.type,
27
27
  tags: options.tag ? (Array.isArray(options.tag) ? options.tag : [options.tag]) : undefined,
@@ -58,7 +58,7 @@ export function registerQuirkCommand(program) {
58
58
  const ctx = await resolveCliContext(options, resolveLogPath());
59
59
  const { config, embedder, store, keywordIndex } = ctx;
60
60
  const tags = options.tag;
61
- const quirk = await updateQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, id, {
61
+ const quirk = await updateQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath, flushState: () => ctx.stateSync?.flush(["quirks"]) ?? Promise.resolve() }, id, {
62
62
  content: options.content,
63
63
  quirkType: options.type,
64
64
  tags: tags ? (Array.isArray(tags) ? tags : [tags]) : undefined,
@@ -85,7 +85,7 @@ export function registerQuirkCommand(program) {
85
85
  try {
86
86
  const ctx = await resolveCliContext(options, resolveLogPath());
87
87
  const { config, embedder, store, keywordIndex } = ctx;
88
- const quirks = await listQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath });
88
+ const quirks = await listQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath, flushState: () => ctx.stateSync?.flush(["quirks"]) ?? Promise.resolve() });
89
89
  logCliInfo(ctx.logFilePath, "quirk list", `\n${c.num(quirks.length)} quirk(s):\n`);
90
90
  for (const q of quirks) {
91
91
  const badge = q.quirkType ? `[${q.quirkType}] ` : "";
@@ -109,7 +109,7 @@ export function registerQuirkCommand(program) {
109
109
  try {
110
110
  const ctx = await resolveCliContext(options, resolveLogPath());
111
111
  const { config, embedder, store, keywordIndex } = ctx;
112
- await removeQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, id);
112
+ await removeQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath, flushState: () => ctx.stateSync?.flush(["quirks"]) ?? Promise.resolve() }, id);
113
113
  logCliInfo(ctx.logFilePath, "quirk rm", `\n${c.success("Quirk removed:")} ${id}`);
114
114
  await cleanupContext(ctx);
115
115
  }
@@ -126,7 +126,7 @@ export function registerQuirkCommand(program) {
126
126
  try {
127
127
  const ctx = await resolveCliContext(options, resolveLogPath());
128
128
  const { config, embedder, store, keywordIndex } = ctx;
129
- const issues = await lintQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath });
129
+ const issues = await lintQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath, flushState: () => ctx.stateSync?.flush(["quirks"]) ?? Promise.resolve() });
130
130
  if (issues.length === 0) {
131
131
  logCliInfo(ctx.logFilePath, "quirk lint", c.success("\nNo issues found. All quirks look healthy."));
132
132
  }
@@ -152,7 +152,7 @@ export function registerQuirkCommand(program) {
152
152
  try {
153
153
  const ctx = await resolveCliContext(options, resolveLogPath());
154
154
  const { config, embedder, store, keywordIndex } = ctx;
155
- const results = await recallQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, content, { topK: 5 });
155
+ const results = await recallQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath, flushState: () => ctx.stateSync?.flush(["quirks"]) ?? Promise.resolve() }, content, { topK: 5 });
156
156
  if (results.length > 0) {
157
157
  logCliInfo(ctx.logFilePath, "quirk test", c.warn("\n✗ Similar quirk(s) already exist — quirk has NOT been appended:\n"));
158
158
  for (const r of results) {