@bndynet/ragbox 0.1.0

package/dist/src/cli.js

@@ -0,0 +1,1013 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const commander_1 = require("commander");
+const config_file_1 = require("./config-file");
+const config_1 = require("./folder-index/config");
+const indexer_1 = require("./folder-index/indexer");
+const manifest_1 = require("./folder-index/manifest");
+const multi_query_1 = require("./folder-index/multi-query");
+const query_1 = require("./folder-index/query");
+const watch_1 = require("./folder-index/watch");
+const serve_1 = require("./serve");
+const setup_pageindex_1 = require("./setup-pageindex");
+const sdk_1 = require("./sdk");
+function parseConcurrency(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error("--concurrency must be a positive integer");
+    }
+    return parsed;
+}
+function parseNonNegativeInteger(value, optionName) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${optionName} must be a non-negative integer`);
+    }
+    return parsed;
+}
+function parseRetryAttempts(value) {
+    return parseNonNegativeInteger(value, "--retry-attempts");
+}
+function parseRetryDelayMs(value) {
+    return parseNonNegativeInteger(value, "--retry-delay-ms");
+}
+function parseDebounceMs(value) {
+    return parseNonNegativeInteger(value, "--debounce-ms");
+}
+function parseServePort(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 65535) {
+        throw new Error("--port must be an integer between 0 and 65535");
+    }
+    return parsed;
+}
+function isVerbose() {
+    return process.env.RAGBOX_VERBOSE === "1" || process.env.RAGBOX_E2E_VERBOSE === "1";
+}
+function logProgress(event) {
+    if (!isVerbose()) {
+        return;
+    }
+    switch (event.type) {
+        case "scan":
+            console.error(`[ragbox] scan root=${event.rootDir} output=${event.outputDir} total=${event.total} toIndex=${event.toIndex} unchanged=${event.unchanged} deleted=${event.deleted}`);
+            break;
+        case "index-start":
+            console.error(`[ragbox] index start ${event.index}/${event.total} ${event.path}`);
+            break;
+        case "index-done":
+            console.error(`[ragbox] index done ${event.index}/${event.total} ${event.path}`);
+            if (event.summary) {
+                console.error(`[ragbox] summary ${event.path}: ${event.summary}`);
+            }
+            break;
+        case "index-failed":
+            console.error(`[ragbox] index failed ${event.index}/${event.total} ${event.path}: ${event.error}`);
+            break;
+        case "write":
+            console.error(`[ragbox] wrote manifest=${event.manifestPath}`);
+            console.error(`[ragbox] wrote rootTree=${event.rootTreePath}`);
+            break;
+    }
+}
+function addLlmOptions(command) {
+    return command
+        .option("--api-key <key>", "OpenAI-compatible API key")
+        .option("--base-url <url>", "OpenAI-compatible API base URL")
+        .option("--model <model>", "LLM model");
+}
+function addProjectOptions(command) {
+    return command.option("--source <name>", "ragbox config source; query accepts comma-separated names");
+}
+function getGlobalOptions(command) {
+    let current = command;
+    while (current) {
+        const options = current.opts();
+        if (options.config) {
+            return { config: options.config };
+        }
+        current = current.parent;
+    }
+    return {};
+}
+function writeJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function writeJsonLine(value) {
+    console.log(JSON.stringify(value));
+}
+function indentMultiline(value, prefix) {
+    return value
+        .split(/\r?\n/)
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+function indexCounts(result) {
+    return {
+        total: result.manifest.documents.length,
+        ready: result.ready,
+        failed: result.failed,
+        added: result.added,
+        modified: result.modified,
+        retryFailed: result.retryFailed,
+        unchanged: result.unchanged,
+        deleted: result.deleted
+    };
+}
+function indexFailures(result) {
+    return result.manifest.documents
+        .filter((document) => document.status === "failed")
+        .map((document) => ({
+        path: document.path,
+        absolutePath: document.absolutePath,
+        indexPath: document.indexPath,
+        error: document.error
+    }));
+}
+function indexJsonOutput(result) {
+    return {
+        version: 1,
+        command: "index",
+        rootDir: result.manifest.rootDir,
+        outputDir: result.outputDir,
+        manifestPath: result.manifestPath,
+        rootTreePath: result.rootTreePath,
+        generatedAt: result.manifest.generatedAt,
+        counts: indexCounts(result),
+        failures: indexFailures(result)
+    };
+}
+function printIndexResult(folder, result) {
+    console.log(`Indexed ${folder}`);
+    console.log(`ready=${result.ready}`);
+    console.log(`failed=${result.failed}`);
+    console.log(`added=${result.added}`);
+    console.log(`modified=${result.modified}`);
+    console.log(`retryFailed=${result.retryFailed}`);
+    console.log(`deleted=${result.deleted}`);
+    console.log(`unchanged=${result.unchanged}`);
+    const failures = indexFailures(result);
+    if (failures.length === 0) {
+        return;
+    }
+    console.error("Failed documents:");
+    for (const failure of failures) {
+        console.error(`- ${failure.path}`);
+        if (failure.error) {
+            console.error(indentMultiline(failure.error, "  "));
+        }
+    }
+}
+function printSetupPageIndexResult(result) {
+    console.log(`PageIndex ready: ${result.pageIndexDir}`);
+    console.log(`cli=${result.cliPath}`);
+    if (result.pythonPath) {
+        console.log(`python=${result.pythonPath}`);
+    }
+    if (result.configPath) {
+        console.log(`config=${result.configPath}`);
+    }
+    if (result.gitignorePath) {
+        console.log(`${result.actions.updatedGitignore ? "updated" : "checked"} gitignore=${result.gitignorePath}`);
+    }
+}
+function logProgressAsJsonLine(event) {
+    writeJsonLine({
+        version: 1,
+        timestamp: new Date().toISOString(),
+        type: "index-progress",
+        event
+    });
+}
+async function loadCommandConfig(command, commandOptions) {
+    const globalOptions = getGlobalOptions(command);
+    const resolved = await (0, config_file_1.resolveRagboxConfig)({
+        configPath: globalOptions.config,
+        source: commandOptions.source
+    });
+    return {
+        rootDir: resolved.rootDir,
+        options: resolved.pageIndexOptions
+    };
+}
+function mergeDefined(...values) {
+    const merged = {};
+    for (const value of values) {
+        for (const [key, nestedValue] of Object.entries(value)) {
+            if (nestedValue !== undefined) {
+                merged[key] = nestedValue;
+            }
+        }
+    }
+    return merged;
+}
+function buildOptions(configOptions, commandOptions, progress = logProgress) {
+    return mergeDefined({
+        ...configOptions,
+        progress
+    }, {
+        apiKey: commandOptions.apiKey,
+        baseUrl: commandOptions.baseUrl,
+        concurrency: commandOptions.concurrency,
+        cliPath: commandOptions.pageindexCli,
+        model: commandOptions.model,
+        outputDir: commandOptions.outputDir,
+        pythonPath: commandOptions.pageindexPython,
+        watchDebounceMs: commandOptions.debounceMs,
+        watchHealthFile: commandOptions.healthFile,
+        watchLockFile: commandOptions.lockFile,
+        watchRetryAttempts: commandOptions.retryAttempts,
+        watchRetryDelayMs: commandOptions.retryDelayMs,
+        watchStaging: commandOptions.staging ?? Boolean(commandOptions.stagingOutputDir),
+        watchStagingOutputDir: commandOptions.stagingOutputDir,
+        watchWebhookUrl: commandOptions.webhook
+    });
+}
+function buildQueryOptions(configOptions, commandOptions) {
+    return mergeDefined({
+        ...configOptions
+    }, {
+        apiKey: commandOptions.apiKey,
+        baseUrl: commandOptions.baseUrl,
+        model: commandOptions.model,
+        trace: commandOptions.trace
+    });
+}
+function parseSourceNames(source) {
+    return (source ?? "")
+        .split(",")
+        .map((name) => name.trim())
+        .filter(Boolean);
+}
+function requireFolder(folder, commandName) {
+    if (!folder) {
+        throw new Error(`Missing folder. Pass a folder argument or configure a source rootDir before running ragbox ${commandName}.`);
+    }
+    return folder;
+}
+function requireTarget(target) {
+    if (!target) {
+        throw new Error("Missing query target. Pass a target argument or configure a source with outputDir/rootDir.");
+    }
+    return target;
+}
+function requireQuestion(question) {
+    if (!question) {
+        throw new Error("Missing question.");
+    }
+    return question;
+}
+async function pathExists(value) {
+    try {
+        await promises_1.default.access(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function startTargetOutputDir(rootDir, options) {
+    return node_path_1.default.resolve(options.outputDir ?? node_path_1.default.join(rootDir, manifest_1.PAGEINDEX_DIR));
+}
+async function loadConfiguredQueryTargets(command, commandOptions) {
+    const globalOptions = getGlobalOptions(command);
+    if (commandOptions.allSources && commandOptions.source) {
+        throw new Error("Use either --source or --all-sources, not both.");
+    }
+    let sourceNames = parseSourceNames(commandOptions.source);
+    if (commandOptions.allSources) {
+        const { config } = await (0, config_file_1.readRagboxConfig)(globalOptions.config);
+        sourceNames = (0, config_file_1.listRagboxConfigSourceNames)(config);
+        if (sourceNames.length === 0) {
+            throw new Error("No configured sources found. Add docs or sources to ragbox.config.json.");
+        }
+    }
+    const targets = [];
+    let answerOptions;
+    for (const sourceName of sourceNames) {
+        const resolved = await (0, config_file_1.resolveRagboxConfig)({
+            configPath: globalOptions.config,
+            source: sourceName
+        });
+        const target = resolved.pageIndexOptions.outputDir ?? resolved.rootDir;
+        if (!target) {
+            throw new Error(`Source does not define outputDir or rootDir: ${sourceName}`);
+        }
+        const options = buildQueryOptions(resolved.pageIndexOptions, commandOptions);
+        answerOptions ??= options;
+        targets.push({
+            name: sourceName,
+            target,
+            options
+        });
+    }
+    return {
+        answerOptions: answerOptions ?? buildQueryOptions({}, commandOptions),
+        targets
+    };
+}
+async function shouldQueryAllSourcesByDefault(command, target, question, sourceNames) {
+    if (!target || question || sourceNames.length > 0) {
+        return false;
+    }
+    if (await pathExists(target)) {
+        return false;
+    }
+    const globalOptions = getGlobalOptions(command);
+    const { config } = await (0, config_file_1.readRagboxConfig)(globalOptions.config);
+    return (0, config_file_1.listRagboxConfigSourceNames)(config).length > 1;
+}
+async function loadDiagnosticTargets(command, commandOptions, target, allSourcesByDefault) {
+    if (target) {
+        return [
+            {
+                target,
+                options: buildQueryOptions({}, commandOptions)
+            }
+        ];
+    }
+    const globalOptions = getGlobalOptions(command);
+    if (commandOptions.allSources && commandOptions.source) {
+        throw new Error("Use either --source or --all-sources, not both.");
+    }
+    let sourceNames = parseSourceNames(commandOptions.source);
+    if (commandOptions.allSources || (allSourcesByDefault && sourceNames.length === 0)) {
+        const { config } = await (0, config_file_1.readRagboxConfig)(globalOptions.config);
+        const configuredSourceNames = (0, config_file_1.listRagboxConfigSourceNames)(config);
+        if (commandOptions.allSources || configuredSourceNames.length > 1) {
+            sourceNames = configuredSourceNames;
+        }
+    }
+    if (sourceNames.length > 0) {
+        const targets = [];
+        for (const sourceName of sourceNames) {
+            const resolved = await (0, config_file_1.resolveRagboxConfig)({
+                configPath: globalOptions.config,
+                source: sourceName
+            });
+            const resolvedTarget = resolved.pageIndexOptions.outputDir ?? resolved.rootDir;
+            if (!resolvedTarget) {
+                throw new Error(`Source does not define outputDir or rootDir: ${sourceName}`);
+            }
+            targets.push({
+                source: sourceName,
+                target: resolvedTarget,
+                options: buildQueryOptions(resolved.pageIndexOptions, commandOptions)
+            });
+        }
+        return targets;
+    }
+    const loaded = await loadCommandConfig(command, commandOptions);
+    const resolvedTarget = loaded.options.outputDir ?? loaded.rootDir;
+    return [
+        {
+            target: requireTarget(resolvedTarget),
+            options: buildQueryOptions(loaded.options, commandOptions)
+        }
+    ];
+}
+async function loadStartTargets(command, commandOptions, folder) {
+    if (folder) {
+        if (commandOptions.allSources || commandOptions.source) {
+            throw new Error("A folder argument cannot be combined with --source or --all-sources.");
+        }
+        const loaded = await loadCommandConfig(command, commandOptions);
+        const rootDir = node_path_1.default.resolve(folder);
+        const options = buildOptions(loaded.options, commandOptions, commandOptions.jsonl ? logProgressAsJsonLine : logProgress);
+        return [
+            {
+                rootDir,
+                target: startTargetOutputDir(rootDir, options),
+                options
+            }
+        ];
+    }
+    const globalOptions = getGlobalOptions(command);
+    if (commandOptions.allSources && commandOptions.source) {
+        throw new Error("Use either --source or --all-sources, not both.");
+    }
+    let sourceNames = parseSourceNames(commandOptions.source);
+    if (commandOptions.allSources || sourceNames.length === 0) {
+        const { config } = await (0, config_file_1.readRagboxConfig)(globalOptions.config);
+        const configuredSourceNames = (0, config_file_1.listRagboxConfigSourceNames)(config);
+        if (commandOptions.allSources || configuredSourceNames.length > 1) {
+            sourceNames = configuredSourceNames;
+        }
+    }
+    if (sourceNames.length > 0) {
+        if (sourceNames.length > 1 && commandOptions.outputDir) {
+            throw new Error("--output-dir cannot be used when starting multiple sources.");
+        }
+        const targets = [];
+        for (const sourceName of sourceNames) {
+            const resolved = await (0, config_file_1.resolveRagboxConfig)({
+                configPath: globalOptions.config,
+                source: sourceName
+            });
+            const rootDir = requireFolder(resolved.rootDir, "start");
+            const options = buildOptions(resolved.pageIndexOptions, commandOptions, commandOptions.jsonl ? logProgressAsJsonLine : logProgress);
+            targets.push({
+                source: sourceName,
+                rootDir,
+                target: startTargetOutputDir(rootDir, options),
+                options
+            });
+        }
+        return targets;
+    }
+    const loaded = await loadCommandConfig(command, commandOptions);
+    const rootDir = requireFolder(loaded.rootDir, "start");
+    const options = buildOptions(loaded.options, commandOptions, commandOptions.jsonl ? logProgressAsJsonLine : logProgress);
+    return [
+        {
+            source: commandOptions.source,
+            rootDir,
+            target: startTargetOutputDir(rootDir, options),
+            options
+        }
+    ];
+}
+async function buildStatusOutput(targets) {
+    const statusTargets = [];
+    for (const target of targets) {
+        const validation = await (0, sdk_1.validateIndex)(target.target);
+        statusTargets.push({
+            source: target.source,
+            target: target.target,
+            ok: validation.ok,
+            inspect: validation.inspect,
+            errors: validation.errors,
+            warnings: validation.warnings
+        });
+    }
+    return {
+        version: 1,
+        command: "status",
+        ok: statusTargets.every((target) => target.ok),
+        targets: statusTargets
+    };
+}
+function printStatusOutput(status) {
+    for (const target of status.targets) {
+        const label = target.source ? `${target.source} ${target.target}` : target.target;
+        console.log(`${target.ok ? "ok" : "error"} ${label}`);
+        if (target.inspect) {
+            const counts = target.inspect.counts;
+            console.log(`  documents=${counts.total} ready=${counts.ready} failed=${counts.failed}`);
+            console.log(`  output=${target.inspect.outputDir}`);
+            console.log(`  generatedAt=${target.inspect.generatedAt}`);
+        }
+        for (const error of target.errors) {
+            console.log(`  error ${error.code}: ${error.message}`);
+        }
+        for (const warning of target.warnings) {
+            console.log(`  warning ${warning.code}: ${warning.message}`);
+        }
+    }
+}
+function startTargetLabel(target) {
+    return target.source ? `${target.source} ${target.rootDir}` : target.rootDir;
+}
+function writeStartJsonLine(type, fields = {}) {
+    writeJsonLine({
+        version: 1,
+        timestamp: new Date().toISOString(),
+        type,
+        ...fields
+    });
+}
+function printStartWatchEvent(event, source) {
+    const prefix = source ? `[${source}] ` : "";
+    switch (event.type) {
+        case "watch-start":
+            console.log(`${prefix}watching ${event.rootDir}`);
+            break;
+        case "watch-file-event":
+            console.log(`${prefix}${event.eventName}: ${event.path}`);
+            break;
+        case "watch-index-start":
+            console.log(`${prefix}index ${event.reason} attempt=${event.attempt}/${event.maxAttempts}`);
+            break;
+        case "watch-index-done":
+            console.log(`${prefix}indexed ready=${event.result.ready} failed=${event.result.failed} added=${event.result.added} modified=${event.result.modified} deleted=${event.result.deleted} unchanged=${event.result.unchanged}`);
+            break;
+        case "watch-index-failed":
+            console.error(`${prefix}index failed: ${event.error}`);
+            break;
+        case "watch-index-retry":
+            console.error(`${prefix}index retry in ${event.delayMs}ms: ${event.error}`);
+            break;
+        case "watch-output-promoted":
+            console.log(`${prefix}promoted staging output ${event.stagingOutputDir}`);
+            break;
+        case "watch-stop":
+            console.log(`${prefix}watch stopped`);
+            break;
+    }
+}
+async function closeStartHandles(watchHandles, serveHandle) {
+    await Promise.allSettled([
+        ...watchHandles.map((handle) => handle.close()),
+        ...(serveHandle ? [serveHandle.close()] : [])
+    ]);
+}
+function isPathLikeCommand(value) {
+    return node_path_1.default.isAbsolute(value) || value.startsWith(".") || value.includes("/") || value.includes("\\");
+}
+async function commandPathExists(value) {
+    if (!value || !isPathLikeCommand(value)) {
+        return undefined;
+    }
+    return await pathExists(value);
+}
+async function buildDoctorOutput(command, commandOptions, target) {
+    const globalOptions = getGlobalOptions(command);
+    const checks = [];
+    const { configPath } = await (0, config_file_1.readRagboxConfig)(globalOptions.config);
+    checks.push({
+        name: "config",
+        ok: true,
+        message: configPath ? `Loaded config: ${configPath}` : "No ragbox config found; using CLI flags, environment, and defaults.",
+        path: configPath
+    });
+    let targets = [];
+    try {
+        targets = await loadDiagnosticTargets(command, commandOptions, target, true);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        checks.push({
+            name: "target",
+            ok: false,
+            message
+        });
+    }
+    const options = targets[0]?.options ?? buildQueryOptions({}, commandOptions);
+    const runtime = (0, config_1.loadPageIndexConfig)(options);
+    const cliExists = await commandPathExists(runtime.cliPath);
+    checks.push({
+        name: "pageindex-cli",
+        ok: Boolean(runtime.cliPath) && cliExists !== false,
+        message: !runtime.cliPath
+            ? "PAGEINDEX_CLI or pageIndex.cli is not configured."
+            : cliExists === false
+                ? `PageIndex CLI does not exist: ${runtime.cliPath}`
+                : `PageIndex CLI configured: ${runtime.cliPath}`,
+        path: runtime.cliPath
+    });
+    checks.push({
+        name: "llm-model",
+        ok: Boolean(runtime.model),
+        message: `LLM model: ${runtime.model}`
+    });
+    checks.push({
+        name: "llm-base-url",
+        ok: Boolean(runtime.baseUrl),
+        message: `LLM base URL: ${runtime.baseUrl}`
+    });
+    checks.push({
+        name: "llm-api-key",
+        ok: Boolean(runtime.apiKey),
+        message: runtime.apiKey ? "LLM API key is configured." : "OPENAI_API_KEY or llm.apiKey is not configured."
+    });
+    const status = await buildStatusOutput(targets);
+    checks.push({
+        name: "index-status",
+        ok: status.ok,
+        message: status.targets.length > 0 ? `Checked ${status.targets.length} index target(s).` : "No index target was checked."
+    });
+    return {
+        version: 1,
+        command: "doctor",
+        ok: checks.every((check) => check.ok),
+        checks,
+        status
+    };
+}
+function printDoctorOutput(doctor) {
+    for (const check of doctor.checks) {
+        console.log(`${check.ok ? "ok" : "error"} ${check.name}: ${check.message}`);
+    }
+    printStatusOutput(doctor.status);
+}
+function printInspectResult(result, source) {
+    const label = source ? `${source} ${result.target}` : result.target;
+    console.log(`Index ${label}`);
+    console.log(`rootDir=${result.rootDir}`);
+    console.log(`outputDir=${result.outputDir}`);
+    console.log(`generatedAt=${result.generatedAt}`);
+    console.log(`documents=${result.counts.total}`);
+    console.log(`ready=${result.counts.ready}`);
+    console.log(`failed=${result.counts.failed}`);
+    for (const document of result.documents) {
+        console.log(`- ${document.status} ${document.path}`);
+    }
+}
+async function runQueryAction(target, question, commandOptions, command) {
+    const sourceNames = parseSourceNames(commandOptions.source);
+    const implicitAllSources = await shouldQueryAllSourcesByDefault(command, target, question, sourceNames);
+    if (commandOptions.allSources || sourceNames.length > 1 || implicitAllSources) {
+        if (question) {
+            throw new Error("Multi-source query uses configured sources; pass only the question argument.");
+        }
+        const multiSourceOptions = implicitAllSources ? { ...commandOptions, allSources: true } : commandOptions;
+        const loadedSources = await loadConfiguredQueryTargets(command, multiSourceOptions);
+        const result = await (0, multi_query_1.queryMultipleIndexes)(loadedSources.targets, requireQuestion(target), loadedSources.answerOptions);
+        if (commandOptions.json || commandOptions.trace) {
+            writeJson(result);
+            return;
+        }
+        console.log(result.answer);
+        return;
+    }
+    const singleSourceOptions = sourceNames.length === 1 ? { ...commandOptions, source: sourceNames[0] } : commandOptions;
+    const loaded = await loadCommandConfig(command, singleSourceOptions);
+    let queryTarget = target;
+    let queryQuestion = question;
+    const configuredTarget = loaded.options.outputDir ?? loaded.rootDir;
+    if (!queryQuestion && queryTarget && configuredTarget) {
+        const singleArgIsQuestion = singleSourceOptions.source || !(await pathExists(queryTarget));
+        if (singleArgIsQuestion) {
+            queryQuestion = queryTarget;
+            queryTarget = undefined;
+        }
+    }
+    queryTarget ??= configuredTarget;
+    const result = await (0, query_1.queryFolder)(requireTarget(queryTarget), requireQuestion(queryQuestion), buildQueryOptions(loaded.options, singleSourceOptions));
+    if (commandOptions.json || commandOptions.trace) {
+        writeJson(result);
+        return;
+    }
+    console.log(result.answer);
+}
+async function runStartAction(folder, commandOptions, command) {
+    const globalOptions = getGlobalOptions(command);
+    const targets = await loadStartTargets(command, commandOptions, folder);
+    const watchHandles = [];
+    let serveHandle;
+    let reloading = false;
+    let reloadAgain = false;
+    async function reloadServe() {
+        if (!serveHandle) {
+            return;
+        }
+        if (reloading) {
+            reloadAgain = true;
+            return;
+        }
+        reloading = true;
+        do {
+            reloadAgain = false;
+            try {
+                const result = await serveHandle.reload();
+                if (commandOptions.jsonl) {
+                    writeStartJsonLine("start-serve-reload", {
+                        indexes: result.indexes.map((index) => ({
+                            source: index.source,
+                            target: index.target,
+                            ok: index.ok
+                        }))
+                    });
+                }
+                else {
+                    console.log(`Reloaded serve index snapshot (${result.indexes.filter((index) => index.ok).length}/${result.indexes.length} ready)`);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (commandOptions.jsonl) {
+                    writeStartJsonLine("start-serve-reload-failed", { error: message });
+                }
+                else {
+                    console.error(`Serve reload failed: ${message}`);
+                }
+            }
+        } while (reloadAgain);
+        reloading = false;
+    }
+    try {
+        if (commandOptions.jsonl) {
+            writeStartJsonLine("start", {
+                sources: targets.map((target) => target.source).filter(Boolean),
+                targets: targets.map((target) => target.target)
+            });
+        }
+        else {
+            console.log(`Starting ragbox for ${targets.length} source${targets.length === 1 ? "" : "s"}`);
+        }
+        for (const target of targets) {
+            const handle = await (0, watch_1.startWatchFolder)(target.rootDir, {
+                ...target.options,
+                watchProgress: (event) => {
+                    if (commandOptions.jsonl) {
+                        writeJsonLine(event);
+                    }
+                    else {
+                        printStartWatchEvent(event, target.source);
+                    }
+                    if (event.type === "watch-index-done") {
+                        void reloadServe();
+                    }
+                }
+            });
+            watchHandles.push(handle);
+        }
+        const readyResults = await Promise.all(watchHandles.map((handle) => handle.ready));
+        const failedReady = readyResults.find((ready) => !ready.ok);
+        if (failedReady && !failedReady.ok) {
+            throw new Error(`Initial index failed: ${failedReady.error}`);
+        }
+        const sourceNames = targets.map((target) => target.source).filter((source) => Boolean(source));
+        const singleTarget = targets.length === 1 ? targets[0] : undefined;
+        serveHandle = await (0, serve_1.startServe)({
+            allSources: targets.length > 1 && sourceNames.length === 0,
+            apiKey: commandOptions.apiKey,
+            authToken: commandOptions.authToken,
+            baseUrl: commandOptions.baseUrl,
+            configPath: globalOptions.config,
+            host: commandOptions.host,
+            model: commandOptions.model,
+            port: commandOptions.port,
+            source: targets.length > 1 ? sourceNames : undefined,
+            target: singleTarget ? singleTarget.target : undefined
+        });
+        if (commandOptions.jsonl) {
+            writeStartJsonLine("start-serve", {
+                url: serveHandle.url,
+                host: serveHandle.host,
+                port: serveHandle.port
+            });
+        }
+        else {
+            console.log(`Serving ragbox at ${serveHandle.url}`);
+        }
+        await new Promise((resolve) => {
+            let closing = false;
+            const stop = () => {
+                if (closing) {
+                    return;
+                }
+                closing = true;
+                void closeStartHandles(watchHandles, serveHandle).finally(resolve);
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+            serveHandle?.server.once("close", stop);
+        });
+    }
+    catch (error) {
+        await closeStartHandles(watchHandles, serveHandle);
+        throw error;
+    }
+}
+async function main() {
+    const program = new commander_1.Command();
+    program
+        .name("ragbox")
+        .description("Index and query a Markdown/MDX folder with PageIndex")
+        .version("0.1.0")
+        .option("--config <path-or-name>", "ragbox config file path, or a name like prod for ragbox.config.prod.json");
+    program
+        .command("init")
+        .description("create a ragbox.config.json file")
+        .option("--docs-dir <folder>", "default docs folder in the generated config", "./docs")
+        .option("-f, --force", "overwrite an existing config file")
+        .option("-o, --output <path>", "config file path")
+        .option("--output-dir <folder>", "default index output directory in the generated config", "./.ragbox-index")
+        .action(async (commandOptions) => {
+        const configPath = await (0, config_file_1.writeDefaultRagboxConfig)({
+            configPath: commandOptions.output,
+            docsDir: commandOptions.docsDir,
+            force: commandOptions.force,
+            outputDir: commandOptions.outputDir
+        });
+        console.log(`Created ${configPath}`);
+    });
+    const setupCommand = program
+        .command("setup")
+        .description("setup local ragbox dependencies");
+    setupCommand
+        .command("pageindex")
+        .description("clone PageIndex and configure ragbox to use it")
+        .option("--dir <folder>", "PageIndex checkout directory", "./.ragbox/PageIndex")
+        .option("--repo <url>", "PageIndex git repository", "https://github.com/VectifyAI/PageIndex.git")
+        .option("--ref <ref>", "PageIndex branch, tag, or commit to checkout")
+        .option("--python <path>", "Python executable used to create the PageIndex virtual environment", "python3")
+        .option("--skip-install", "skip virtual environment creation and pip install")
+        .option("--no-write-config", "do not create or update ragbox.config.json")
+        .option("--no-gitignore", "do not add .ragbox/ to .gitignore")
+        .option("--json", "print a stable JSON result")
+        .action(async (commandOptions, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const result = await (0, setup_pageindex_1.setupPageIndex)({
+            configPath: globalOptions.config,
+            dir: commandOptions.dir,
+            gitignore: commandOptions.gitignore !== false,
+            install: !commandOptions.skipInstall,
+            python: commandOptions.python,
+            ref: commandOptions.ref,
+            repo: commandOptions.repo,
+            writeConfig: commandOptions.writeConfig !== false
+        });
+        if (commandOptions.json) {
+            writeJson(result);
+            return;
+        }
+        printSetupPageIndexResult(result);
+    });
+    addProjectOptions(addLlmOptions(program
+        .command("index")
+        .argument("[folder]", "folder to index")
+        .option("-c, --concurrency <number>", "PageIndex concurrency", parseConcurrency)
+        .option("--pageindex-cli <path>", "PageIndex script path")
+        .option("-o, --output-dir <folder>", "folder for ragbox index files")
+        .option("--pageindex-python <path>", "Python executable used to run PageIndex")
+        .option("--json", "print a stable JSON result")))
+        .action(async (folder, commandOptions, command) => {
+        const loaded = await loadCommandConfig(command, commandOptions);
+        const indexFolderPath = requireFolder(folder ?? loaded.rootDir, "index");
+        const result = await (0, indexer_1.indexFolder)(indexFolderPath, buildOptions(loaded.options, commandOptions));
+        if (commandOptions.json) {
+            writeJson(indexJsonOutput(result));
+            return;
+        }
+        printIndexResult(indexFolderPath, result);
+    });
+    addProjectOptions(program
+        .command("inspect")
+        .argument("[target]", "docs folder or ragbox output directory")
+        .option("--all-sources", "inspect every configured source")
+        .option("--json", "print a stable JSON result"))
+        .action(async (target, commandOptions, command) => {
+        const targets = await loadDiagnosticTargets(command, commandOptions, target, false);
+        const results = [];
+        for (const diagnosticTarget of targets) {
+            results.push({
+                source: diagnosticTarget.source,
+                ...(await (0, sdk_1.inspectIndex)(diagnosticTarget.target))
+            });
+        }
+        if (commandOptions.json) {
+            writeJson(results.length === 1
+                ? results[0]
+                : {
+                    version: 1,
+                    command: "inspect",
+                    indexes: results
+                });
+            return;
+        }
+        for (const result of results) {
+            printInspectResult(result, result.source);
+        }
+    });
+    addProjectOptions(program
+        .command("status")
+        .argument("[target]", "docs folder or ragbox output directory")
+        .option("--all-sources", "check every configured source")
+        .option("--json", "print a stable JSON result"))
+        .action(async (target, commandOptions, command) => {
+        const targets = await loadDiagnosticTargets(command, commandOptions, target, true);
+        const status = await buildStatusOutput(targets);
+        if (commandOptions.json) {
+            writeJson(status);
+            return;
+        }
+        printStatusOutput(status);
+    });
+    addProjectOptions(addLlmOptions(program
+        .command("doctor")
+        .argument("[target]", "docs folder or ragbox output directory")
+        .option("--all-sources", "check every configured source")
+        .option("--json", "print a stable JSON result")))
+        .action(async (target, commandOptions, command) => {
+        const doctor = await buildDoctorOutput(command, commandOptions, target);
+        if (commandOptions.json) {
+            writeJson(doctor);
+            return;
+        }
+        printDoctorOutput(doctor);
+    });
+    addProjectOptions(addLlmOptions(program
+        .command("query")
+        .argument("[target]", "docs folder or ragbox output directory")
+        .argument("[question]", "question to answer")
+        .option("--all-sources", "query every configured source and synthesize one answer")
+        .option("--json", "print a stable JSON result with selections and sources")
+        .option("--trace", "include query trace diagnostics; implies JSON output")))
+        .action(async (target, question, commandOptions, command) => {
+        await runQueryAction(target, question, commandOptions, command);
+    });
+    const traceCommand = program
+        .command("trace")
+        .description("run diagnostic tracing commands");
+    addProjectOptions(addLlmOptions(traceCommand
+        .command("query")
+        .argument("[target]", "docs folder or ragbox output directory")
+        .argument("[question]", "question to answer")
+        .option("--all-sources", "query every configured source and synthesize one answer")
+        .option("--json", "print a stable JSON result with selections and sources")))
+        .action(async (target, question, commandOptions, command) => {
+        await runQueryAction(target, question, { ...commandOptions, trace: true, json: true }, command);
+    });
+    addProjectOptions(addLlmOptions(program
+        .command("start")
+        .argument("[folder]", "folder to index, watch, and serve")
+        .option("--all-sources", "start every configured source")
+        .option("--auth-token <token>", "bearer token required for non-health endpoints")
+        .option("-c, --concurrency <number>", "PageIndex concurrency", parseConcurrency)
+        .option("--pageindex-cli <path>", "PageIndex script path")
+        .option("-o, --output-dir <folder>", "folder for ragbox index files")
+        .option("--pageindex-python <path>", "Python executable used to run PageIndex")
+        .option("--debounce-ms <ms>", "watch change debounce in milliseconds", parseDebounceMs)
+        .option("--health-file <path>", "write a watch health JSON file")
+        .option("--host <host>", "host to bind", process.env.RAGBOX_SERVE_HOST ?? "127.0.0.1")
+        .option("--jsonl", "print stable JSON Lines start, watch, and index progress events")
+        .option("--lock-file <path>", "create an exclusive lock file while start is running")
+        .option("--port <number>", "port to bind", parseServePort)
+        .option("--retry-attempts <number>", "retry failed watch index runs", parseRetryAttempts)
+        .option("--retry-delay-ms <ms>", "delay between watch retries in milliseconds", parseRetryDelayMs)
+        .option("--staging", "index into a staging directory and promote it after a clean run")
+        .option("--staging-output-dir <folder>", "staging directory used with --staging")
+        .option("--webhook <url>", "POST watch events to a webhook URL")))
+        .action(async (folder, commandOptions, command) => {
+        await runStartAction(folder, commandOptions, command);
+    });
+    addProjectOptions(addLlmOptions(program
+        .command("serve")
+        .argument("[target]", "docs folder or ragbox output directory")
+        .option("--all-sources", "serve every configured source by default")
+        .option("--auth-token <token>", "bearer token required for non-health endpoints")
+        .option("--host <host>", "host to bind", process.env.RAGBOX_SERVE_HOST ?? "127.0.0.1")
+        .option("--port <number>", "port to bind", parseServePort)))
+        .action(async (target, commandOptions, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const handle = await (0, serve_1.startServe)({
+            allSources: commandOptions.allSources,
+            apiKey: commandOptions.apiKey,
+            authToken: commandOptions.authToken,
+            baseUrl: commandOptions.baseUrl,
+            configPath: globalOptions.config,
+            host: commandOptions.host,
+            model: commandOptions.model,
+            port: commandOptions.port,
+            source: commandOptions.source,
+            target
+        });
+        console.log(`Serving ragbox at ${handle.url}`);
+        await new Promise((resolve) => {
+            let closing = false;
+            const stop = () => {
+                if (closing) {
+                    return;
+                }
+                closing = true;
+                void handle.close().finally(resolve);
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+            handle.server.once("close", () => {
+                process.off("SIGINT", stop);
+                process.off("SIGTERM", stop);
+                resolve();
+            });
+        });
+    });
+    addProjectOptions(addLlmOptions(program
+        .command("watch")
+        .argument("[folder]", "folder to watch")
+        .option("-c, --concurrency <number>", "PageIndex concurrency", parseConcurrency)
+        .option("--pageindex-cli <path>", "PageIndex script path")
+        .option("-o, --output-dir <folder>", "folder for ragbox index files")
+        .option("--pageindex-python <path>", "Python executable used to run PageIndex")
+        .option("--debounce-ms <ms>", "watch change debounce in milliseconds", parseDebounceMs)
+        .option("--health-file <path>", "write a watch health JSON file")
+        .option("--jsonl", "print stable JSON Lines watch and index progress events")
+        .option("--lock-file <path>", "create an exclusive lock file while watch is running")
+        .option("--retry-attempts <number>", "retry failed watch index runs", parseRetryAttempts)
+        .option("--retry-delay-ms <ms>", "delay between watch retries in milliseconds", parseRetryDelayMs)
+        .option("--staging", "index into a staging directory and promote it after a clean run")
+        .option("--staging-output-dir <folder>", "staging directory used with --staging")
+        .option("--webhook <url>", "POST watch events to a webhook URL")))
+        .action(async (folder, commandOptions, command) => {
+        const loaded = await loadCommandConfig(command, commandOptions);
+        const watchFolderPath = requireFolder(folder ?? loaded.rootDir, "watch");
+        const options = buildOptions(loaded.options, commandOptions, commandOptions.jsonl ? logProgressAsJsonLine : logProgress);
+        if (commandOptions.jsonl) {
+            options.watchProgress = writeJsonLine;
+        }
+        await (0, watch_1.watchFolder)(watchFolderPath, options);
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});