@vibe-agent-toolkit/cli 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/commands/rag/query-schema.d.ts

@@ -0,0 +1,363 @@
+/**
+ * The document `vat rag query` publishes, apart from the command (see
+ * `index-schema.ts` for why a sibling, and why no runtime import of the RAG
+ * packages).
+ *
+ * `examined` counts the chunks in the index searched, so a query that matches
+ * nothing over a populated index is `ok` with `chunks: []`. An index with no
+ * data — no chunk table, or a table of zero chunks — refuses before searching
+ * (`INPUT_UNREADABLE`, exit 2), so the zero-examined remedy below is the
+ * writer's backstop, not an outcome a run reaches.
+ */
+import { type Report } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import type { ExaminedDeclaration } from '../../utils/run-integrity.js';
+/** What `examined` counts for `vat rag query`, and the remedy when it is zero. */
+export declare const RAG_QUERY_EXAMINED: ExaminedDeclaration;
+declare const RagQueryDataSchema: z.ZodObject<{
+    /** The directory every `filePath` is relative to: the only absolute path. */
+    root: z.ZodString;
+    query: z.ZodString;
+    /** Mirrors `RAGResult.stats` from `@vibe-agent-toolkit/rag`. */
+    stats: z.ZodObject<{
+        totalMatches: z.ZodNumber;
+        searchDurationMs: z.ZodNumber;
+        embedding: z.ZodOptional<z.ZodObject<{
+            model: z.ZodString;
+            tokensUsed: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            model: string;
+            tokensUsed?: number | undefined;
+        }, {
+            model: string;
+            tokensUsed?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    }, {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    }>;
+    chunks: z.ZodArray<z.ZodObject<{
+        chunkId: z.ZodString;
+        resourceId: z.ZodString;
+        /** The chunk's source file, relative to `root`. */
+        filePath: z.ZodString;
+        headingPath: z.ZodOptional<z.ZodString>;
+        headingLevel: z.ZodOptional<z.ZodNumber>;
+        startLine: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        contentHash: z.ZodString;
+        tokenCount: z.ZodNumber;
+        embeddingModel: z.ZodString;
+        /** ISO 8601. */
+        embeddedAt: z.ZodString;
+        previousChunkId: z.ZodOptional<z.ZodString>;
+        nextChunkId: z.ZodOptional<z.ZodString>;
+        /** The full chunk text, never truncated; last so a long result stays scannable. */
+        content: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }, {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    query: string;
+    stats: {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    };
+    chunks: {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }[];
+}, {
+    root: string;
+    query: string;
+    stats: {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    };
+    chunks: {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }[];
+}>;
+export type RagQueryData = z.infer<typeof RagQueryDataSchema>;
+/** The document this command publishes. */
+export declare const RAG_QUERY_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** The directory every `filePath` is relative to: the only absolute path. */
+    root: z.ZodString;
+    query: z.ZodString;
+    /** Mirrors `RAGResult.stats` from `@vibe-agent-toolkit/rag`. */
+    stats: z.ZodObject<{
+        totalMatches: z.ZodNumber;
+        searchDurationMs: z.ZodNumber;
+        embedding: z.ZodOptional<z.ZodObject<{
+            model: z.ZodString;
+            tokensUsed: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            model: string;
+            tokensUsed?: number | undefined;
+        }, {
+            model: string;
+            tokensUsed?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    }, {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    }>;
+    chunks: z.ZodArray<z.ZodObject<{
+        chunkId: z.ZodString;
+        resourceId: z.ZodString;
+        /** The chunk's source file, relative to `root`. */
+        filePath: z.ZodString;
+        headingPath: z.ZodOptional<z.ZodString>;
+        headingLevel: z.ZodOptional<z.ZodNumber>;
+        startLine: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        contentHash: z.ZodString;
+        tokenCount: z.ZodNumber;
+        embeddingModel: z.ZodString;
+        /** ISO 8601. */
+        embeddedAt: z.ZodString;
+        previousChunkId: z.ZodOptional<z.ZodString>;
+        nextChunkId: z.ZodOptional<z.ZodString>;
+        /** The full chunk text, never truncated; last so a long result stays scannable. */
+        content: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }, {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    query: string;
+    stats: {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    };
+    chunks: {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }[];
+}, {
+    root: string;
+    query: string;
+    stats: {
+        totalMatches: number;
+        searchDurationMs: number;
+        embedding?: {
+            model: string;
+            tokensUsed?: number | undefined;
+        } | undefined;
+    };
+    chunks: {
+        content: string;
+        embeddingModel: string;
+        chunkId: string;
+        resourceId: string;
+        filePath: string;
+        contentHash: string;
+        tokenCount: number;
+        embeddedAt: string;
+        type?: string | undefined;
+        headingPath?: string | undefined;
+        headingLevel?: number | undefined;
+        startLine?: number | undefined;
+        endLine?: number | undefined;
+        title?: string | undefined;
+        tags?: string[] | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+    }[];
+}>, z.ZodObject<Omit<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["error", "warning", "info", "ignore"]>;
+    message: z.ZodString;
+    location: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    line: z.ZodOptional<z.ZodNumber>;
+    field: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, "severity"> & {
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    column: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}>>;
+export type RagQueryReport = Report<RagQueryData>;
+export {};
+//# sourceMappingURL=query-schema.d.ts.map

package/dist/commands/rag/query-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/rag/query-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,EAAE,mBAGhC,CAAC;AA0BF,QAAA,MAAM,kBAAkB;IACtB,6EAA6E;;;IAG7E,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAxBhE,mDAAmD;;;;;;;;;;;;QAYnD,gBAAgB;;;;QAIhB,mFAAmF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkB1E,CAAC;AAEZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB;IAlBlC,6EAA6E;;;IAG7E,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAxBhE,mDAAmD;;;;;;;;;;;;QAYnD,gBAAgB;;;;QAIhB,mFAAmF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuBC,CAAC;AAEvF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC"}

package/dist/commands/rag/query-schema.js

@@ -0,0 +1,59 @@
+/**
+ * The document `vat rag query` publishes, apart from the command (see
+ * `index-schema.ts` for why a sibling, and why no runtime import of the RAG
+ * packages).
+ *
+ * `examined` counts the chunks in the index searched, so a query that matches
+ * nothing over a populated index is `ok` with `chunks: []`. An index with no
+ * data — no chunk table, or a table of zero chunks — refuses before searching
+ * (`INPUT_UNREADABLE`, exit 2), so the zero-examined remedy below is the
+ * writer's backstop, not an outcome a run reaches.
+ */
+import { FindingSchema, reportSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+/** What `examined` counts for `vat rag query`, and the remedy when it is zero. */
+export const RAG_QUERY_EXAMINED = {
+    unit: 'chunks in the index',
+    whenZero: 'The index holds no chunk to search: run vat rag index first, and check its findings for documents that failed.',
+};
+/** One matched chunk. Optional fields are omitted when the chunk has none. */
+const RagQueryChunkSchema = z.object({
+    chunkId: z.string(),
+    resourceId: z.string(),
+    /** The chunk's source file, relative to `root`. */
+    filePath: z.string(),
+    headingPath: z.string().optional(),
+    headingLevel: z.number().int().optional(),
+    startLine: z.number().int().optional(),
+    endLine: z.number().int().optional(),
+    title: z.string().optional(),
+    type: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    contentHash: z.string(),
+    tokenCount: z.number().int().nonnegative(),
+    embeddingModel: z.string(),
+    /** ISO 8601. */
+    embeddedAt: z.string(),
+    previousChunkId: z.string().optional(),
+    nextChunkId: z.string().optional(),
+    /** The full chunk text, never truncated; last so a long result stays scannable. */
+    content: z.string(),
+}).strict();
+const RagQueryDataSchema = z.object({
+    /** The directory every `filePath` is relative to: the only absolute path. */
+    root: z.string(),
+    query: z.string(),
+    /** Mirrors `RAGResult.stats` from `@vibe-agent-toolkit/rag`. */
+    stats: z.object({
+        totalMatches: z.number().int().nonnegative(),
+        searchDurationMs: z.number().nonnegative(),
+        embedding: z.object({
+            model: z.string(),
+            tokensUsed: z.number().optional(),
+        }).strict().optional(),
+    }).strict(),
+    chunks: z.array(RagQueryChunkSchema),
+}).strict();
+/** The document this command publishes. */
+export const RAG_QUERY_REPORT_SCHEMA = reportSchema(RagQueryDataSchema, FindingSchema);
+//# sourceMappingURL=query-schema.js.map

package/dist/commands/rag/query-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-schema.js","sourceRoot":"","sources":["../../../src/commands/rag/query-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAwB;IACrD,IAAI,EAAE,qBAAqB;IAC3B,QAAQ,EAAE,gHAAgH;CAC3H,CAAC;AAEF,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,mDAAmD;IACnD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACzC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,gBAAgB;IAChB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,mFAAmF;IACnF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,gEAAgE;IAChE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC5C,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;QAC1C,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC;YAClB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;YACjB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAClC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACvB,CAAC,CAAC,MAAM,EAAE;IACX,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CACrC,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,YAAY,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC"}

package/dist/commands/rag/stats-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stats-command.d.ts","sourceRoot":"","sources":["../../../src/commands/rag/stats-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BvE"}
+{"version":3,"file":"stats-command.d.ts","sourceRoot":"","sources":["../../../src/commands/rag/stats-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBvE"}

package/dist/commands/rag/stats-command.js

@@ -1,26 +1,27 @@
 /**
  * RAG stats command - show database statistics
  */
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { writeYamlOutput } from '../../utils/output.js';
-import { executeRagOperation, formatDuration } from './command-helpers.js';
+import { buildReport } from '@vibe-agent-toolkit/schema';
+import { endWithReport } from '../../utils/document-writer.js';
+import { executeRagOperation, RAG_GATE } from './command-helpers.js';
+/** One database is opened and reported on. */
+const DATABASES_OPENED = 1;
 export async function statsCommand(options) {
     const startTime = Date.now();
-    const stats = await executeRagOperation(options, async (ragProvider) => {
-        // Get stats
-        return await ragProvider.getStats();
-    }, 'Stats');
-    const duration = Date.now() - startTime;
-    // Output stats as YAML
-    writeYamlOutput({
-        status: 'success',
-        totalChunks: stats.totalChunks,
-        totalResources: stats.totalResources,
-        dbSizeBytes: stats.dbSizeBytes,
-        embeddingModel: stats.embeddingModel,
-        lastIndexed: stats.lastIndexed.toISOString(),
-        duration: formatDuration(duration),
+    const stats = await executeRagOperation('rag stats', options, (ragProvider) => ragProvider.getStats());
+    const report = buildReport({
+        examined: DATABASES_OPENED,
+        findings: [],
+        data: {
+            totalChunks: stats.totalChunks,
+            totalResources: stats.totalResources,
+            dbSizeBytes: stats.dbSizeBytes,
+            embeddingModel: stats.embeddingModel,
+            lastIndexed: stats.lastIndexed.toISOString(),
+        },
+        gate: RAG_GATE,
+        durationMs: Date.now() - startTime,
     });
-    process.exit(ExitCode.OK);
+    endWithReport('rag stats', report, 'yaml');
 }
 //# sourceMappingURL=stats-command.js.map

package/dist/commands/rag/stats-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"stats-command.js","sourceRoot":"","sources":["../../../src/commands/rag/stats-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAO3E,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAqB;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,MAAM,KAAK,GAAG,MAAM,mBAAmB,CACrC,OAAO,EACP,KAAK,EAAE,WAAW,EAAE,EAAE;QACpB,YAAY;QACZ,OAAO,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;IACtC,CAAC,EACD,OAAO,CACR,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAExC,uBAAuB;IACvB,eAAe,CAAC;QACd,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE;QAC5C,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC;KACnC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"stats-command.js","sourceRoot":"","sources":["../../../src/commands/rag/stats-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAG/D,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAOrE,8CAA8C;AAC9C,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAqB;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEvG,MAAM,MAAM,GAAmB,WAAW,CAAC;QACzC,QAAQ,EAAE,gBAAgB;QAC1B,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE;YACJ,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE;SAC7C;QACD,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;KACnC,CAAC,CAAC;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/commands/resources/check-progress.d.ts

@@ -38,36 +38,46 @@
  * exactly and automatically by the schema the reader compiles with.
  */
 import { z } from 'zod';
+import type { SupervisedChild } from './check-supervisor.js';
 declare const ProgressEntrySchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"started">;
+}, "strict", z.ZodTypeAny, {
+    kind: "started";
+}, {
+    kind: "started";
+}>, z.ZodObject<{
     kind: z.ZodLiteral<"population">;
-    population: z.ZodUnion<[z.ZodLiteral<"derived">, z.ZodLiteral<"store">]>;
+    population: z.ZodEnum<["store" | "derived", ...("store" | "derived")[]]>;
+    lensPopulation: z.ZodEnum<["none", "store" | "derived", ...("store" | "derived")[]]>;
     populationMs: z.ZodNumber;
     lensMs: z.ZodNumber;
     lensesEvaluated: z.ZodArray<z.ZodString, "many">;
     membersEnumerated: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
     kind: "population";
-    population: "derived" | "store";
+    population: "store" | "derived";
+    lensesEvaluated: string[];
+    lensPopulation: "store" | "none" | "derived";
     populationMs: number;
     lensMs: number;
-    lensesEvaluated: string[];
     membersEnumerated: number;
 }, {
     kind: "population";
-    population: "derived" | "store";
+    population: "store" | "derived";
+    lensesEvaluated: string[];
+    lensPopulation: "store" | "none" | "derived";
     populationMs: number;
     lensMs: number;
-    lensesEvaluated: string[];
     membersEnumerated: number;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"start">;
     name: z.ZodString;
 }, "strict", z.ZodTypeAny, {
-    name: string;
     kind: "start";
-}, {
     name: string;
+}, {
     kind: "start";
+    name: string;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"check">;
     name: z.ZodString;
@@ -76,15 +86,15 @@ declare const ProgressEntrySchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<
     broken: z.ZodOptional<z.ZodLiteral<true>>;
     builtin: z.ZodOptional<z.ZodLiteral<true>>;
 }, "strict", z.ZodTypeAny, {
-    name: string;
     kind: "check";
+    name: string;
     durationMs: number;
     rows?: number | undefined;
     broken?: true | undefined;
     builtin?: true | undefined;
 }, {
-    name: string;
     kind: "check";
+    name: string;
     durationMs: number;
     rows?: number | undefined;
     broken?: true | undefined;
@@ -110,6 +120,8 @@ export type ProgressEntry = z.infer<typeof ProgressEntrySchema>;
  * forty rules.
  */
 export type UnitInFlight = {
+    readonly kind: 'startup';
+} | {
     readonly kind: 'population';
 } | {
     readonly kind: 'check';
@@ -131,8 +143,13 @@ export declare function parseProgressLog(text: string): ProgressEntry[];
  *
  * 🔑 The population sentinel is keyed on the population line's ABSENCE rather
  * than on there being no `start` lines. Those are different states: a run killed
- * during population has no projection and no honest document, while a run killed
- * between the population and the first statement has both.
+ * during population has no projection, while a run killed between the population
+ * and the first statement has one.
+ *
+ * 🔑 The startup sentinel is keyed the same way, on the `started` line's
+ * absence — never on an empty log. Before that line the child was still loading
+ * Node and the CLI, nothing had touched the tree, and advice about sizing the
+ * budget against a population would be advice about a unit that never began.
  *
  * @param entries - What {@link parseProgressLog} recovered
  * @returns The unit in flight
@@ -146,9 +163,58 @@ export declare function unitInFlight(entries: readonly ProgressEntry[]): UnitInF
  * queued behind work the event loop never gets back to, so the line naming the
  * rule that hangs would exist only in memory — where `SIGKILL` destroys it.
  *
- * @param path - Where the supervisor is watching
+ * @param child - Where the supervisor is watching
  * @returns A writer that appends one entry and returns once it is on disk
  */
-export declare function createProgressWriter(path: string): (entry: ProgressEntry) => void;
+export declare function createProgressWriter(child: Pick<SupervisedChild, 'progressLog'>): (entry: ProgressEntry) => void;
+/**
+ * End this supervised child the moment its supervisor is gone, however the supervisor ended.
+ *
+ * ## 🚨 Why: the bound lives in the supervisor
+ *
+ * A supervisor that dies where none of its own code runs — SIGKILL, an OOM killer — cannot take the
+ * child down, and the child would run on with nothing bounding it and nobody reading what it
+ * publishes. This is the POSIX path: on Windows an outside kill of the supervisor
+ * (`TerminateProcess`) ends this process too, before any of its code runs, because libuv spawns it
+ * in a kill-on-close job object whose only handle the supervisor holds. The pipe below is there on
+ * Windows as well, and harmless.
+ *
+ * ## 🔑 How: the supervisor holds this process's stdin open and never writes to it
+ *
+ * The supervisor spawns the child with stdin as a pipe whose write end only it holds, and it never
+ * writes or ends it. However the supervisor ends, the OS closes that end, and this process reads
+ * end-of-file — with no pid to compare and no liveness probe to misread (a pid
+ * reused, or a probe refused `EPERM` in a sandbox, both used to read wrongly). On EOF, a read error
+ * or a close, the child ends at once: exit 2 and ONE stderr line, no document — nobody is left to
+ * read one. It ends by `process.exit`, never by a signal handler: the child must never install one
+ * (see `check-supervisor.ts`). Nothing else in the child reads stdin.
+ *
+ * The stream is UNREFERENCED, so a child that finishes is never held open by it.
+ *
+ * ⚠️ **It fires when this process's event loop next turns, and only then.** The population is
+ * asynchronous I/O, so an orphan there ends at once. The checks run one after another
+ * synchronously, and a statement blocked inside SQLite reaches nothing until it returns — so an
+ * orphan in the middle of them runs on until the LAST check returns. It then ends before it
+ * publishes anything, because the child turns its loop first ({@link letSupervisorLossSurface}).
+ *
+ * @param supervisorPid - The supervisor's pid, named in the stderr line
+ * @param stdin - This process's stdin: the caller passes `process.stdin`; a test hands it a stream
+ *   it owns
+ */
+export declare function endWhenSupervisorGone(supervisorPid: number, stdin: NodeJS.ReadableStream & {
+    unref?: () => void;
+}): void;
+/**
+ * Let a supervisor's loss END this child before it publishes: turn the event loop twice, so an
+ * end-of-file that has waited on stdin since the supervisor died — while the synchronous check loop
+ * held the thread — is read, and {@link endWhenSupervisorGone} exits before any document is written.
+ *
+ * Twice, because the first turn may begin after this iteration's poll phase: the second always
+ * crosses one. Without it, a child orphaned inside a check wrote its document to a pipe nobody
+ * reads and exited 0.
+ *
+ * @returns A promise that resolves after two turns — when the child is still supervised
+ */
+export declare function letSupervisorLossSurface(): Promise<void>;
 export {};
 //# sourceMappingURL=check-progress.d.ts.map

package/dist/commands/resources/check-progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-progress.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwFxB,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAKvB,CAAC;AAEH,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAQ9D;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,YAAY,CAuB5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAIjF"}
+{"version":3,"file":"check-progress.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA+G7D,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAMvB,CAAC;AAEH,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAQ9D;AA4BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,YAAY,CA2B5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAC1C,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAIhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GACpD,IAAI,CAiBN;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9D"}