opencode-rag-plugin 1.12.17 → 1.14.6

package/dist/cli/helpers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Package and file-system utility helpers used by CLI command modules.
+ */
+import type { PackageMetadata } from "./types.js";
+/**
+ * Resolve the absolute path to the package root directory.
+ *
+ * Uses `import.meta.url` to locate the directory containing `package.json`
+ * relative to the compiled output.
+ *
+ * @returns Absolute path to the package root (e.g. `/path/to/opencode-rag`).
+ */
+export declare function getPackageRoot(): string;
+/**
+ * Read and parse `package.json` from the package root.
+ *
+ * @returns The parsed `PackageMetadata` containing name, version, and dependency maps.
+ * @throws {Error} If the package.json file cannot be read or parsed (e.g. merge conflicts).
+ */
+export declare function getPackageMetadata(): PackageMetadata;
+/**
+ * Filter an unknown value into a `Record<string, string>`.
+ *
+ * Returns an empty object if the value is not a plain object or contains
+ * non-string entries.
+ *
+ * @param value - The unknown value to normalize.
+ * @returns A record with only string-valued entries.
+ */
+export declare function getStringRecord(value: unknown): Record<string, string>;
+/**
+ * Read a JSON file from disk and return it as a generic record.
+ *
+ * @param filePath - Absolute path to the JSON file.
+ * @returns The parsed object, or `undefined` if the file does not exist.
+ */
+export declare function readJsonObject(filePath: string): Record<string, unknown> | undefined;
+/**
+ * Write a JavaScript object to disk as pretty-printed JSON.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param value - The object to serialize (2-space indentation, trailing newline).
+ */
+export declare function writeJsonFile(filePath: string, value: Record<string, unknown>): void;
+/**
+ * Convert a platform-specific path to POSIX (forward-slash) format.
+ *
+ * @param input - A file path using the platform separator.
+ * @returns The same path with all backslashes replaced by forward slashes.
+ */
+export declare function toPosixPath(input: string): string;

package/dist/cli/helpers.js

@@ -0,0 +1,86 @@
+/**
+ * Package and file-system utility helpers used by CLI command modules.
+ */
+import path from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Resolve the absolute path to the package root directory.
+ *
+ * Uses `import.meta.url` to locate the directory containing `package.json`
+ * relative to the compiled output.
+ *
+ * @returns Absolute path to the package root (e.g. `/path/to/opencode-rag`).
+ */
+export function getPackageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+/**
+ * Read and parse `package.json` from the package root.
+ *
+ * @returns The parsed `PackageMetadata` containing name, version, and dependency maps.
+ * @throws {Error} If the package.json file cannot be read or parsed (e.g. merge conflicts).
+ */
+export function getPackageMetadata() {
+    const packageJsonPath = path.join(getPackageRoot(), "package.json");
+    try {
+        return JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    }
+    catch (cause) {
+        throw new Error(`Failed to parse package.json at ${packageJsonPath}. ` +
+            "This usually means the file contains invalid JSON, such as unresolved git merge conflict markers " +
+            "(<<<<<<<, =======, >>>>>>>). Resolve the conflict manually.\n" +
+            `Inner error: ${cause.message}`);
+    }
+}
+/**
+ * Filter an unknown value into a `Record<string, string>`.
+ *
+ * Returns an empty object if the value is not a plain object or contains
+ * non-string entries.
+ *
+ * @param value - The unknown value to normalize.
+ * @returns A record with only string-valued entries.
+ */
+export function getStringRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+/**
+ * Read a JSON file from disk and return it as a generic record.
+ *
+ * @param filePath - Absolute path to the JSON file.
+ * @returns The parsed object, or `undefined` if the file does not exist.
+ */
+export function readJsonObject(filePath) {
+    if (!existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse JSON at ${filePath}: ${err.message}`);
+    }
+}
+/**
+ * Write a JavaScript object to disk as pretty-printed JSON.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param value - The object to serialize (2-space indentation, trailing newline).
+ */
+export function writeJsonFile(filePath, value) {
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+/**
+ * Convert a platform-specific path to POSIX (forward-slash) format.
+ *
+ * @param input - A file path using the platform separator.
+ * @returns The same path with all backslashes replaced by forward slashes.
+ */
+export function toPosixPath(input) {
+    return input.split(path.sep).join("/");
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cli/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/cli/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,cAAc,CAAC,CAAC;IACpE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAoB,CAAC;IAC/E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,mCAAmC,eAAe,IAAI;YACpD,mGAAmG;YACnG,+DAA+D;YAC/D,gBAAiB,KAAe,CAAC,OAAO,EAAE,CAC7C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAA6B,EAAE,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CACjG,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAA4B,CAAC;IAChF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,KAA8B;IAC5E,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI entry point — creates the Commander program, wires all command modules,
+ * and handles auto-run detection for symlinked binaries.
+ *
+ * This file is compiled to `dist/cli/index.js`, the actual entry point
+ * referenced by the `bin` entry in `package.json`. The sibling file
+ * `dist/cli.js` is a backwards-compatibility re-export shim.
+ */
+/**
+ * Determine whether the CLI should auto-run for the current module.
+ *
+ * Resolves the first argv entry so symlinked binaries compare against the
+ * real file path, and returns `false` if the path cannot be resolved.
+ *
+ * @param moduleUrl - The `import.meta.url` of the CLI entry module.
+ * @param argv1 - The first CLI argument (`process.argv[1]`), typically the script path.
+ * @returns `true` if the resolved argv path matches the module URL.
+ */
+export declare function shouldAutoRunCli(moduleUrl: string, argv1?: string): boolean;
+/**
+ * Programmatically invoke the CLI with custom arguments.
+ *
+ * This is the public API entry point for running the CLI from code
+ * (e.g. from tests or the library export).
+ *
+ * @param argv - The argument vector to parse (defaults to `process.argv`).
+ */
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,104 @@
+/**
+ * CLI entry point — creates the Commander program, wires all command modules,
+ * and handles auto-run detection for symlinked binaries.
+ *
+ * This file is compiled to `dist/cli/index.js`, the actual entry point
+ * referenced by the `bin` entry in `package.json`. The sibling file
+ * `dist/cli.js` is a backwards-compatibility re-export shim.
+ */
+import { Command } from "commander";
+import { realpathSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, } from "./commands/index.js";
+/**
+ * The top-level Commander program instance that defines the `opencode-rag` CLI.
+ *
+ * All command modules register their sub-commands against this instance during
+ * module initialization. The program is parsed either on auto-run detection or
+ * when {@link runCli} is called programmatically.
+ */
+const program = new Command();
+program
+    .name("opencode-rag")
+    .description("Local-first RAG semantic code search");
+registerIndexCommand(program);
+registerQueryCommand(program);
+registerClearCommand(program);
+registerStatusCommand(program);
+registerListCommand(program);
+registerShowCommand(program);
+registerDumpCommand(program);
+registerDescribeImageCommand(program);
+registerUiCommand(program);
+registerMcpCommand(program);
+registerUpdateCommand(program);
+registerEvalSessionsCommand(program);
+registerEvalAnalyzeCommand(program);
+registerEvalCompareCommand(program);
+registerInitCommand(program);
+// ── Auto-run detection ──────────────────────────────────────────
+/**
+ * Determine whether the CLI should auto-run for the current module.
+ *
+ * Resolves the first argv entry so symlinked binaries compare against the
+ * real file path, and returns `false` if the path cannot be resolved.
+ *
+ * @param moduleUrl - The `import.meta.url` of the CLI entry module.
+ * @param argv1 - The first CLI argument (`process.argv[1]`), typically the script path.
+ * @returns `true` if the resolved argv path matches the module URL.
+ */
+export function shouldAutoRunCli(moduleUrl, argv1) {
+    if (!argv1) {
+        return false;
+    }
+    try {
+        const resolvedPath = realpathSync(argv1).replace(/\\/g, "/");
+        const normalizedUrl = moduleUrl.replace(/\\/g, "/");
+        return normalizedUrl === `file://${resolvedPath}` || normalizedUrl.endsWith(`/${resolvedPath}`) || normalizedUrl.includes(resolvedPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (shouldAutoRunCli(import.meta.url, process.argv[1])) {
+    void program.parseAsync(process.argv);
+}
+else {
+    // Fallback: auto-run only when the script being executed IS the CLI entry
+    // (detected by basename match). Avoids triggering on test runner imports
+    // or other modules that import the CLI programmatically.
+    const modulePath = fileURLToPath(import.meta.url);
+    const argvRaw = process.argv[1] ?? "";
+    const cliScript = basename(modulePath);
+    const runningScript = basename(argvRaw);
+    if (cliScript === runningScript) {
+        void program.parseAsync(process.argv);
+    }
+    else {
+        // Backwards-compatibility: when a shim points to the sibling cli.js
+        // (e.g. node dist/cli.js) but the real entry is dist/cli/index.js,
+        // check whether the running script lives in the same parent directory.
+        try {
+            const resolvedArgv = realpathSync(argvRaw);
+            if (dirname(resolvedArgv) === dirname(dirname(modulePath))) {
+                void program.parseAsync(process.argv);
+            }
+        }
+        catch {
+            // If the path cannot be resolved, skip auto-run.
+        }
+    }
+}
+/**
+ * Programmatically invoke the CLI with custom arguments.
+ *
+ * This is the public API entry point for running the CLI from code
+ * (e.g. from tests or the library export).
+ *
+ * @param argv - The argument vector to parse (defaults to `process.argv`).
+ */
+export async function runCli(argv = process.argv) {
+    await program.parseAsync(argv);
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,cAAc,CAAC;KACpB,WAAW,CAAC,sCAAsC,CAAC,CAAC;AAEvD,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,4BAA4B,CAAC,OAAO,CAAC,CAAC;AACtC,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,2BAA2B,CAAC,OAAO,CAAC,CAAC;AACrC,0BAA0B,CAAC,OAAO,CAAC,CAAC;AACpC,0BAA0B,CAAC,OAAO,CAAC,CAAC;AACpC,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAE7B,mEAAmE;AAEnE;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,KAAc;IAChE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC7D,MAAM,aAAa,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACpD,OAAO,aAAa,KAAK,UAAU,YAAY,EAAE,IAAI,aAAa,CAAC,QAAQ,CAAC,IAAI,YAAY,EAAE,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC1I,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;KAAM,CAAC;IACN,0EAA0E;IAC1E,yEAAyE;IACzE,yDAAyD;IACzD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;QAChC,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,oEAAoE;QACpE,mEAAmE;QACnE,uEAAuE;QACvE,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;gBAC3D,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;QACnD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAiB,OAAO,CAAC,IAAI;IACxD,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}

package/dist/cli/progress.d.ts

@@ -0,0 +1,39 @@
+import type { IndexProgress } from "../core/interfaces.js";
+/**
+ * Terminal-based progress reporter that renders a live-updating table of
+ * indexing progress for each file through the chunking → description → embedding pipeline.
+ *
+ * When output is a TTY, the table is re-rendered in-place on a 100 ms interval.
+ * For non-TTY streams (piped output), each finished or failed file is logged as a single line.
+ */
+export declare class TerminalProgressTable implements IndexProgress {
+    private stream;
+    private entries;
+    private failed;
+    private fileLabels;
+    private fileCount;
+    private maxLabelLength;
+    private renderedLineCount;
+    private dirty;
+    private timer;
+    private done_;
+    private isTTY;
+    /**
+     * @param stream - The write stream used for rendering (typically `process.stdout` or `process.stderr`).
+     */
+    constructor(stream: NodeJS.WriteStream);
+    /** Set the total number of files to be processed (shown in the table header). */
+    setFileCount(n: number): void;
+    /** Register a new file with the given label and reset its stage to 0. */
+    startFile(label: string): void;
+    /** Advance the file to its next pipeline stage. */
+    finishStage(label: string): void;
+    /** Mark the file as fully processed through all stages. */
+    finishFile(label: string): void;
+    /** Mark the file as failed and log the failure. */
+    failFile(label: string): void;
+    /** Signal that indexing is complete — flush remaining output and clean up the interval timer. */
+    done(): void;
+    private flush;
+    private render;
+}

package/dist/cli/progress.js

@@ -0,0 +1,137 @@
+const STAGE_LABELS = ["Chunking", "Description", "Embedding"];
+/** Build a human-readable breadcrumb trail through the indexing pipeline stages. */
+function formatBreadcrumb(stageIdx, failed) {
+    if (failed) {
+        return "Failed!";
+    }
+    const parts = [];
+    for (let i = 0; i < STAGE_LABELS.length; i++) {
+        if (i < stageIdx) {
+            parts.push(STAGE_LABELS[i]);
+        }
+        else if (i === stageIdx) {
+            parts.push(STAGE_LABELS[i] + "...");
+            break;
+        }
+        else {
+            break;
+        }
+    }
+    const breadcrumb = parts.join(" -> ");
+    if (stageIdx >= STAGE_LABELS.length) {
+        return breadcrumb + " -> Finished!";
+    }
+    return breadcrumb;
+}
+/** Format a single terminal progress line with padded label and breadcrumb. */
+function logLine(label, maxLabelLength, breadcrumb) {
+    return `  ${label.padEnd(maxLabelLength + 2)}${breadcrumb}`;
+}
+/**
+ * Terminal-based progress reporter that renders a live-updating table of
+ * indexing progress for each file through the chunking → description → embedding pipeline.
+ *
+ * When output is a TTY, the table is re-rendered in-place on a 100 ms interval.
+ * For non-TTY streams (piped output), each finished or failed file is logged as a single line.
+ */
+export class TerminalProgressTable {
+    stream;
+    entries = new Map();
+    failed = new Set();
+    fileLabels = [];
+    fileCount = 0;
+    maxLabelLength = 0;
+    renderedLineCount = 0;
+    dirty = false;
+    timer = null;
+    done_ = false;
+    isTTY;
+    /**
+     * @param stream - The write stream used for rendering (typically `process.stdout` or `process.stderr`).
+     */
+    constructor(stream) {
+        this.stream = stream;
+        this.isTTY = stream.isTTY;
+        if (this.isTTY) {
+            this.timer = setInterval(() => this.flush(), 100);
+        }
+    }
+    /** Set the total number of files to be processed (shown in the table header). */
+    setFileCount(n) {
+        this.fileCount = n;
+        this.dirty = true;
+    }
+    /** Register a new file with the given label and reset its stage to 0. */
+    startFile(label) {
+        if (!this.entries.has(label)) {
+            this.fileLabels.push(label);
+            this.maxLabelLength = Math.max(this.maxLabelLength, label.length);
+        }
+        this.entries.set(label, 0);
+        this.dirty = true;
+    }
+    /** Advance the file to its next pipeline stage. */
+    finishStage(label) {
+        const idx = this.entries.get(label);
+        if (idx !== undefined && idx < STAGE_LABELS.length) {
+            this.entries.set(label, idx + 1);
+            this.dirty = true;
+        }
+    }
+    /** Mark the file as fully processed through all stages. */
+    finishFile(label) {
+        const idx = this.entries.get(label);
+        if (idx !== undefined) {
+            this.entries.set(label, STAGE_LABELS.length);
+            this.dirty = true;
+            if (!this.isTTY) {
+                console.log(logLine(label, this.maxLabelLength, formatBreadcrumb(STAGE_LABELS.length)));
+            }
+        }
+    }
+    /** Mark the file as failed and log the failure. */
+    failFile(label) {
+        this.failed.add(label);
+        this.dirty = true;
+        if (!this.isTTY) {
+            console.log(logLine(label, this.maxLabelLength, formatBreadcrumb(0, true)));
+        }
+    }
+    /** Signal that indexing is complete — flush remaining output and clean up the interval timer. */
+    done() {
+        this.done_ = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.flush();
+        this.stream.write("\n");
+    }
+    flush() {
+        if (!this.dirty || this.done_)
+            return;
+        this.dirty = false;
+        this.render();
+    }
+    render() {
+        if (!this.isTTY)
+            return;
+        const lines = [];
+        if (this.fileCount > 0) {
+            lines.push(`Indexing ${this.fileCount} files:`);
+        }
+        for (const label of this.fileLabels) {
+            const stageIdx = this.entries.get(label);
+            if (stageIdx === undefined)
+                continue;
+            lines.push(logLine(label, this.maxLabelLength, formatBreadcrumb(stageIdx, this.failed.has(label))));
+        }
+        const clearCount = this.renderedLineCount;
+        if (clearCount > 0) {
+            this.stream.write(`\x1b[${clearCount}A\x1b[J`);
+        }
+        this.stream.write(lines.join("\n"));
+        this.renderedLineCount = lines.length;
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/cli/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/cli/progress.ts"],"names":[],"mappings":"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"}

package/dist/cli/types.d.ts

@@ -0,0 +1,40 @@
+/** Shared CLI option interfaces used by all command modules. */
+/** Standard CLI options shared by most commands (index, query, clear, etc.). */
+export interface CliOptions {
+    /** Optional path to an `opencode-rag.json` config file. */
+    config?: string;
+    /** Force a full re-index when set. */
+    force?: boolean;
+    /** Watch workspace for changes and re-index automatically. */
+    watch?: boolean;
+    /** Maximum number of results to return (query command). */
+    topK?: string;
+    /** Chunk offset for paginated dump output. */
+    offset?: string;
+    /** Maximum number of chunks to dump. */
+    limit?: string;
+    /** Show hybrid score breakdown in query results. */
+    explain?: boolean;
+    /** Skip confirmation prompts for destructive operations. */
+    yes?: boolean;
+}
+/** Options for the `init` command. */
+export interface InitOptions {
+    /** Overwrite existing files during initialization. */
+    force?: boolean;
+    /** Skip installing workspace-local plugin dependencies. */
+    skipInstall?: boolean;
+    /** Skip provider connectivity and model availability check. */
+    skipHealthCheck?: boolean;
+}
+/** Shape of the `package.json` metadata required by CLI helpers. */
+export interface PackageMetadata {
+    /** The npm package name. */
+    name: string;
+    /** The semver version string. */
+    version: string;
+    /** Dev dependencies map, used to resolve plugin versions. */
+    devDependencies?: Record<string, string>;
+    /** Peer dependencies map, used to resolve plugin versions. */
+    peerDependencies?: Record<string, string>;
+}

package/dist/cli/types.js

@@ -0,0 +1,3 @@
+/** Shared CLI option interfaces used by all command modules. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cli/types.ts"],"names":[],"mappings":"AAAA,gEAAgE"}

package/dist/cli.d.ts

@@ -1,4 +1,11 @@
-#!/usr/bin/env node
-export declare function removeStaleGlobalPluginRegistrations(homeDir: string, pluginName: string): string[];
-export declare function shouldAutoRunCli(moduleUrl: string, argv1?: string): boolean;
-export declare function runCli(argv?: string[]): Promise<void>;
+/**
+ * Backwards-compatibility shim — re-exports the public API from the new
+ * `cli/` module tree so existing tests and external consumers that import
+ * from `../cli.js` continue to work unchanged.
+ *
+ * The actual CLI entry point is now `cli/index.ts` (compiled to `dist/cli/index.js`).
+ */
+/** Main CLI runner and auto-launch detection. */
+export { runCli, shouldAutoRunCli } from "./cli/index.js";
+/** Cleanup helper that removes stale global plugin registration symlinks. */
+export { removeStaleGlobalPluginRegistrations } from "./cli/commands/init-helpers.js";