@bndynet/ragbox 0.1.0 → 0.1.1

package/dist/src/cli.js

@@ -4,7 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
 const promises_1 = __importDefault(require("node:fs/promises"));
+const node_http_1 = __importDefault(require("node:http"));
 const node_path_1 = __importDefault(require("node:path"));
 const commander_1 = require("commander");
 const config_file_1 = require("./config-file");
@@ -24,6 +27,12 @@ function parseConcurrency(value) {
     }
     return parsed;
 }
+function parsePageIndexRunner(value) {
+    if (value === "auto" || value === "single" || value === "batch") {
+        return value;
+    }
+    throw new Error("--pageindex-runner must be one of: auto, single, batch");
+}
 function parseNonNegativeInteger(value, optionName) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isFinite(parsed) || parsed < 0) {
@@ -40,6 +49,9 @@ function parseRetryDelayMs(value) {
 function parseDebounceMs(value) {
     return parseNonNegativeInteger(value, "--debounce-ms");
 }
+function parseStopTimeoutMs(value) {
+    return parseNonNegativeInteger(value, "--timeout-ms");
+}
 function parseServePort(value) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isFinite(parsed) || parsed < 0 || parsed > 65535) {
@@ -76,6 +88,32 @@ function logProgress(event) {
             break;
     }
 }
+function firstLine(value) {
+    return value.split(/\r?\n/, 1)[0] ?? value;
+}
+function printIndexProgress(event) {
+    switch (event.type) {
+        case "scan":
+            console.error(`[ragbox] scan complete output=${event.outputDir} total=${event.total} toIndex=${event.toIndex} unchanged=${event.unchanged} deleted=${event.deleted}`);
+            break;
+        case "index-start":
+            console.error(`[ragbox] indexing ${event.index}/${event.total} ${event.path}`);
+            break;
+        case "index-done":
+            console.error(`[ragbox] indexed ${event.index}/${event.total} ${event.path}`);
+            if (event.summary) {
+                console.error(`[ragbox] summary ${event.path}: ${event.summary}`);
+            }
+            break;
+        case "index-failed":
+            console.error(`[ragbox] failed ${event.index}/${event.total} ${event.path}: ${firstLine(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")
@@ -218,6 +256,7 @@ function buildOptions(configOptions, commandOptions, progress = logProgress) {
         cliPath: commandOptions.pageindexCli,
         model: commandOptions.model,
         outputDir: commandOptions.outputDir,
+        pageIndexRunner: commandOptions.pageindexRunner,
         pythonPath: commandOptions.pageindexPython,
         watchDebounceMs: commandOptions.debounceMs,
         watchHealthFile: commandOptions.healthFile,
@@ -245,6 +284,94 @@ function parseSourceNames(source) {
         .map((name) => name.trim())
         .filter(Boolean);
 }
+function resolveServeProbeHost(host) {
+    if (host === "0.0.0.0") {
+        return "127.0.0.1";
+    }
+    if (host === "::") {
+        return "::1";
+    }
+    return host;
+}
+function serveHealthUrl(host, port) {
+    const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    return `http://${urlHost}:${port}/health`;
+}
+function isServeHealthResult(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const health = value;
+    return health.version === 1
+        && typeof health.ok === "boolean"
+        && (health.status === "ready" || health.status === "degraded" || health.status === "error")
+        && typeof health.indexes === "object"
+        && health.indexes !== null;
+}
+async function checkServeHealth(configPath) {
+    const { config } = await (0, config_file_1.readRagboxConfig)(configPath);
+    const serveConfig = (0, config_file_1.resolveRagboxServeConfig)({ config });
+    const host = resolveServeProbeHost(serveConfig.host);
+    const port = serveConfig.port;
+    const url = serveHealthUrl(host, port);
+    return await new Promise((resolve) => {
+        const request = node_http_1.default.get(url, { timeout: 2000 }, (response) => {
+            let raw = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                raw += chunk;
+            });
+            response.on("end", () => {
+                let health;
+                let error;
+                if (raw.trim()) {
+                    try {
+                        const parsed = JSON.parse(raw);
+                        if (isServeHealthResult(parsed)) {
+                            health = parsed;
+                        }
+                        else {
+                            error = "Response was not a ragbox health payload.";
+                        }
+                    }
+                    catch (parseError) {
+                        error = parseError instanceof Error ? parseError.message : String(parseError);
+                    }
+                }
+                else {
+                    error = "Response body was empty.";
+                }
+                const statusCode = response.statusCode ?? 0;
+                resolve({
+                    version: 1,
+                    url,
+                    host,
+                    port,
+                    ok: Boolean(health?.ok) && statusCode >= 200 && statusCode < 300,
+                    reachable: true,
+                    status: health?.status,
+                    statusCode,
+                    health,
+                    error
+                });
+            });
+        });
+        request.on("timeout", () => {
+            request.destroy(new Error("Timed out after 2000ms."));
+        });
+        request.on("error", (error) => {
+            resolve({
+                version: 1,
+                url,
+                host,
+                port,
+                ok: false,
+                reachable: false,
+                error: error.message
+            });
+        });
+    });
+}
 function requireFolder(folder, commandName) {
     if (!folder) {
         throw new Error(`Missing folder. Pass a folder argument or configure a source rootDir before running ragbox ${commandName}.`);
@@ -433,7 +560,7 @@ async function loadStartTargets(command, commandOptions, folder) {
         }
     ];
 }
-async function buildStatusOutput(targets) {
+async function buildStatusOutput(targets, configPath) {
     const statusTargets = [];
     for (const target of targets) {
         const validation = await (0, sdk_1.validateIndex)(target.target);
@@ -446,13 +573,40 @@ async function buildStatusOutput(targets) {
             warnings: validation.warnings
         });
     }
+    const serve = await checkServeHealth(configPath);
     return {
         version: 1,
         command: "status",
-        ok: statusTargets.every((target) => target.ok),
-        targets: statusTargets
+        ok: statusTargets.every((target) => target.ok) && serve.ok,
+        targets: statusTargets,
+        serve
     };
 }
+function serveHealthSummary(serve) {
+    if (!serve.reachable) {
+        return `HTTP server is not reachable at ${serve.url}: ${serve.error ?? "connection failed"}`;
+    }
+    if (!serve.health) {
+        return `HTTP server responded at ${serve.url}, but health could not be parsed: ${serve.error ?? "invalid response"}`;
+    }
+    const indexes = serve.health.indexes;
+    return `HTTP server ${serve.health.status} at ${serve.url}; indexes ready=${indexes.ready}/${indexes.total}.`;
+}
+function printServeHealthOutput(serve) {
+    console.log(`${serve.ok ? "ok" : "error"} serve ${serve.url}`);
+    console.log(`  reachable=${serve.reachable}`);
+    if (serve.statusCode !== undefined) {
+        console.log(`  http=${serve.statusCode}`);
+    }
+    if (serve.health) {
+        const indexes = serve.health.indexes;
+        console.log(`  status=${serve.health.status}`);
+        console.log(`  indexes=${indexes.total} ready=${indexes.ready} failed=${indexes.failed}`);
+    }
+    if (serve.error) {
+        console.log(`  error ${serve.error}`);
+    }
+}
 function printStatusOutput(status) {
     for (const target of status.targets) {
         const label = target.source ? `${target.source} ${target.target}` : target.target;
@@ -470,6 +624,9 @@ function printStatusOutput(status) {
             console.log(`  warning ${warning.code}: ${warning.message}`);
         }
     }
+    if (status.serve) {
+        printServeHealthOutput(status.serve);
+    }
 }
 function startTargetLabel(target) {
     return target.source ? `${target.source} ${target.rootDir}` : target.rootDir;
@@ -517,6 +674,177 @@ async function closeStartHandles(watchHandles, serveHandle) {
         ...(serveHandle ? [serveHandle.close()] : [])
     ]);
 }
+const BACKGROUND_CHILD_ENV = "RAGBOX_BACKGROUND_CHILD";
+function stripBackgroundStartArgs(args) {
+    const stripped = [];
+    let afterTerminator = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (afterTerminator) {
+            stripped.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            afterTerminator = true;
+            stripped.push(arg);
+            continue;
+        }
+        if (arg === "--background" || arg.startsWith("--background=")) {
+            continue;
+        }
+        if (arg === "--pid-file" || arg === "--log-file") {
+            index += 1;
+            continue;
+        }
+        if (arg === "--no-pid-file" || arg.startsWith("--pid-file=") || arg.startsWith("--log-file=")) {
+            continue;
+        }
+        stripped.push(arg);
+    }
+    return stripped;
+}
+async function writeBackgroundPidFile(pidFile, pid) {
+    if (!pidFile) {
+        return undefined;
+    }
+    const resolvedPidFile = node_path_1.default.resolve(pidFile);
+    await promises_1.default.mkdir(node_path_1.default.dirname(resolvedPidFile), { recursive: true });
+    await promises_1.default.writeFile(resolvedPidFile, `${pid}\n`, "utf8");
+    return resolvedPidFile;
+}
+async function launchBackgroundStart(commandOptions) {
+    const cliScript = process.argv[1];
+    if (!cliScript) {
+        throw new Error("Cannot start ragbox in the background because the CLI script path is unavailable.");
+    }
+    const logFile = node_path_1.default.resolve(commandOptions.logFile ?? "ragbox.log");
+    await promises_1.default.mkdir(node_path_1.default.dirname(logFile), { recursive: true });
+    const logFd = (0, node_fs_1.openSync)(logFile, "a");
+    const childArgs = [cliScript, ...stripBackgroundStartArgs(process.argv.slice(2))];
+    const child = (0, node_child_process_1.spawn)(process.execPath, childArgs, {
+        cwd: process.cwd(),
+        detached: true,
+        env: {
+            ...process.env,
+            [BACKGROUND_CHILD_ENV]: "1"
+        },
+        stdio: ["ignore", logFd, logFd]
+    });
+    try {
+        if (!child.pid) {
+            throw new Error("Failed to start background ragbox process.");
+        }
+        const pidFile = await writeBackgroundPidFile(commandOptions.pidFile === false ? undefined : commandOptions.pidFile ?? "ragbox.pid", child.pid);
+        child.unref();
+        return {
+            pid: child.pid,
+            logFile,
+            pidFile
+        };
+    }
+    catch (error) {
+        child.kill("SIGTERM");
+        throw error;
+    }
+    finally {
+        (0, node_fs_1.closeSync)(logFd);
+    }
+}
+function printBackgroundStartResult(result, jsonl) {
+    if (jsonl) {
+        writeStartJsonLine("start-background", result);
+        return;
+    }
+    console.log(`Started ragbox in the background (pid=${result.pid})`);
+    console.log(`log=${result.logFile}`);
+    if (result.pidFile) {
+        console.log(`pidFile=${result.pidFile}`);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isNoSuchProcessError(error) {
+    return error.code === "ESRCH";
+}
+async function readStopPidFile(pidFile) {
+    let raw;
+    try {
+        raw = await promises_1.default.readFile(pidFile, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`No ragbox pid file found: ${pidFile}. Run ragbox start --background first, or pass --pid-file.`);
+        }
+        throw error;
+    }
+    const trimmed = raw.trim();
+    const pid = Number.parseInt(trimmed, 10);
+    if (!trimmed || !Number.isInteger(pid) || pid <= 0 || String(pid) !== trimmed) {
+        throw new Error(`Invalid ragbox pid file: ${pidFile}`);
+    }
+    return pid;
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (isNoSuchProcessError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const startedAt = Date.now();
+    do {
+        if (!isProcessRunning(pid)) {
+            return true;
+        }
+        await sleep(50);
+    } while (Date.now() - startedAt < timeoutMs);
+    return !isProcessRunning(pid);
+}
+async function runStopAction(commandOptions) {
+    const pidFile = node_path_1.default.resolve(commandOptions.pidFile ?? "ragbox.pid");
+    const pid = await readStopPidFile(pidFile);
+    const signal = commandOptions.force ? "SIGKILL" : "SIGTERM";
+    const timeoutMs = commandOptions.timeoutMs ?? 5000;
+    let stale = false;
+    try {
+        process.kill(pid, signal);
+    }
+    catch (error) {
+        if (!isNoSuchProcessError(error)) {
+            throw error;
+        }
+        stale = true;
+    }
+    const stopped = stale || await waitForProcessExit(pid, timeoutMs);
+    if (!stopped) {
+        throw new Error(`ragbox process ${pid} did not stop within ${timeoutMs}ms; pid file left in place: ${pidFile}`);
+    }
+    await promises_1.default.rm(pidFile, { force: true });
+    return {
+        version: 1,
+        command: "stop",
+        pid,
+        pidFile,
+        signal,
+        stopped,
+        stale,
+        removedPidFile: true
+    };
+}
+function printStopResult(result) {
+    if (result.stale) {
+        console.log(`Removed stale ragbox pid file ${result.pidFile} (pid=${result.pid})`);
+        return;
+    }
+    console.log(`Stopped ragbox (pid=${result.pid}, signal=${result.signal})`);
+}
 function isPathLikeCommand(value) {
     return node_path_1.default.isAbsolute(value) || value.startsWith(".") || value.includes("/") || value.includes("\\");
 }
@@ -576,12 +904,20 @@ async function buildDoctorOutput(command, commandOptions, target) {
         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);
+    const status = await buildStatusOutput(targets, globalOptions.config);
+    const indexStatusOk = status.targets.every((target) => target.ok);
     checks.push({
         name: "index-status",
-        ok: status.ok,
+        ok: indexStatusOk,
         message: status.targets.length > 0 ? `Checked ${status.targets.length} index target(s).` : "No index target was checked."
     });
+    if (status.serve) {
+        checks.push({
+            name: "serve-health",
+            ok: status.serve.ok,
+            message: serveHealthSummary(status.serve)
+        });
+    }
     return {
         version: 1,
         command: "doctor",
@@ -718,11 +1054,6 @@ async function runStartAction(folder, commandOptions, command) {
             });
             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)({
@@ -747,6 +1078,12 @@ async function runStartAction(folder, commandOptions, command) {
         else {
             console.log(`Serving ragbox at ${serveHandle.url}`);
         }
+        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}`);
+        }
+        await reloadServe();
         await new Promise((resolve) => {
             let closing = false;
             const stop = () => {
@@ -828,11 +1165,15 @@ async function main() {
         .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("--pageindex-runner <mode>", "PageIndex runner mode: auto, single, or batch", parsePageIndexRunner)
         .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) {
+            console.error(`[ragbox] indexing ${indexFolderPath}`);
+        }
+        const result = await (0, indexer_1.indexFolder)(indexFolderPath, buildOptions(loaded.options, commandOptions, commandOptions.json ? logProgress : printIndexProgress));
         if (commandOptions.json) {
             writeJson(indexJsonOutput(result));
             return;
@@ -873,8 +1214,9 @@ async function main() {
         .option("--all-sources", "check every configured source")
         .option("--json", "print a stable JSON result"))
         .action(async (target, commandOptions, command) => {
+        const globalOptions = getGlobalOptions(command);
         const targets = await loadDiagnosticTargets(command, commandOptions, target, true);
-        const status = await buildStatusOutput(targets);
+        const status = await buildStatusOutput(targets, globalOptions.config);
         if (commandOptions.json) {
             writeJson(status);
             return;
@@ -921,15 +1263,20 @@ async function main() {
         .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("--background", "run start as a detached background process")
         .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("--pageindex-runner <mode>", "PageIndex runner mode: auto, single, or batch", parsePageIndexRunner)
         .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("--host <host>", "host to bind")
         .option("--jsonl", "print stable JSON Lines start, watch, and index progress events")
+        .option("--log-file <path>", "background stdout/stderr log file; defaults to ./ragbox.log")
         .option("--lock-file <path>", "create an exclusive lock file while start is running")
+        .option("--pid-file <path>", "background process id file; defaults to ./ragbox.pid")
+        .option("--no-pid-file", "do not write a background process id file")
         .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)
@@ -937,14 +1284,34 @@ async function main() {
         .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) => {
+        if (commandOptions.background && process.env[BACKGROUND_CHILD_ENV] !== "1") {
+            const result = await launchBackgroundStart(commandOptions);
+            printBackgroundStartResult(result, commandOptions.jsonl);
+            return;
+        }
         await runStartAction(folder, commandOptions, command);
     });
+    program
+        .command("stop")
+        .description("stop a background ragbox start process")
+        .option("--pid-file <path>", "pid file written by ragbox start --background", "ragbox.pid")
+        .option("--force", "send SIGKILL instead of SIGTERM")
+        .option("--timeout-ms <ms>", "time to wait for the process to exit", parseStopTimeoutMs)
+        .option("--json", "print a stable JSON result")
+        .action(async (commandOptions) => {
+        const result = await runStopAction(commandOptions);
+        if (commandOptions.json) {
+            writeJson(result);
+            return;
+        }
+        printStopResult(result);
+    });
     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("--host <host>", "host to bind")
         .option("--port <number>", "port to bind", parseServePort)))
         .action(async (target, commandOptions, command) => {
         const globalOptions = getGlobalOptions(command);
@@ -986,6 +1353,7 @@ async function main() {
         .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("--pageindex-runner <mode>", "PageIndex runner mode: auto, single, or batch", parsePageIndexRunner)
         .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")

package/dist/src/config-file.d.ts

@@ -1,11 +1,14 @@
-import { PageIndexOptions } from "./folder-index/types";
+import { PageIndexOptions, PageIndexRunner } from "./folder-index/types";
 export declare const RAGBOX_CONFIG_FILE = "ragbox.config.json";
+export declare const DEFAULT_SERVE_HOST = "127.0.0.1";
+export declare const DEFAULT_SERVE_PORT = 8787;
 export type RagboxPageIndexConfig = {
     cli?: string;
     concurrency?: number;
     extraArgs?: string[];
     outputArg?: string;
     python?: string;
+    runner?: PageIndexRunner;
 };
 export type RagboxLlmConfig = {
     apiKey?: string;
@@ -17,6 +20,11 @@ export type RagboxIndexConfig = {
     include?: string[];
     outputDir?: string;
 };
+export type RagboxServeConfig = {
+    authToken?: string;
+    host?: string;
+    port?: number;
+};
 export type RagboxConfigSource = RagboxIndexConfig & {
     index?: RagboxIndexConfig;
     llm?: RagboxLlmConfig;
@@ -29,6 +37,7 @@ export type RagboxConfig = {
     index?: RagboxIndexConfig;
     llm?: RagboxLlmConfig;
     pageIndex?: RagboxPageIndexConfig;
+    serve?: RagboxServeConfig;
     sources?: Record<string, RagboxConfigSource>;
 };
 export type ResolvedRagboxConfig = {
@@ -57,6 +66,13 @@ export type WritePageIndexSetupConfigOptions = {
     cwd?: string;
     pythonPath?: string;
 };
+export type ResolveRagboxServeConfigOptions = RagboxServeConfig & {
+    config?: RagboxConfig;
+    env?: NodeJS.ProcessEnv;
+};
+export type ResolvedRagboxServeConfig = Required<Pick<RagboxServeConfig, "host" | "port">> & Pick<RagboxServeConfig, "authToken">;
+export declare function parseRagboxServePort(value: unknown, source: string): number | undefined;
+export declare function resolveRagboxServeConfig(options?: ResolveRagboxServeConfigOptions): ResolvedRagboxServeConfig;
 export declare function createDefaultRagboxConfig(options?: Pick<WriteDefaultRagboxConfigOptions, "docsDir" | "outputDir">): RagboxConfig;
 export declare function listRagboxConfigSourceNames(config: RagboxConfig | undefined): string[];
 export declare function writeDefaultRagboxConfig(options?: WriteDefaultRagboxConfigOptions): Promise<string>;

package/dist/src/config-file.js

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RAGBOX_CONFIG_FILE = void 0;
+exports.DEFAULT_SERVE_PORT = exports.DEFAULT_SERVE_HOST = exports.RAGBOX_CONFIG_FILE = void 0;
+exports.parseRagboxServePort = parseRagboxServePort;
+exports.resolveRagboxServeConfig = resolveRagboxServeConfig;
 exports.createDefaultRagboxConfig = createDefaultRagboxConfig;
 exports.listRagboxConfigSourceNames = listRagboxConfigSourceNames;
 exports.writeDefaultRagboxConfig = writeDefaultRagboxConfig;
@@ -13,8 +15,14 @@ exports.resolveRagboxConfig = resolveRagboxConfig;
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 exports.RAGBOX_CONFIG_FILE = "ragbox.config.json";
+exports.DEFAULT_SERVE_HOST = "127.0.0.1";
+exports.DEFAULT_SERVE_PORT = 8787;
 const DEFAULT_INCLUDE = ["**/*.md", "**/*.mdx"];
 const DEFAULT_EXCLUDE = ["node_modules/**", ".git/**", ".pageindex/**", "dist/**", "build/**"];
+const DEFAULT_API_KEY_PLACEHOLDER = "YOUR_OPENAI_API_KEY";
+const DEFAULT_SERVE_TOKEN_PLACEHOLDER = "YOUR_RAGBOX_SERVE_TOKEN";
+const API_KEY_PLACEHOLDERS = new Set([DEFAULT_API_KEY_PLACEHOLDER, "sk-..."]);
+const SERVE_TOKEN_PLACEHOLDERS = new Set([DEFAULT_SERVE_TOKEN_PLACEHOLDER, "<token>"]);
 async function pathExists(filePath) {
     try {
         await promises_1.default.access(filePath);
@@ -94,12 +102,14 @@ function pageIndexConfigToOptions(configDir, config) {
         concurrency: config.concurrency,
         extraArgs: config.extraArgs,
         outputArg: config.outputArg,
+        pageIndexRunner: config.runner,
         pythonPath: resolveConfigCommandPath(configDir, config.python)
     };
 }
 function llmConfigToOptions(config) {
+    const apiKey = config.apiKey?.trim();
     return {
-        apiKey: config.apiKey,
+        apiKey: apiKey && !API_KEY_PLACEHOLDERS.has(apiKey) ? config.apiKey : undefined,
         baseUrl: config.baseUrl,
         model: config.model
     };
@@ -111,17 +121,52 @@ function indexConfigToOptions(configDir, config) {
         outputDir: resolveConfigRelativePath(configDir, config.outputDir)
     };
 }
+function parseRagboxServePort(value, source) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number.parseInt(value, 10) : NaN;
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+        throw new Error(`Invalid ${source}: ${String(value)}`);
+    }
+    return parsed;
+}
+function resolveRagboxServeToken(value) {
+    const authToken = value?.trim();
+    return authToken && !SERVE_TOKEN_PLACEHOLDERS.has(authToken) ? authToken : undefined;
+}
+function resolveRagboxServeConfig(options = {}) {
+    const env = options.env ?? process.env;
+    return {
+        authToken: resolveRagboxServeToken(options.authToken)
+            ?? resolveRagboxServeToken(options.config?.serve?.authToken)
+            ?? resolveRagboxServeToken(env.RAGBOX_SERVE_TOKEN),
+        host: options.host ?? options.config?.serve?.host ?? env.RAGBOX_SERVE_HOST ?? exports.DEFAULT_SERVE_HOST,
+        port: options.port
+            ?? parseRagboxServePort(options.config?.serve?.port, "ragbox config serve.port")
+            ?? parseRagboxServePort(env.RAGBOX_SERVE_PORT, "RAGBOX_SERVE_PORT")
+            ?? exports.DEFAULT_SERVE_PORT
+    };
+}
 function createDefaultRagboxConfig(options = {}) {
     const docsDir = options.docsDir ?? "./docs";
     const outputDir = options.outputDir ?? "./.ragbox-index";
     return {
         version: 1,
         pageIndex: {
-            cli: "/path/to/PageIndex/run_pageindex.py"
+            cli: "/path/to/PageIndex/run_pageindex.py",
+            concurrency: 1,
+            runner: "auto"
         },
         llm: {
             baseUrl: "https://api.openai.com/v1",
-            model: "gpt-4o-mini"
+            model: "gpt-4o-mini",
+            apiKey: DEFAULT_API_KEY_PLACEHOLDER
+        },
+        serve: {
+            authToken: DEFAULT_SERVE_TOKEN_PLACEHOLDER,
+            host: exports.DEFAULT_SERVE_HOST,
+            port: exports.DEFAULT_SERVE_PORT
         },
         docs: {
             rootDir: docsDir,