opencode-rag-plugin 2.12.2 → 2.13.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 CHANGED
@@ -79,7 +79,8 @@ No GPU is required, although it is recommended when using code and image descrip
79
79
  npm install -g opencode-rag-plugin
80
80
 
81
81
  # 2. Set up the runtime, the workspace, and your models
82
- # (a short interactive wizard guides you through the configuration)
82
+ # (a short interactive wizard guides you through the configuration;
83
+ # the web UI then opens on the Configuration page)
83
84
  cd /path/to/your/project
84
85
  opencode-rag setup
85
86
 
@@ -114,6 +115,7 @@ It handles the whole onboarding in one command:
114
115
  - installs or verifies the machine-level runtime in `~/.opencode/`
115
116
  - scaffolds the current workspace (`.opencode/` config, plugin entries, skill files)
116
117
  - on the first run, or with `--reconfigure`, starts a **model wizard** for the embedding, description, vision, and decision models
118
+ - an interactive run finishes by opening the **Web UI on its Configuration page**, so the generated settings can be reviewed and adjusted; the server stays up until you press `Ctrl+C` (`--no-ui` keeps setup headless)
117
119
 
118
120
  A plain re-run only syncs the workspace files. The wizard is scriptable (`--yes`, `--provider`, `--base-url`, `--embedding-model`, `--description off`, and more), and `--skip-runtime` limits the run to the workspace. Use `opencode-rag update` to upgrade the runtime to a newer release.
119
121
 
@@ -387,7 +389,7 @@ Image files (PNG, JPEG, WebP, and others) are sent to a vision-capable LLM, and
387
389
 
388
390
  ### 7. Web UI, evaluation, and calibration
389
391
 
390
- **Web UI.** A browser dashboard for exploring the vector database: browse, visualize, and inspect chunks, and evaluate OpenCode sessions by retrieved chunks and consumed tokens. Launch it with `opencode-rag ui`. See the [Web UI docs](doc/webui.md).
392
+ **Web UI.** A browser dashboard for exploring the vector database: browse, visualize, and inspect chunks side-by-side with a movable splitter, edit the global and project configuration layers, switch between dark, plasma, drama, and light themes, and evaluate OpenCode sessions by retrieved chunks and consumed tokens. Launch it with `opencode-rag ui` (or let `opencode-rag setup` open it on the Configuration page). See the [Web UI docs](doc/webui.md).
391
393
 
392
394
  [![OpenCodeRAG Web UI](doc/assets/webui-3d.png)](doc/assets/webui-3d.png)
393
395
 
@@ -0,0 +1,20 @@
1
+ /**
2
+ * @fileoverview Cross-platform helper for opening a URL in the user's default browser.
3
+ */
4
+ /**
5
+ * Open a URL in the system default browser.
6
+ *
7
+ * Spawns the platform launcher detached so it outlives the CLI process:
8
+ * `cmd.exe /c start` on Windows, `open` on macOS and `xdg-open` elsewhere.
9
+ * Every spawn passes `windowsHide: true` — the plugin also runs inside
10
+ * OpenCode's console-less service, where an un-hidden spawn flashes a
11
+ * terminal window per call.
12
+ *
13
+ * The returned promise resolves once the launcher process either spawned or
14
+ * failed (a missing `xdg-open` emits an `error` event rather than throwing),
15
+ * so callers can tell "no browser available" from "browser opened".
16
+ *
17
+ * @param url - Absolute URL to open.
18
+ * @returns `true` when the launcher process was spawned, `false` otherwise.
19
+ */
20
+ export declare function openInBrowser(url: string): Promise<boolean>;
@@ -0,0 +1,49 @@
1
+ /**
2
+ * @fileoverview Cross-platform helper for opening a URL in the user's default browser.
3
+ */
4
+ import { spawn } from "node:child_process";
5
+ /**
6
+ * Open a URL in the system default browser.
7
+ *
8
+ * Spawns the platform launcher detached so it outlives the CLI process:
9
+ * `cmd.exe /c start` on Windows, `open` on macOS and `xdg-open` elsewhere.
10
+ * Every spawn passes `windowsHide: true` — the plugin also runs inside
11
+ * OpenCode's console-less service, where an un-hidden spawn flashes a
12
+ * terminal window per call.
13
+ *
14
+ * The returned promise resolves once the launcher process either spawned or
15
+ * failed (a missing `xdg-open` emits an `error` event rather than throwing),
16
+ * so callers can tell "no browser available" from "browser opened".
17
+ *
18
+ * @param url - Absolute URL to open.
19
+ * @returns `true` when the launcher process was spawned, `false` otherwise.
20
+ */
21
+ export async function openInBrowser(url) {
22
+ try {
23
+ // The empty title argument keeps `start` from treating the URL as the
24
+ // window title on Windows.
25
+ const child = process.platform === "win32"
26
+ ? spawn("cmd.exe", ["/c", "start", "", url], {
27
+ detached: true,
28
+ stdio: "ignore",
29
+ windowsHide: true,
30
+ })
31
+ : spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], {
32
+ detached: true,
33
+ stdio: "ignore",
34
+ windowsHide: true,
35
+ });
36
+ const spawned = await new Promise((resolve) => {
37
+ child.once("spawn", () => resolve(true));
38
+ child.once("error", () => resolve(false));
39
+ });
40
+ child.unref();
41
+ return spawned;
42
+ }
43
+ catch {
44
+ // `spawn` throws synchronously only for invalid arguments — treat any
45
+ // throw as "could not open a browser".
46
+ return false;
47
+ }
48
+ }
49
+ //# sourceMappingURL=browser.js.map
@@ -15,6 +15,7 @@ import { generateDefaultConfigJson } from "./workspace-helpers.js";
15
15
  import { detectOllamaBackend } from "./backend-detect.js";
16
16
  import { isLikelyProjectRoot, runWorkspaceHealthCheck, scaffoldWorkspace, } from "../workspace.js";
17
17
  import { destroyAllPooledConnections } from "../../embedder/http.js";
18
+ import { launchSetupConfigUi, shouldLaunchSetupUi } from "../setup-ui.js";
18
19
  import { getGlobalPluginDir, installGlobalPlugin, isGlobalPluginInstalled, isWorkspacePluginInstalled, removeGlobalPlugin, } from "../../core/global-plugin.js";
19
20
  const PLUGIN_NAME = "opencode-rag-plugin";
20
21
  function removeIfExists(targetPath) {
@@ -72,6 +73,9 @@ export function registerSetupCommand(program) {
72
73
  " Use --reconfigure to re-open the wizard, or pass flags for scripted setups.\n" +
73
74
  " - Updating: use 'opencode-rag update' to install a newer release.\n" +
74
75
  " - Troubleshooting: use --check to inspect the runtime, or --force to reinstall.\n" +
76
+ "\nAfter an interactive run the web UI opens on the Configuration page so the\n" +
77
+ "generated settings can be reviewed; press Ctrl+C there to finish. Use --no-ui\n" +
78
+ "to keep setup headless.\n" +
75
79
  "\nProvider/model settings are written to the global config\n" +
76
80
  "(~/.config/opencode/opencode-rag.json); feature toggles to the workspace\n" +
77
81
  "config (.opencode/opencode-rag.json).\n")
@@ -104,6 +108,7 @@ export function registerSetupCommand(program) {
104
108
  .option("--skip-runtime [on|off]", "skip the machine-level runtime install (workspace setup only)")
105
109
  .option("--workspace-plugin", "install the plugin into this workspace instead of the global config")
106
110
  .option("--no-index", "do not offer to build the search index after setup")
111
+ .option("--no-ui", "do not open the web UI Configuration page after setup")
107
112
  .action(async (options) => {
108
113
  await runSetup(options);
109
114
  });
@@ -413,6 +418,12 @@ async function runSetup(rawOptions) {
413
418
  console.log(` ${c.dim(" 1. Restart OpenCode if it is running")}`);
414
419
  console.log(` ${c.dim(" 2. Run `opencode-rag index` to build the search index")}`);
415
420
  checkOpenCodeRunning();
421
+ // Interactive runs hand off to the Configuration page so the generated
422
+ // settings can be reviewed immediately; the process stays alive until the
423
+ // user presses Ctrl+C. Never in scripted (`-y`) or failed runs.
424
+ if ((process.exitCode ?? 0) === 0 && shouldLaunchSetupUi(options)) {
425
+ await launchSetupConfigUi(process.cwd());
426
+ }
416
427
  console.log();
417
428
  }
418
429
  /**
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import path from "node:path";
8
8
  import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo } from "../format.js";
9
+ import { openInBrowser } from "../browser.js";
9
10
  /**
10
11
  * Register the `ui` command on the given Commander program.
11
12
  *
@@ -43,17 +44,8 @@ export function registerUiCommand(program) {
43
44
  logCliInfo(logFilePath, "ui", ` ${c.dim("The token in the URL authenticates this session — keep it private.")}`);
44
45
  logCliInfo(logFilePath, "ui", ` ${c.dim("Press Ctrl+C to stop")}\n`);
45
46
  if (openBrowser) {
46
- const { spawn } = await import("node:child_process");
47
- try {
48
- if (process.platform === "win32") {
49
- spawn("cmd.exe", ["/c", "start", url], { detached: true, stdio: "ignore", windowsHide: true }).unref();
50
- }
51
- else {
52
- const cmd = process.platform === "darwin" ? "open" : "xdg-open";
53
- spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
54
- }
55
- }
56
- catch {
47
+ const opened = await openInBrowser(url);
48
+ if (!opened) {
57
49
  console.error(c.dim(`Could not open browser automatically. Open ${url} manually.`));
58
50
  }
59
51
  }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @fileoverview Optional hand-off from `opencode-rag setup` to the web UI's
3
+ * Configuration view.
4
+ *
5
+ * Once the workspace is configured, an interactive setup opens the browser on
6
+ * the Configuration page and keeps the UI server alive until the user presses
7
+ * Ctrl+C. Scripted runs (`-y`), non-TTY runs and `--no-ui` never launch it.
8
+ */
9
+ /** Setup options that decide whether the Configuration UI opens. */
10
+ export interface SetupUiLaunchOptions {
11
+ /** Set to `false` by `--no-ui`. */
12
+ ui?: boolean;
13
+ /** Set by `-y`/`--yes`: scripted runs never open a browser. */
14
+ yes?: boolean;
15
+ }
16
+ /**
17
+ * Decide whether a finished setup should open the Configuration UI.
18
+ *
19
+ * Deliberately conservative: the setup process stays alive while the UI is
20
+ * open, so it must never trigger in a scripted (`-y`), non-interactive or
21
+ * `--no-ui` run — those would hang a CI job or an install pipeline.
22
+ *
23
+ * @param options - Parsed setup options.
24
+ * @param interactive - Whether stdin/stdout are a TTY (injectable for tests).
25
+ * @returns `true` when the UI should be launched.
26
+ */
27
+ export declare function shouldLaunchSetupUi(options: SetupUiLaunchOptions, interactive?: boolean): boolean;
28
+ /**
29
+ * Open the web UI on the Configuration view and keep it running until the
30
+ * user stops it.
31
+ *
32
+ * Best-effort by design: setup has already completed, so a failure to start
33
+ * the server or open a browser only prints a hint and returns. The browser
34
+ * link carries the per-run auth token and the `#config` hash route.
35
+ *
36
+ * @param cwd - Workspace root (defaults to the current directory).
37
+ */
38
+ export declare function launchSetupConfigUi(cwd?: string): Promise<void>;
@@ -0,0 +1,133 @@
1
+ /**
2
+ * @fileoverview Optional hand-off from `opencode-rag setup` to the web UI's
3
+ * Configuration view.
4
+ *
5
+ * Once the workspace is configured, an interactive setup opens the browser on
6
+ * the Configuration page and keeps the UI server alive until the user presses
7
+ * Ctrl+C. Scripted runs (`-y`), non-TTY runs and `--no-ui` never launch it.
8
+ */
9
+ import { c, cleanupContext } from "./format.js";
10
+ import { openInBrowser } from "./browser.js";
11
+ import { isInteractiveTerminal } from "./prompt.js";
12
+ import { findConfigFile, projectConfigPath } from "../core/config.js";
13
+ import { resolveRagContext } from "../core/bootstrap.js";
14
+ /**
15
+ * Decide whether a finished setup should open the Configuration UI.
16
+ *
17
+ * Deliberately conservative: the setup process stays alive while the UI is
18
+ * open, so it must never trigger in a scripted (`-y`), non-interactive or
19
+ * `--no-ui` run — those would hang a CI job or an install pipeline.
20
+ *
21
+ * @param options - Parsed setup options.
22
+ * @param interactive - Whether stdin/stdout are a TTY (injectable for tests).
23
+ * @returns `true` when the UI should be launched.
24
+ */
25
+ export function shouldLaunchSetupUi(options, interactive = isInteractiveTerminal()) {
26
+ if (options.ui === false)
27
+ return false;
28
+ if (options.yes === true)
29
+ return false;
30
+ return interactive;
31
+ }
32
+ /**
33
+ * Open the web UI on the Configuration view and keep it running until the
34
+ * user stops it.
35
+ *
36
+ * Best-effort by design: setup has already completed, so a failure to start
37
+ * the server or open a browser only prints a hint and returns. The browser
38
+ * link carries the per-run auth token and the `#config` hash route.
39
+ *
40
+ * @param cwd - Workspace root (defaults to the current directory).
41
+ */
42
+ export async function launchSetupConfigUi(cwd = process.cwd()) {
43
+ let ctx;
44
+ try {
45
+ // Read-only context: never probe the provider or reconcile quirks during
46
+ // setup — the Configuration page only needs the resolved config and paths.
47
+ ctx = await resolveRagContext({ cwd, skipProbe: true, skipKeywordIndex: true });
48
+ }
49
+ catch (err) {
50
+ console.log(` ${c.warn("Configuration UI skipped:")} ${err.message}`);
51
+ return;
52
+ }
53
+ if (ctx.config.ui?.openBrowser === false) {
54
+ console.log(` ${c.dim("Configuration UI: browser launch disabled (ui.openBrowser = false).")} ` +
55
+ `Run ${c.file("opencode-rag ui")} to open the dashboard.`);
56
+ await cleanupContext(ctx);
57
+ return;
58
+ }
59
+ const configPath = findConfigFile(cwd) ?? projectConfigPath(cwd);
60
+ const port = ctx.config.ui?.port ?? 3210;
61
+ let server;
62
+ try {
63
+ const { startWebUi } = await import("../web/server.js");
64
+ try {
65
+ server = await startWebUi(ctx.storePath, port, cwd, ctx.dimension, ctx.config, configPath);
66
+ }
67
+ catch (err) {
68
+ if (!isAddressInUse(err) || port === 0)
69
+ throw err;
70
+ console.log(` ${c.dim(`Port ${port} is in use — using a free port for the Configuration UI.`)}`);
71
+ server = await startWebUi(ctx.storePath, 0, cwd, ctx.dimension, ctx.config, configPath);
72
+ }
73
+ }
74
+ catch (err) {
75
+ console.log(` ${c.warn("Configuration UI could not start:")} ${err.message}`);
76
+ console.log(` ${c.dim("Run `opencode-rag ui` later to open the dashboard.")}`);
77
+ await cleanupContext(ctx);
78
+ return;
79
+ }
80
+ const url = `http://127.0.0.1:${server.port}/?token=${server.token}#config`;
81
+ console.log(`\n${c.heading("Configuration UI")}`);
82
+ console.log(` ${c.label("URL:")} ${c.value(url)}`);
83
+ console.log(` ${c.dim("The token in the URL authenticates this session — keep it private.")}`);
84
+ console.log(` ${c.dim("Edit the global and project settings in the browser, then press Ctrl+C to stop.")}\n`);
85
+ if (!(await openInBrowser(url))) {
86
+ console.log(` ${c.warn("Could not open the browser automatically.")} Open the URL above manually,`);
87
+ console.log(` ${c.dim("or run `opencode-rag ui` later to open the dashboard.")}`);
88
+ // Nobody is looking at a page we could not open — stop instead of hanging.
89
+ await closeUi(server, ctx);
90
+ return;
91
+ }
92
+ let shuttingDown = false;
93
+ const shutdown = async () => {
94
+ if (shuttingDown) {
95
+ // Second Ctrl+C: do not wait for the graceful close.
96
+ process.exit(1);
97
+ }
98
+ shuttingDown = true;
99
+ await closeUi(server, ctx);
100
+ process.exit(0);
101
+ };
102
+ process.on("SIGINT", shutdown);
103
+ process.on("SIGTERM", shutdown);
104
+ }
105
+ /**
106
+ * Tear down the UI server and the bootstrap context it borrowed.
107
+ *
108
+ * @param server - Running web UI handle.
109
+ * @param ctx - Bootstrap context created for the launch.
110
+ */
111
+ async function closeUi(server, ctx) {
112
+ try {
113
+ await server.close();
114
+ }
115
+ catch {
116
+ // best-effort — setup is finishing anyway
117
+ }
118
+ try {
119
+ await cleanupContext(ctx);
120
+ }
121
+ catch {
122
+ // best-effort cleanup
123
+ }
124
+ }
125
+ /** Whether a `listen()` error is a port conflict. */
126
+ function isAddressInUse(err) {
127
+ if (typeof err !== "object" || err === null)
128
+ return false;
129
+ if (err.code === "EADDRINUSE")
130
+ return true;
131
+ return /EADDRINUSE/.test(err.message ?? "");
132
+ }
133
+ //# sourceMappingURL=setup-ui.js.map
@@ -59,6 +59,11 @@ export interface SetupOptions extends WizardFlags {
59
59
  workspacePlugin?: boolean;
60
60
  /** Set to `false` by `--no-index`: do not offer to build the index. */
61
61
  index?: boolean;
62
+ /**
63
+ * Set to `false` by `--no-ui`: do not open the web UI Configuration page
64
+ * when an interactive setup finishes.
65
+ */
66
+ ui?: boolean;
62
67
  }
63
68
  /** Shape of the `package.json` metadata required by CLI helpers. */
64
69
  export interface PackageMetadata {
@@ -321,6 +321,13 @@ export interface UiConfig {
321
321
  port: number;
322
322
  /** Whether to automatically open the browser on startup. */
323
323
  openBrowser: boolean;
324
+ /**
325
+ * Dashboard color theme: `dark`, `light`, `plasma` or `drama`.
326
+ * Machine-wide preference, so it lives in the global config; the web UI
327
+ * caches it in localStorage for first paint and treats this as the source
328
+ * of truth on snapshot load.
329
+ */
330
+ theme: string;
324
331
  }
325
332
  /** Configuration for the automated documentation mode that adds JSDoc/TSDoc to source files. */
326
333
  export interface DocumentationModeConfig {
@@ -376,6 +376,7 @@ export const DEFAULT_CONFIG = {
376
376
  ui: {
377
377
  port: 3210,
378
378
  openBrowser: true,
379
+ theme: "dark",
379
380
  },
380
381
  tui: {
381
382
  fileListKeybinding: "ctrl+enter",
@@ -612,6 +613,9 @@ export function validateConfig(config) {
612
613
  if (config.ui.port < 1 || config.ui.port > 65535) {
613
614
  warnings.push("ui.port must be between 1 and 65535");
614
615
  }
616
+ if (!["dark", "light", "plasma", "drama"].includes(config.ui.theme)) {
617
+ warnings.push(`ui.theme "${config.ui.theme}" — expected "dark", "light", "plasma" or "drama"`);
618
+ }
615
619
  }
616
620
  if (config.description) {
617
621
  const KNOWN_DESCRIPTION_PROVIDERS = new Set(["ollama", "openai", "anthropic", "google"]);
package/dist/plugin.js CHANGED
@@ -2008,8 +2008,28 @@ async function loadKeywordIndex(storePath, logFilePath, logLevel) {
2008
2008
  const index = await KeywordIndex.load(storePath);
2009
2009
  appendDebugLog(logFilePath, {
2010
2010
  scope: "plugin",
2011
- message: `Keyword index loaded (${index.count()} chunks)`,
2011
+ message: `Keyword index loaded (${index.count()} chunks, ${index.postingCount()} postings)`,
2012
2012
  }, logLevel);
2013
+ // One-time migration from the legacy v3 (Map-era) serialization: the
2014
+ // freshly parsed file was the fat sidecar, so persist once in the compact
2015
+ // v4 format and later boots skip the multi-hundred-MB v3 parse spike.
2016
+ // Fire-and-forget — startup must never block on the disk write.
2017
+ if (index.needsFormatMigration()) {
2018
+ void index.save()
2019
+ .then(() => {
2020
+ appendDebugLog(logFilePath, {
2021
+ scope: "plugin",
2022
+ message: "Keyword index migrated to v4 format",
2023
+ }, logLevel);
2024
+ })
2025
+ .catch((err) => {
2026
+ appendDebugLog(logFilePath, {
2027
+ scope: "plugin",
2028
+ message: "Keyword index v4 migration save failed",
2029
+ error: err,
2030
+ }, logLevel);
2031
+ });
2032
+ }
2013
2033
  return index;
2014
2034
  }
2015
2035
  catch (err) {
@@ -1,5 +1,20 @@
1
1
  /**
2
2
  * @fileoverview In-memory inverted keyword index with stemming, tokenization, and optional serialization.
3
+ *
4
+ * Memory model: postings live in compressed-sparse-row typed arrays
5
+ * (per-token slices of chunk indices + frequencies, sorted by chunk index),
6
+ * chunk identity is interned to a numeric slot, and per-chunk token sets are
7
+ * never materialized as JS Sets. For a corpus with millions of postings this
8
+ * keeps the resident heap at tens of megabytes instead of gigabytes — the
9
+ * previous Map<token, Map<chunkId, freq>> representation plus a full
10
+ * chunkTokens Map multiplied the serialized size several-fold and dominated
11
+ * the OpenCode server's memory (a 188 MB sidecar index cost >2 GB resident).
12
+ *
13
+ * Mutations between {@link KeywordIndex.save} calls accumulate in small
14
+ * pending structures (addPostings / dels) that {@link retrieve}-time scoring
15
+ * merges on the fly and that {@link KeywordIndex.save} folds into the CSR
16
+ * before serializing, so incremental watcher passes stay O(changed file)
17
+ * while the steady-state structures stay compact.
3
18
  */
4
19
  import type { Chunk, SearchResult, MetadataFilter } from "../core/interfaces.js";
5
20
  /**
@@ -13,37 +28,60 @@ export declare function indexPathFor(storePath: string): string;
13
28
  /**
14
29
  * In-memory inverted keyword index with stemming, TF-IDF scoring, and optional JSON serialization.
15
30
  *
31
+ * Postings are stored CSR-style: token `t` owns the slice
32
+ * `[tokenStart[t], tokenStart[t+1])` of `postChunk`/`postFreq`, sorted by
33
+ * chunk index. Chunks have an internal numeric slot; the string id exists
34
+ * exactly once per chunk. Deletions are tombstones that a merge (run by
35
+ * `save()`) folds away by rebuilding the CSR without them.
36
+ *
16
37
  * @param storePath - Optional path to the vector store directory used for loading/saving the serialized index
17
38
  */
18
39
  export declare class KeywordIndex {
19
- private invertedIndex;
20
40
  private chunkMap;
21
- private readonly storePath?;
22
- /** filePath (normalized) → chunk IDs, for O(chunks-in-file) removal. */
41
+ /** chunk id -> numeric slot. Dead (deleted) ids are removed; slots are never reused. */
42
+ private idToIdx;
43
+ /** slot -> chunk id (holes for dead slots are simply never consulted). */
44
+ private idxToId;
45
+ /** filePath (normalized) -> slot set, for O(chunks-in-file) removal. */
23
46
  private fileToIds;
24
- /** Indexed-token length per chunk, and the running total — drives BM25 length
25
- * normalization so long chunks can't dominate purely on term frequency. */
47
+ /** Indexed-token length per slot — drives BM25 length normalization. */
26
48
  private docLengths;
27
49
  private totalTokens;
28
- /** The exact set of tokens indexed per chunk id, recorded at add time.
29
- * Removal deletes precisely these entries instead of re-tokenizing the
30
- * chunk: re-derivation would leave dangling inverted-index references
31
- * whenever the chunk's text drifted between indexing and removal (the
32
- * description stage mutates `chunk.description` after addChunks, or the
33
- * persisted index was written by a build whose tokenizer differed). */
34
- private chunkTokens;
50
+ private tokNames;
51
+ private tokIdx;
52
+ /** length tokNames.length + 1; slice bounds into postChunk/postFreq. */
53
+ private tokenStart;
54
+ private postChunk;
55
+ private postFreq;
56
+ /** token -> slot -> term frequency, recorded at add time. Also plays the
57
+ * role the old chunkTokens Map played: removal and merging use these
58
+ * recorded postings rather than re-tokenizing, because the description
59
+ * stage mutates `chunk.description` AFTER addChunks ran and re-derivation
60
+ * would leak tokens that were never indexed. */
61
+ private addPostings;
62
+ /** slots deleted since the last merge — filtered by search and save. */
63
+ private dels;
64
+ /** Set by a v3-format load; the plugin re-saves once to migrate. */
65
+ private migratedFromV3;
35
66
  constructor(storePath?: string);
67
+ private readonly storePath?;
36
68
  addChunks(chunks: Chunk[]): void;
37
69
  getMatchedTerms(query: string, chunkId: string): string[];
70
+ /** Binary search the sorted CSR slice of token `ti` for slot `idx`. */
71
+ private csrContains;
38
72
  removeByFilePath(filePath: string): void;
39
73
  search(query: string, topK: number, filter?: MetadataFilter): SearchResult[];
40
- /** Remove every inverted-index reference to chunk ids that no longer have a
41
- * chunkMap entry. Uses the recorded token set when available (fast path,
42
- * always taken for loaded indexes) and falls back to a full scan. */
43
- private pruneDangling;
74
+ /** Fold pending additions and tombstones into the CSR. Empty token slices
75
+ * are dropped so the token table does not grow unboundedly across merges. */
76
+ private merge;
44
77
  close(): void;
45
78
  clear(): void;
46
79
  count(): number;
80
+ /** Total postings (merged + pending). Diagnostic/logging only. */
81
+ postingCount(): number;
82
+ /** True when this instance was loaded from the legacy v3 (Map-era) file
83
+ * format; the caller should persist once to migrate to v4. */
84
+ needsFormatMigration(): boolean;
47
85
  hasChunk(id: string): boolean;
48
86
  /**
49
87
  * Normalized file paths that currently have at least one indexed chunk.
@@ -57,5 +95,9 @@ export declare class KeywordIndex {
57
95
  getIndexedFilePaths(): string[];
58
96
  save(storePath?: string): Promise<void>;
59
97
  static load(storePath: string): Promise<KeywordIndex>;
98
+ /** Read the legacy Map-era format and build the CSR representation.
99
+ * Transient parse peaks exist for this ONE read; the plugin migrates to v4
100
+ * immediately after (needsFormatMigration) so later boots are cheap. */
101
+ private static loadV3;
60
102
  static clearFile(storePath: string): Promise<void>;
61
103
  }