@bndynet/ragbox 0.1.0

package/dist/src/sdk.js

@@ -0,0 +1,352 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIndex = createIndex;
+exports.queryIndex = queryIndex;
+exports.watchIndex = watchIndex;
+exports.inspectIndex = inspectIndex;
+exports.validateIndex = validateIndex;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_file_1 = require("./config-file");
+const indexer_1 = require("./folder-index/indexer");
+const manifest_1 = require("./folder-index/manifest");
+const query_1 = require("./folder-index/query");
+const watch_1 = require("./folder-index/watch");
+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;
+}
+async function toPageIndexOptions(options = {}) {
+    const createOptions = options;
+    const queryOptions = options;
+    const watchOptions = options;
+    const resolved = await (0, config_file_1.resolveRagboxConfig)({
+        configPath: options.configPath,
+        source: options.source
+    });
+    return mergeDefined(resolved.pageIndexOptions, {
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        cliPath: createOptions.pageIndexCli,
+        concurrency: createOptions.concurrency,
+        env: options.env,
+        exclude: createOptions.exclude,
+        extraArgs: createOptions.pageIndexExtraArgs,
+        include: createOptions.include,
+        llmClient: options.llmClient,
+        model: options.model,
+        outputArg: createOptions.pageIndexOutputArg,
+        outputDir: options.outputDir,
+        progress: createOptions.onProgress,
+        pythonPath: createOptions.pageIndexPython,
+        trace: queryOptions.trace,
+        watchDebounceMs: watchOptions.debounceMs,
+        watchHealthFile: watchOptions.healthFile,
+        watchLockFile: watchOptions.lockFile,
+        watchProgress: watchOptions.onEvent,
+        watchRetryAttempts: watchOptions.retryAttempts,
+        watchRetryDelayMs: watchOptions.retryDelayMs,
+        watchStaging: watchOptions.staging,
+        watchStagingOutputDir: watchOptions.stagingOutputDir,
+        watchWebhookUrl: watchOptions.webhookUrl
+    });
+}
+function toIndexCounts(result) {
+    if ("documents" in result) {
+        const ready = result.documents.filter((record) => record.status === "ready").length;
+        const failed = result.documents.filter((record) => record.status === "failed").length;
+        return {
+            total: result.documents.length,
+            ready,
+            failed,
+            added: 0,
+            modified: 0,
+            retryFailed: 0,
+            unchanged: 0,
+            deleted: 0
+        };
+    }
+    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 toCreateIndexResult(result) {
+    return {
+        version: 1,
+        rootDir: result.manifest.rootDir,
+        outputDir: result.outputDir,
+        manifestPath: result.manifestPath,
+        rootTreePath: result.rootTreePath,
+        generatedAt: result.manifest.generatedAt,
+        counts: toIndexCounts(result),
+        manifest: result.manifest,
+        rootTree: result.rootTree
+    };
+}
+async function readJson(filePath, code, label) {
+    try {
+        return {
+            ok: true,
+            value: JSON.parse(await promises_1.default.readFile(filePath, "utf8"))
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            issue: {
+                code,
+                message: `${label} is not readable JSON: ${message}`,
+                path: filePath
+            }
+        };
+    }
+}
+async function pathExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveIndexFiles(target) {
+    const resolvedTarget = node_path_1.default.resolve(target);
+    const candidates = [resolvedTarget, node_path_1.default.join(resolvedTarget, manifest_1.PAGEINDEX_DIR)];
+    for (const outputDir of candidates) {
+        const manifestPath = node_path_1.default.join(outputDir, manifest_1.MANIFEST_FILE);
+        const rootTreePath = node_path_1.default.join(outputDir, manifest_1.ROOT_TREE_FILE);
+        if ((await pathExists(manifestPath)) || (await pathExists(rootTreePath))) {
+            return {
+                target: resolvedTarget,
+                rootDir: outputDir === candidates[1] ? resolvedTarget : outputDir,
+                outputDir,
+                manifestPath,
+                rootTreePath
+            };
+        }
+    }
+    return {
+        target: resolvedTarget,
+        rootDir: resolvedTarget,
+        outputDir: resolvedTarget,
+        manifestPath: node_path_1.default.join(resolvedTarget, manifest_1.MANIFEST_FILE),
+        rootTreePath: node_path_1.default.join(resolvedTarget, manifest_1.ROOT_TREE_FILE)
+    };
+}
+function documentSummaries(manifest) {
+    return manifest.documents.map((record) => ({
+        docId: record.docId,
+        path: record.path,
+        title: record.title,
+        status: record.status,
+        indexPath: record.indexPath,
+        summary: record.summary,
+        size: record.size,
+        mtimeMs: record.mtimeMs
+    }));
+}
+function collectDocumentNodes(rootTree) {
+    const nodes = [];
+    function visit(node) {
+        if (node.type === "document") {
+            nodes.push(node);
+        }
+        for (const child of node.children ?? []) {
+            visit(child);
+        }
+    }
+    visit(rootTree);
+    return nodes;
+}
+async function createIndex(folder, options = {}) {
+    return toCreateIndexResult(await (0, indexer_1.indexFolder)(folder, await toPageIndexOptions(options)));
+}
+async function queryIndex(target, question, options = {}) {
+    return await (0, query_1.queryFolder)(target, question, await toPageIndexOptions(options));
+}
+async function watchIndex(folder, options = {}) {
+    const handle = await (0, watch_1.startWatchFolder)(folder, await toPageIndexOptions(options));
+    return {
+        rootDir: handle.rootDir,
+        outputDir: handle.outputDir,
+        ready: handle.ready.then((ready) => {
+            if (!ready.ok) {
+                return ready;
+            }
+            return {
+                ok: true,
+                result: toCreateIndexResult(ready.result)
+            };
+        }),
+        closed: handle.closed,
+        close: handle.close
+    };
+}
+async function inspectIndex(target) {
+    const location = await (0, query_1.resolveQueryIndexLocation)(target);
+    const manifest = JSON.parse(await promises_1.default.readFile(location.manifestPath, "utf8"));
+    await promises_1.default.access(location.rootTreePath);
+    return {
+        version: 1,
+        target: node_path_1.default.resolve(target),
+        rootDir: location.rootDir,
+        outputDir: location.outputDir ?? node_path_1.default.join(location.rootDir, manifest_1.PAGEINDEX_DIR),
+        manifestPath: location.manifestPath,
+        rootTreePath: location.rootTreePath,
+        generatedAt: manifest.generatedAt,
+        counts: toIndexCounts(manifest),
+        documents: documentSummaries(manifest)
+    };
+}
+async function validateIndex(target) {
+    const location = await resolveIndexFiles(target);
+    const errors = [];
+    const warnings = [];
+    let manifest;
+    let rootTree;
+    if (!(await pathExists(location.manifestPath))) {
+        errors.push({
+            code: "missing_manifest",
+            message: `Missing ${manifest_1.MANIFEST_FILE}`,
+            path: location.manifestPath
+        });
+    }
+    else {
+        const result = await readJson(location.manifestPath, "invalid_manifest_json", "manifest");
+        if (result.ok) {
+            manifest = result.value;
+            if (manifest.version !== 1) {
+                errors.push({
+                    code: "invalid_manifest_version",
+                    message: `Unsupported manifest version: ${String(manifest.version)}`,
+                    path: location.manifestPath
+                });
+            }
+            if (!Array.isArray(manifest.documents)) {
+                errors.push({
+                    code: "invalid_manifest_documents",
+                    message: "Manifest documents must be an array",
+                    path: location.manifestPath
+                });
+            }
+        }
+        else {
+            errors.push(result.issue);
+        }
+    }
+    if (!(await pathExists(location.rootTreePath))) {
+        errors.push({
+            code: "missing_root_tree",
+            message: `Missing ${manifest_1.ROOT_TREE_FILE}`,
+            path: location.rootTreePath
+        });
+    }
+    else {
+        const result = await readJson(location.rootTreePath, "invalid_root_tree_json", "root tree");
+        if (result.ok) {
+            rootTree = result.value;
+            if (rootTree.node_id !== "root" || rootTree.type !== "root") {
+                errors.push({
+                    code: "invalid_root_tree",
+                    message: "Root tree must have node_id=root and type=root",
+                    path: location.rootTreePath
+                });
+            }
+        }
+        else {
+            errors.push(result.issue);
+        }
+    }
+    if (manifest) {
+        const rootDir = manifest.rootDir ? node_path_1.default.resolve(manifest.rootDir) : location.rootDir;
+        for (const record of manifest.documents ?? []) {
+            if (record.status !== "ready") {
+                continue;
+            }
+            const indexPath = (0, manifest_1.resolveDocumentIndexPath)(rootDir, record.indexPath, location.outputDir);
+            if (!(await pathExists(indexPath))) {
+                errors.push({
+                    code: "missing_document_index",
+                    message: `Missing PageIndex JSON for ready document: ${record.path}`,
+                    path: indexPath,
+                    docId: record.docId
+                });
+            }
+        }
+    }
+    if (manifest && rootTree) {
+        const manifestByDocId = new Map(manifest.documents.map((record) => [record.docId, record]));
+        const rootTreeDocumentNodes = collectDocumentNodes(rootTree);
+        const rootTreeDocumentIds = new Set(rootTreeDocumentNodes.map((node) => node.node_id));
+        for (const node of rootTreeDocumentNodes) {
+            const record = manifestByDocId.get(node.node_id);
+            if (!record) {
+                errors.push({
+                    code: "root_tree_unknown_document",
+                    message: `Root tree references a document missing from manifest: ${node.node_id}`,
+                    path: node.path,
+                    docId: node.node_id
+                });
+                continue;
+            }
+            if (node.index_path && node.index_path !== record.indexPath) {
+                errors.push({
+                    code: "root_tree_index_path_mismatch",
+                    message: `Root tree index path differs from manifest for ${record.path}`,
+                    path: node.path,
+                    docId: record.docId
+                });
+            }
+        }
+        for (const record of manifest.documents) {
+            if (record.status === "ready" && !rootTreeDocumentIds.has(record.docId)) {
+                errors.push({
+                    code: "manifest_document_missing_from_root_tree",
+                    message: `Ready document is missing from root tree: ${record.path}`,
+                    path: record.path,
+                    docId: record.docId
+                });
+            }
+        }
+    }
+    const inspect = errors.length === 0 && manifest
+        ? {
+            version: 1,
+            target: location.target,
+            rootDir: manifest.rootDir ? node_path_1.default.resolve(manifest.rootDir) : location.rootDir,
+            outputDir: location.outputDir,
+            manifestPath: location.manifestPath,
+            rootTreePath: location.rootTreePath,
+            generatedAt: manifest.generatedAt,
+            counts: toIndexCounts(manifest),
+            documents: documentSummaries(manifest)
+        }
+        : undefined;
+    return {
+        version: 1,
+        target: location.target,
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        inspect
+    };
+}

package/dist/src/serve.d.ts

@@ -0,0 +1,64 @@
+import http from "node:http";
+import { LlmClient } from "./folder-index/types";
+import { InspectIndexResult, ValidateIndexResult } from "./sdk";
+export type ServeOptions = {
+    allSources?: boolean;
+    apiKey?: string;
+    authToken?: string;
+    baseUrl?: string;
+    configPath?: string;
+    env?: NodeJS.ProcessEnv;
+    host?: string;
+    llmClient?: LlmClient;
+    model?: string;
+    port?: number;
+    source?: string | string[];
+    target?: string;
+};
+export type ServeHandle = {
+    url: string;
+    host: string;
+    port: number;
+    server: http.Server;
+    reload: () => Promise<ServeIndexesResult>;
+    close: () => Promise<void>;
+};
+export type ServeIndexSummary = {
+    source?: string;
+    target: string;
+    ok: boolean;
+    generatedAt?: string;
+    counts?: InspectIndexResult["counts"];
+    errors: ValidateIndexResult["errors"];
+    warnings: ValidateIndexResult["warnings"];
+};
+export type ServeIndexesResult = {
+    version: 1;
+    indexes: ServeIndexSummary[];
+};
+export type ServeHealthResult = {
+    version: 1;
+    ok: boolean;
+    status: "ready" | "degraded" | "error";
+    uptimeMs: number;
+    lastReloadAt: string;
+    indexes: {
+        total: number;
+        ready: number;
+        failed: number;
+    };
+};
+export type ServeRootResult = {
+    version: 1;
+    name: "ragbox";
+    status: ServeHealthResult["status"];
+    ok: boolean;
+    health: ServeHealthResult;
+    endpoints: Array<{
+        method: "GET" | "POST";
+        path: "/" | "/health" | "/indexes" | "/query" | "/reload";
+        authRequired: boolean;
+        description: string;
+    }>;
+};
+export declare function startServe(options?: ServeOptions): Promise<ServeHandle>;