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

package/dist/commands/rag/index.js

@@ -49,7 +49,7 @@ Configuration:
         .description('Index markdown resources into vector database')
         .option(DB_PATH_OPTION, DB_PATH_DESC)
         .option('--debug', DEBUG_OPTION_DESC)
-        .action(lazyAction(RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
+        .action(lazyAction('rag index', RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
         .addHelpText('after', `
 Description:
   Indexes markdown files into LanceDB vector database for semantic search.
@@ -61,21 +61,34 @@ Description:
   When path specified: recursively finds all *.md files (ignores config)
   When no path: uses vibe-agent-toolkit.config.yaml include/exclude patterns
 
-Output Structure (YAML):
-  status: success (every resource indexed) / partial (some failed) / error
-  resourcesIndexed: new/updated files
-  resourcesSkipped: unchanged files (content hash match)
-  resourcesEmpty: files that chunked to nothing (frontmatter-only or blank);
-          recorded, not searchable, not an error
-  resourcesUpdated: files with new content
-  chunksCreated: total chunks added
-  chunksDeleted: chunks removed from updated files
-  duration: total indexing time
-  errors: resources that failed, present only when non-empty. Their content
-          is NOT in the index and NOT searchable.
+Output:
+  A YAML report on stdout (status ok, findings or error); examined counts
+  the resources submitted. Its data holds:
+  - resourcesIndexed: new/updated files
+  - resourcesSkipped: unchanged files (content hash match)
+  - resourcesEmpty: files that chunked to nothing (frontmatter-only or blank);
+    recorded, not searchable, not an error
+  - resourcesUpdated: files with new content
+  - chunksCreated / chunksDeleted: chunks added, and removed from updated files
+  Each file NOT in the index (unreadable, or failed to chunk or embed) is a
+  RAG_DOCUMENT_INDEX_FAILED finding at its path; its content is not searchable.
 
 Exit Codes:
-  0 - Success  |  1 - Indexed with errors (see 'errors')  |  2 - System error
+  0 - Every submitted file indexed (or skipped as unchanged)
+  1 - Findings: at least one file is not in the index
+  2 - Could not run (error.code says why: USAGE_INVALID for a missing path or
+      --db, a --db that is (or lies under) a file, or a --db directory holding
+      anything but a RAG database; INPUT_UNREADABLE, also for a project
+      .rag-db that is a file or holds anything else, and for a chunk table that
+      cannot be read — files the OS refuses (the message names the path and
+      errno: fix the permissions), a table another tool or build wrote, or
+      damaged files (vat rag clear removes either); RUN_INCOMPLETE when the
+      database directory cannot be examined, listed, created or written;
+      CONFIG_INVALID;
+      BACKEND_UNAVAILABLE when the RAG backend is not installed; INTERNAL_ERROR
+      for a database error such as a rag_documents table whose columns an
+      earlier build typed differently — the message names the columns, and
+      vat rag clear is the remedy)
 
 Requirements:
   projectRoot: optional (tolerates absence — use --db to specify path)
@@ -94,22 +107,20 @@ Example:
         .option(DB_PATH_OPTION, DB_PATH_DESC)
         .option('--limit <n>', 'Maximum results to return (default: 10)', Number.parseInt)
         .option('--debug', DEBUG_OPTION_DESC)
-        .action(lazyAction(RAG_BACKEND, async () => (await import('./query-command.js')).queryCommand))
+        .action(lazyAction('rag query', RAG_BACKEND, async () => (await import('./query-command.js')).queryCommand))
         .addHelpText('after', `
 Description:
   Searches vector database using semantic similarity. Converts your query
   to a vector embedding and finds the most relevant document chunks based
   on meaning (not just keywords). Returns full chunk content with metadata.
 
-Output Structure (YAML):
-  status: success/error
-  query: original search text
-  stats:
-    totalMatches: number of results
-    searchDurationMs: query time
-    embedding.model: model used for embeddings
-  duration: total command time
-  chunks: array of matching document chunks with full content
+Output:
+  A YAML report on stdout (status ok, or error); examined counts the chunks
+  in the index searched, so a query matching nothing is ok. Its data holds:
+  - root: the directory every filePath is relative to
+  - query: original search text
+  - stats: totalMatches, searchDurationMs, embedding.model
+  - chunks: matching document chunks with full content
 
 Each chunk includes:
   - chunkId, resourceId, filePath (identifiers)
@@ -119,7 +130,14 @@ Each chunk includes:
   - content (full text, not truncated)
 
 Exit Codes:
-  0 - Success  |  2 - System error (no database)
+  0 - Searched
+  2 - Could not run (error.code: INPUT_UNREADABLE when nothing is indexed yet,
+      the database cannot be read (damaged table files included), or the
+      project .rag-db holds anything else; USAGE_INVALID with no --db and no
+      project or a --db that is not a RAG database — nothing there, a file,
+      or a directory holding anything but the tables vat rag index writes
+      (operating-system litter such as .DS_Store aside); BACKEND_UNAVAILABLE;
+      INTERNAL_ERROR for an embedding failure)
 
 Requirements:
   projectRoot: optional (tolerates absence — use --db to specify path)
@@ -136,24 +154,32 @@ Example:
         .description('Show RAG database statistics')
         .option(DB_PATH_OPTION, DB_PATH_DESC)
         .option('--debug', DEBUG_OPTION_DESC)
-        .action(lazyAction(RAG_BACKEND, async () => (await import('./stats-command.js')).statsCommand))
+        .action(lazyAction('rag stats', RAG_BACKEND, async () => (await import('./stats-command.js')).statsCommand))
         .addHelpText('after', `
 Description:
   Displays vector database statistics including indexed content count,
   embedding model information, and database metadata. Use this to verify
   indexing completed successfully and monitor database size.
 
-Output Structure (YAML):
-  status: success/error
-  totalChunks: number of document chunks indexed
-  totalResources: number of unique documents indexed
-  dbSizeBytes: database size on disk (if available)
-  embeddingModel: model used for vector embeddings
-  lastIndexed: timestamp of most recent indexing
-  duration: command execution time
+Output:
+  A YAML report on stdout (status ok, or error); examined is 1, the database
+  opened. Its data holds:
+  - totalChunks: number of document chunks indexed
+  - totalResources: number of unique documents indexed
+  - dbSizeBytes: database size on disk
+  - embeddingModel: model used for vector embeddings
+  - lastIndexed: ISO 8601 timestamp of the most recent indexing
 
 Exit Codes:
-  0 - Success  |  2 - System error (no database)
+  0 - Reported (an existing database holding nothing reports zeros)
+  2 - Could not run (error.code: USAGE_INVALID with no --db and no project or
+      a --db that is not a RAG database — nothing there, a file, or a
+      directory holding anything but the tables vat rag index writes
+      (operating-system litter such as .DS_Store aside) — INPUT_UNREADABLE
+      when the project has no database yet, its .rag-db holds anything else,
+      or the database cannot be read (damaged table files included),
+      BACKEND_UNAVAILABLE, INTERNAL_ERROR for a defect in VAT). Never creates
+      the database.
 
 Requirements:
   projectRoot: optional (tolerates absence — use --db to specify path)
@@ -170,7 +196,7 @@ Example:
         .description('Delete entire RAG database directory')
         .option(DB_PATH_OPTION, DB_PATH_DESC)
         .option('--debug', DEBUG_OPTION_DESC)
-        .action(lazyAction(RAG_BACKEND, async () => (await import('./clear-command.js')).clearCommand))
+        .action(lazyAction('rag clear', RAG_BACKEND, async () => (await import('./clear-command.js')).clearCommand))
         .addHelpText('after', `
 Description:
   Deletes the entire RAG database directory and all indexed data.
@@ -181,13 +207,34 @@ Warning:
   This operation cannot be undone. The database directory will be
   permanently deleted. Re-run 'vat rag index' to rebuild from source.
 
-Output Structure (YAML):
-  status: success/error
-  message: confirmation message
-  duration: command execution time
+  Only a RAG database is removed: a directory holding nothing but the tables
+  vat rag index writes (and operating-system litter files such as .DS_Store:
+  a regular file that starts with the bytes the OS writes into it — a ._*
+  file of your own, or a directory or link with a litter name, is not
+  litter). It is
+  removed without being opened, so a database whose files are damaged can
+  still be cleared. Any other directory is refused and left untouched, and so
+  is a --db that is a symbolic link: removing the link would leave the
+  database in place, so the refusal names the path it links to. The
+  database is moved off its path whole before it is removed, so a removal
+  the OS stops never leaves part of it at the path you named.
+
+Output:
+  A YAML report on stdout (status ok, or error); examined is 1, the database
+  removed. Its data is { cleared: true }.
 
 Exit Codes:
-  0 - Success  |  2 - System error
+  0 - Cleared
+  2 - Could not run (error.code: USAGE_INVALID with no --db and no project or
+      a --db that is not a RAG database — nothing there, a file, a symbolic
+      link, or a directory holding anything but the tables vat rag index
+      writes — INPUT_UNREADABLE when the project has no database yet, or its
+      .rag-db is a link or holds anything else; RUN_INCOMPLETE when it cannot
+      be examined, listed or moved off its path (it is what clear removes), or
+      the OS stopped deleting it once it was off its path — then the clear is
+      done (data present) and a TREE_CLEANUP_INCOMPLETE warning names where
+      the rest is, for you to remove);
+      BACKEND_UNAVAILABLE; INTERNAL_ERROR for a defect in VAT)
 
 Requirements:
   projectRoot: optional (tolerates absence — use --db to specify path)

package/dist/commands/rag/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/rag/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAwB,MAAM,iCAAiC,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,GAAoB;IACnC,OAAO,EAAE,KAAK;IACd,WAAW,EAAE,iCAAiC;CAC/C,CAAC;AAEF,6BAA6B;AAC7B,MAAM,cAAc,GAAG,aAAa,CAAC;AACrC,MAAM,YAAY,GAAG,kDAAkD,CAAC;AACxE,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AAEjD,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IAE/B,GAAG;SACA,WAAW,CAAC,qEAAqE,CAAC;SAClF,WAAW,CAAC,KAAK,CAAC,CAAC,uDAAuD;SAC1E,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;CAmBL,CACI,CAAC;IAEJ,GAAG;SACA,OAAO,CAAC,cAAc,CAAC;SACvB,WAAW,CAAC,+CAA+C,CAAC;SAC5D,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC;SACpC,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC;SACpC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;SAC9F,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCL,CACI,CAAC;IAEJ,GAAG;SACA,OAAO,CAAC,cAAc,CAAC;SACvB,WAAW,CAAC,yCAAyC,CAAC;SACtD,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC;SACpC,MAAM,CAAC,aAAa,EAAE,yCAAyC,EAAE,MAAM,CAAC,QAAQ,CAAC;SACjF,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC;SACpC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;SAC9F,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCL,CACI,CAAC;IAEJ,GAAG;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,8BAA8B,CAAC;SAC3C,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC;SACpC,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC;SACpC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;SAC9F,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BL,CACI,CAAC;IAEJ,GAAG;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,sCAAsC,CAAC;SACnD,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC;SACpC,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC;SACpC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;SAC9F,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BL,CACI,CAAC;IAEJ,OAAO,GAAG,CAAC;AACb,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/rag/index.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 /**
  * RAG query command - search the vector database
  */
+import type { RagQueryData } from './query-schema.js';
 interface QueryOptions {
     db?: string;
     limit?: number;
@@ -29,13 +30,12 @@ interface QueriedChunk {
 export interface QueryPayloadInput {
     queryText: string;
     chunks: readonly QueriedChunk[];
-    stats: unknown;
-    durationMs: number;
+    stats: RagQueryData['stats'];
     /** The stated root: the ONE base every reported path is relative to. */
     root: string;
 }
 /**
- * Build the query payload.
+ * Build the query `data`.
  *
  * `resourceId` is already relative — the registry derives it from the indexing
  * base — so an absolute `filePath` one line above it put a single record in two
@@ -45,7 +45,21 @@ export interface QueryPayloadInput {
  * Fields are ordered deliberately: short ones first, `content` last, so a long
  * result stays scannable.
  */
-export declare function buildQueryOutputData(input: QueryPayloadInput): Record<string, unknown>;
+export declare function buildQueryOutputData(input: QueryPayloadInput): RagQueryData;
+/**
+ * Refuse an index that holds no chunk, as the provider refuses one with no table.
+ *
+ * "Nothing indexed" reaches this command two ways — a database with no chunk
+ * table (the provider's query throws `RAG_INDEX_EMPTY`) and a table holding
+ * zero chunks (the query would return nothing, and the writer's zero-examined
+ * refusal would publish a finding at exit 1). One situation, one outcome: the
+ * same code, which the refusal map reads as INPUT_UNREADABLE (exit 2).
+ *
+ * @param totalChunks - Chunks in the index, from the provider's stats
+ * @param dbPath - The database, for the message
+ * @throws {VatError} `RAG_INDEX_EMPTY` when the index holds no chunk
+ */
+export declare function assertIndexHoldsChunks(totalChunks: number, dbPath: string): void;
 export declare function queryCommand(queryText: string, options: QueryOptions): Promise<void>;
 export {};
 //# sourceMappingURL=query-command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query-command.d.ts","sourceRoot":"","sources":["../../../src/commands/rag/query-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,0FAA0F;AAC1F,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,IAAI,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2CtF;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAmCf"}
+{"version":3,"file":"query-command.d.ts","sourceRoot":"","sources":["../../../src/commands/rag/query-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,mBAAmB,CAAC;AAEtE,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,0FAA0F;AAC1F,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,IAAI,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAC7B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAoC3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAMhF;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAoCf"}

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

@@ -1,14 +1,14 @@
 /**
  * RAG query command - search the vector database
  */
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { safePath } from '@vibe-agent-toolkit/utils';
-import { writeYamlOutput } from '../../utils/output.js';
+import { buildReport } from '@vibe-agent-toolkit/schema';
+import { RAG_INDEX_EMPTY_CODE, safePath, VatError } from '@vibe-agent-toolkit/utils';
+import { endWithReport } from '../../utils/document-writer.js';
 import { projectRootOrNull } from '../../utils/project-root-policy.js';
 import { relativizePath } from '../../utils/relativize-paths.js';
-import { executeRagOperation, formatDuration } from './command-helpers.js';
+import { executeRagOperation, RAG_GATE } from './command-helpers.js';
 /**
- * Build the query payload.
+ * Build the query `data`.
  *
  * `resourceId` is already relative — the registry derives it from the indexing
  * base — so an absolute `filePath` one line above it put a single record in two
@@ -19,7 +19,7 @@ import { executeRagOperation, formatDuration } from './command-helpers.js';
  * result stays scannable.
  */
 export function buildQueryOutputData(input) {
-    const { queryText, chunks, stats, durationMs, root } = input;
+    const { queryText, chunks, stats, root } = input;
     const formattedChunks = chunks.map((chunk) => ({
         // Identifiers
         chunkId: chunk.chunkId,
@@ -38,45 +38,60 @@ export function buildQueryOutputData(input) {
         contentHash: chunk.contentHash,
         tokenCount: chunk.tokenCount,
         embeddingModel: chunk.embeddingModel,
-        embeddedAt: chunk.embeddedAt,
+        embeddedAt: chunk.embeddedAt.toISOString(),
         // Context links (short)
         ...(chunk.previousChunkId ? { previousChunkId: chunk.previousChunkId } : {}),
         ...(chunk.nextChunkId ? { nextChunkId: chunk.nextChunkId } : {}),
         // Content (long, last)
         content: chunk.content,
     }));
-    // Stats/duration before chunks (short fields first)
-    return {
-        status: 'success',
-        root,
-        query: queryText,
-        stats,
-        duration: formatDuration(durationMs),
-        chunks: formattedChunks,
-    };
+    // Stats before chunks (short fields first)
+    return { root, query: queryText, stats, chunks: formattedChunks };
+}
+/**
+ * Refuse an index that holds no chunk, as the provider refuses one with no table.
+ *
+ * "Nothing indexed" reaches this command two ways — a database with no chunk
+ * table (the provider's query throws `RAG_INDEX_EMPTY`) and a table holding
+ * zero chunks (the query would return nothing, and the writer's zero-examined
+ * refusal would publish a finding at exit 1). One situation, one outcome: the
+ * same code, which the refusal map reads as INPUT_UNREADABLE (exit 2).
+ *
+ * @param totalChunks - Chunks in the index, from the provider's stats
+ * @param dbPath - The database, for the message
+ * @throws {VatError} `RAG_INDEX_EMPTY` when the index holds no chunk
+ */
+export function assertIndexHoldsChunks(totalChunks, dbPath) {
+    if (totalChunks > 0)
+        return;
+    throw new VatError(RAG_INDEX_EMPTY_CODE, `No data indexed yet: the index at ${dbPath} holds no chunk to search. Run vat rag index first, and check its findings for documents that failed.`);
 }
 export async function queryCommand(queryText, options) {
     const startTime = Date.now();
-    const result = await executeRagOperation(options, async (ragProvider, logger) => {
+    const { result, indexedChunks } = await executeRagOperation('rag query', options, async (ragProvider, logger, dbPath) => {
+        // `examined` is what was searched — the index — so a query that matches
+        // nothing over a populated index is a clean answer, not an empty run.
+        // Asked BEFORE the query, so an empty index refuses one way however it is empty.
+        const { totalChunks } = await ragProvider.getStats();
+        assertIndexHoldsChunks(totalChunks, dbPath);
         logger.debug(`Querying for: "${queryText}"`);
-        // Execute query
         const queryResult = await ragProvider.query({
             text: queryText,
             limit: options.limit ?? 10,
         });
-        return queryResult;
-    }, 'Query');
+        return { result: queryResult, indexedChunks: totalChunks };
+    });
     // The index lives under the project (`<projectRoot>/.rag-db` by default) and
     // its `resourceId`s are already project-relative, so projectRoot is the base
     // that puts `filePath` in the same coordinate system.
     const root = projectRootOrNull(process.cwd()) ?? safePath.resolve(process.cwd());
-    writeYamlOutput(buildQueryOutputData({
-        queryText,
-        chunks: result.chunks,
-        stats: result.stats,
+    const report = buildReport({
+        examined: indexedChunks,
+        findings: [],
+        data: buildQueryOutputData({ queryText, chunks: result.chunks, stats: result.stats, root }),
+        gate: RAG_GATE,
         durationMs: Date.now() - startTime,
-        root,
-    }));
-    process.exit(ExitCode.OK);
+    });
+    endWithReport('rag query', report, 'yaml');
 }
 //# sourceMappingURL=query-command.js.map

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

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