@gmickel/gno 2.12.2 → 2.13.0

package/src/cli/commands/index-cmd.ts

@@ -7,6 +7,7 @@
  * @module src/cli/commands/indexCmd
  */
 
+import { resolveReindexScope } from "../../core/reindex-paths";
 import {
   type CliWriteLeaseOptions,
   type WriteLeaseContention,
@@ -27,6 +28,7 @@ import {
   type SyncResult,
   withContentTypeRules,
 } from "../../ingestion";
+import { CliError } from "../errors";
 import { type EmbedResult, embedStageOutcome } from "./embed";
 import {
   formatSyncResultLines,
@@ -44,6 +46,8 @@ export interface IndexOptions extends CliWriteLeaseOptions {
   indexName?: string;
   /** Scope to single collection */
   collection?: string;
+  /** Reindex only these files of `collection` */
+  paths?: string[];
   /** Run ingestion only, skip embedding */
   noEmbed?: boolean;
   /** Download models if missing */
@@ -186,6 +190,18 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
     }
 
     const { store, collections, config } = initResult;
+    let paths: string[] | null;
+    try {
+      paths = await resolveReindexScope(
+        options.collection ? (collections[0] ?? null) : null,
+        options.paths,
+        { gitPull: options.gitPull }
+      );
+    } catch (e) {
+      await store.close();
+      const message = e instanceof Error ? e.message : String(e);
+      throw new CliError("VALIDATION", message.replace(/^[A-Z_]+: /, ""));
+    }
     const db = store.getRawDb();
     const embedSkipped = options.noEmbed ?? false;
 
@@ -202,18 +218,40 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
       markIndexStageRunning(db, "lexical", { collection: options.collection });
       let syncResult: SyncResult;
       try {
-        syncResult = await defaultSyncService.syncAll(
-          collections,
-          store,
-          withContentTypeRules(
-            {
-              gitPull: options.gitPull,
-              runUpdateCmd: true,
-              onSlowConversion: reportSlowConversion,
-            },
-            config
-          )
-        );
+        const collection = collections[0];
+        if (paths && collection) {
+          const pathResult = await defaultSyncService.syncPaths(
+            collection,
+            store,
+            paths,
+            withContentTypeRules(
+              { onSlowConversion: reportSlowConversion },
+              config
+            )
+          );
+          syncResult = {
+            collections: [pathResult],
+            totalDurationMs: pathResult.durationMs,
+            totalFilesProcessed: pathResult.filesProcessed,
+            totalFilesAdded: pathResult.filesAdded,
+            totalFilesUpdated: pathResult.filesUpdated,
+            totalFilesErrored: pathResult.filesErrored,
+            totalFilesSkipped: pathResult.filesSkipped,
+          };
+        } else {
+          syncResult = await defaultSyncService.syncAll(
+            collections,
+            store,
+            withContentTypeRules(
+              {
+                gitPull: options.gitPull,
+                runUpdateCmd: true,
+                onSlowConversion: reportSlowConversion,
+              },
+              config
+            )
+          );
+        }
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         markIndexStageFinished(db, "lexical", "failed");

package/src/cli/commands/query.ts

@@ -19,6 +19,7 @@ import {
   fingerprintContentTypeMetadataRules,
   normalizeContentTypes,
 } from "../../config";
+import { resolveCollectionScope } from "../../core/collection-scope";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
@@ -27,7 +28,7 @@ import {
 } from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
-import { resolveModelUri } from "../../llm/registry";
+import { modelCollectionForList, resolveModelUri } from "../../llm/registry";
 import {
   diagnoseQueryTarget,
   type QueryDiagnoseResult as PipelineQueryDiagnoseResult,
@@ -91,7 +92,7 @@ export type QueryResult =
       data: SearchResults;
       metadata?: RetrievalTraceSurfaceMetadata;
     }
-  | { success: false; error: string };
+  | { success: false; error: string; isValidation?: boolean };
 
 export type QueryDiagnoseCommandOptions = Omit<
   HybridSearchOptions,
@@ -151,17 +152,29 @@ export async function query(
   let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const scope = resolveCollectionScope(options, config.collections);
+    if (!scope.ok) {
+      return {
+        success: false,
+        error: scope.message,
+        isValidation: scope.kind === "validation",
+      };
+    }
+    options = { ...options, collections: scope.collections };
     const { projectAffinityDisabled, projectRoots, ...queryOptions } = options;
     const projectAffinity = await resolveCliProjectAffinity(config, {
       cwd: process.cwd(),
       disabled: projectAffinityDisabled,
       projectRoots,
     });
+    const modelCollection = (type: "embed" | "expand" | "rerank") =>
+      options.collection ??
+      modelCollectionForList(config, type, options.collections);
     const embedUri = resolveModelUri(
       config,
       "embed",
       options.embedModel,
-      options.collection
+      modelCollection("embed")
     );
     const expandUri =
       !options.noExpand && !options.queryModes?.length
@@ -169,7 +182,7 @@ export async function query(
             config,
             "expand",
             options.expandModel ?? options.genModel,
-            options.collection
+            modelCollection("expand")
           )
         : undefined;
     const rerankUri = !options.noRerank
@@ -177,7 +190,7 @@ export async function query(
           config,
           "rerank",
           options.rerankModel,
-          options.collection
+          modelCollection("rerank")
         )
       : undefined;
     const traceStart = await startRetrievalTraceRequest({
@@ -196,9 +209,9 @@ export async function query(
     }
     traceSession = traceStart.value ?? undefined;
     const llm = new LlmAdapter(config);
-    const egressCollections = options.collection
-      ? [options.collection]
-      : ("all" as const);
+    const egressCollections =
+      options.collections ??
+      (options.collection ? [options.collection] : ("all" as const));
 
     // Resolve download policy from env/flags
     const globals = getGlobals();

package/src/cli/commands/search.ts

@@ -13,6 +13,7 @@ import type {
 import type { SearchOptions, SearchResults } from "../../pipeline/types";
 
 import { normalizeContentTypes } from "../../config";
+import { resolveCollectionScope } from "../../core/collection-scope";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
@@ -91,6 +92,15 @@ export async function search(
   let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const scope = resolveCollectionScope(options, config.collections);
+    if (!scope.ok) {
+      return {
+        success: false,
+        error: scope.message,
+        isValidation: scope.kind === "validation",
+      };
+    }
+    options = { ...options, collections: scope.collections };
     const { projectAffinityDisabled, projectRoots, ...searchOptions } = options;
     const projectAffinity = await resolveCliProjectAffinity(config, {
       cwd: process.cwd(),
@@ -104,6 +114,7 @@ export async function search(
       filters: {
         limit,
         collection: options.collection,
+        collections: options.collections,
         lang: options.lang,
         full: options.full,
         lineNumbers: options.lineNumbers,

package/src/cli/commands/vsearch.ts

@@ -13,6 +13,7 @@ import type {
 import type { EmbeddingPort } from "../../llm/types";
 import type { SearchOptions, SearchResults } from "../../pipeline/types";
 
+import { resolveCollectionScope } from "../../core/collection-scope";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
@@ -20,7 +21,7 @@ import {
   startRetrievalTraceRequest,
 } from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
-import { resolveModelUri } from "../../llm/registry";
+import { modelCollectionForList, resolveModelUri } from "../../llm/registry";
 import { formatQueryForEmbedding } from "../../pipeline/contextual";
 import {
   searchVectorWithEmbedding,
@@ -65,7 +66,7 @@ export type VsearchResult =
       data: SearchResults;
       metadata?: RetrievalTraceSurfaceMetadata;
     }
-  | { success: false; error: string };
+  | { success: false; error: string; isValidation?: boolean };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Command Implementation
@@ -99,6 +100,15 @@ export async function vsearch(
   let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const scope = resolveCollectionScope(options, config.collections);
+    if (!scope.ok) {
+      return {
+        success: false,
+        error: scope.message,
+        isValidation: scope.kind === "validation",
+      };
+    }
+    options = { ...options, collections: scope.collections };
     const { projectAffinityDisabled, projectRoots, ...searchOptions } = options;
     const projectAffinity = await resolveCliProjectAffinity(config, {
       cwd: process.cwd(),
@@ -110,7 +120,8 @@ export async function vsearch(
       config,
       "embed",
       options.model,
-      options.collection
+      options.collection ??
+        modelCollectionForList(config, "embed", options.collections)
     );
     const traceStart = await startRetrievalTraceRequest({
       store,
@@ -129,7 +140,9 @@ export async function vsearch(
     // Create LLM adapter for embeddings
     const llm = new LlmAdapter(config);
     const embedResult = await llm.createEmbeddingPort(modelUri, {
-      egressCollections: options.collection ? [options.collection] : "all",
+      egressCollections:
+        options.collections ??
+        (options.collection ? [options.collection] : "all"),
     });
     if (!embedResult.ok) {
       await traceSession?.finish("failed");

package/src/cli/options.ts

@@ -26,6 +26,23 @@ export interface CliProjectAffinityOptions {
   projectRoots: string[];
 }
 
+/**
+ * Map repeatable `-c` values for search/vsearch/query: one value keeps the
+ * single-collection `collection` path; two or more form the allowlist.
+ */
+export const splitCollectionFlags = (
+  value: unknown
+): { collection?: string; collections?: string[] } => {
+  const values = Array.isArray(value)
+    ? (value as string[])
+    : typeof value === "string"
+      ? [value]
+      : [];
+  if (values.length === 0) return {};
+  if (values.length === 1) return { collection: values[0] };
+  return { collections: values };
+};
+
 export const collectRepeatableValue = (
   value: string,
   previous: string[] = []
@@ -70,6 +87,7 @@ export const CMD = {
   ask: "ask",
   get: "get",
   multiGet: "multi-get",
+  convert: "convert",
   ls: "ls",
   status: "status",
   peek: "peek",
@@ -107,6 +125,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.ask]: ["terminal", "json", "md"],
   [CMD.get]: ["terminal", "json", "md"],
   [CMD.multiGet]: ["terminal", "json", "files", "md"],
+  [CMD.convert]: ["terminal", "json"],
   [CMD.ls]: ["terminal", "json", "files", "md"],
   [CMD.status]: ["terminal", "json"],
   [CMD.peek]: ["terminal", "json"],

package/src/cli/program.ts

@@ -52,6 +52,7 @@ import {
   assertFormatSupported,
   CMD,
   collectRepeatableValue,
+  splitCollectionFlags,
   getDefaultLimit,
   parseCliProjectAffinityOptions,
   parseCliMetadataFilter,
@@ -325,6 +326,18 @@ function validateContextOutputPath(value: unknown): string | undefined {
 // Program Factory
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** `query --diagnose` explains one collection scope; several `-c` are refused. */
+function singleDiagnoseCollection(value: unknown): string | undefined {
+  const { collection, collections } = splitCollectionFlags(value);
+  if (collections) {
+    throw new CliError(
+      "VALIDATION",
+      "query --diagnose accepts a single -c collection"
+    );
+  }
+  return collection;
+}
+
 export function createProgram(): Command {
   const program = new Command();
 
@@ -349,7 +362,7 @@ export function createProgram(): Command {
     .option("--no-pager", "disable automatic paging of long output");
 
   // Resolve globals ONCE before any command runs (ensures consistency)
-  program.hook("preAction", async (thisCommand) => {
+  program.hook("preAction", async (thisCommand, actionCommand) => {
     const rootOpts = thisCommand.optsWithGlobals();
     const globals = parseGlobalOptions(rootOpts);
     if (!isValidIndexName(globals.index)) {
@@ -360,6 +373,8 @@ export function createProgram(): Command {
     }
     applyGlobalOptions(globals);
     globalState.current = globals;
+    // convert reads no config or index, so there is no binding to check.
+    if (actionCommand === convertCommand) return;
     const { assertCliSessionBinding } = await import("./session-binding");
     await assertCliSessionBinding(globals.config, globals.index);
   });
@@ -375,6 +390,7 @@ export function createProgram(): Command {
   wirePublishCommand(program);
   wireVecCommands(program);
   wireRetrievalCommands(program);
+  const convertCommand = wireConvertCommand(program);
   wireTagsCommands(program);
   wireLinksCommands(program);
   wireGraphCommand(program);
@@ -650,7 +666,11 @@ function wireSearchCommands(program: Command): void {
     )
     .option("-n, --limit <num>", "max results")
     .option("--min-score <num>", "minimum score threshold")
-    .option("-c, --collection <name>", "filter by collection")
+    .option(
+      "-c, --collection <name>",
+      "filter by collection (repeat for several)",
+      collectRepeatableValue
+    )
     .option("--lang <code>", "language filter/hint (BCP-47)")
     .option(
       "--since <date>",
@@ -740,7 +760,7 @@ function wireSearchCommands(program: Command): void {
           indexName: globals.index,
           limit,
           minScore,
-          collection: cmdOpts.collection as string | undefined,
+          ...splitCollectionFlags(cmdOpts.collection),
           lang: cmdOpts.lang as string | undefined,
           since: cmdOpts.since as string | undefined,
           until: cmdOpts.until as string | undefined,
@@ -790,7 +810,11 @@ function wireSearchCommands(program: Command): void {
     .description("Vector similarity search")
     .option("-n, --limit <num>", "max results")
     .option("--min-score <num>", "minimum score threshold")
-    .option("-c, --collection <name>", "filter by collection")
+    .option(
+      "-c, --collection <name>",
+      "filter by collection (repeat for several)",
+      collectRepeatableValue
+    )
     .option("--lang <code>", "language filter/hint (BCP-47)")
     .option(
       "--since <date>",
@@ -870,7 +894,7 @@ function wireSearchCommands(program: Command): void {
         indexName: globals.index,
         limit,
         minScore,
-        collection: cmdOpts.collection as string | undefined,
+        ...splitCollectionFlags(cmdOpts.collection),
         lang: cmdOpts.lang as string | undefined,
         since: cmdOpts.since as string | undefined,
         until: cmdOpts.until as string | undefined,
@@ -892,7 +916,10 @@ function wireSearchCommands(program: Command): void {
       });
 
       if (!result.success) {
-        throw new CliError("RUNTIME", result.error);
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
+        );
       }
       const output = formatVsearch(result, {
         json: format === "json",
@@ -918,7 +945,11 @@ function wireSearchCommands(program: Command): void {
     )
     .option("-n, --limit <num>", "max results")
     .option("--min-score <num>", "minimum score threshold")
-    .option("-c, --collection <name>", "filter by collection")
+    .option(
+      "-c, --collection <name>",
+      "filter by collection (repeat for several)",
+      collectRepeatableValue
+    )
     .option("--lang <code>", "language hint (BCP-47)")
     .option(
       "--since <date>",
@@ -1088,7 +1119,7 @@ function wireSearchCommands(program: Command): void {
             target: cmdOpts.target as string,
             limit,
             minScore,
-            collection: cmdOpts.collection as string | undefined,
+            collection: singleDiagnoseCollection(cmdOpts.collection),
             lang: cmdOpts.lang as string | undefined,
             since: cmdOpts.since as string | undefined,
             until: cmdOpts.until as string | undefined,
@@ -1125,7 +1156,7 @@ function wireSearchCommands(program: Command): void {
           indexName: globals.index,
           limit,
           minScore,
-          collection: cmdOpts.collection as string | undefined,
+          ...splitCollectionFlags(cmdOpts.collection),
           lang: cmdOpts.lang as string | undefined,
           since: cmdOpts.since as string | undefined,
           until: cmdOpts.until as string | undefined,
@@ -1154,7 +1185,10 @@ function wireSearchCommands(program: Command): void {
         });
 
         if (!result.success) {
-          throw new CliError("RUNTIME", result.error);
+          throw new CliError(
+            result.isValidation ? "VALIDATION" : "RUNTIME",
+            result.error
+          );
         }
         const output = formatQuery(result, {
           format,
@@ -1624,6 +1658,10 @@ function wireOnboardingCommands(program: Command): void {
     program
       .command("index [collection]")
       .description("Index files from collections")
+      .option(
+        "--path <path...>",
+        "reindex only these files of the collection (relative to its root)"
+      )
       .option("--no-embed", "skip embedding after sync")
       .option("--git-pull", "run git pull in git repositories")
       .option("--models-pull", "download models if missing")
@@ -1640,6 +1678,7 @@ function wireOnboardingCommands(program: Command): void {
         configPath: globals.config,
         indexName: globals.index,
         collection,
+        paths: cmdOpts.path as string[] | undefined,
         noEmbed: cmdOpts.embed === false,
         gitPull: Boolean(cmdOpts.gitPull),
         modelsPull: Boolean(cmdOpts.modelsPull),
@@ -2436,6 +2475,36 @@ function wireSessionsAutomationCommands(
 // Retrieval Commands (get, multi-get, ls)
 // ─────────────────────────────────────────────────────────────────────────────
 
+function wireConvertCommand(program: Command): Command {
+  return program
+    .command("convert <file>")
+    .description("Print the Markdown GNO would index for one file")
+    .option("--json", "JSON output")
+    .action(async (file: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.convert, format);
+
+      const { convertFile } = await import("../ingestion/convert-file");
+      const result = await convertFile(file);
+      if (!result.ok) {
+        const { reason, message, validation, details } = result.error;
+        throw new CliError(validation ? "VALIDATION" : "RUNTIME", message, {
+          details: { reason, ...details },
+        });
+      }
+
+      if (format === "json") {
+        process.stdout.write(`${JSON.stringify(result.value, null, 2)}\n`);
+        return;
+      }
+      // Warnings go to stderr so stdout stays exactly the Markdown.
+      for (const warning of result.value.warnings) {
+        process.stderr.write(`Warning: ${warning.code}: ${warning.message}\n`);
+      }
+      process.stdout.write(result.value.markdown);
+    });
+}
+
 function wireRetrievalCommands(program: Command): void {
   // get - Retrieve document by URI or docid
   program

package/src/core/collection-scope.ts

@@ -0,0 +1,105 @@
+/**
+ * Request-level collection allowlist shared by search, vsearch and query on
+ * every surface (CLI, MCP, REST, SDK).
+ *
+ * @module src/core/collection-scope
+ */
+
+/** Most collections one request may list; matches the audit scope bound. */
+export const MAX_REQUEST_COLLECTIONS = 256;
+
+export type CollectionListResult =
+  | { ok: true; value: string[] }
+  | { ok: false; message: string };
+
+/**
+ * Normalize a `collections` allowlist: trim, lowercase, de-duplicate, sort.
+ * Rejects non-arrays, non-string or blank members, an empty list, and lists
+ * longer than {@link MAX_REQUEST_COLLECTIONS} after normalization.
+ */
+export function normalizeCollectionList(input: unknown): CollectionListResult {
+  if (!Array.isArray(input)) {
+    return { ok: false, message: "collections must be an array of names" };
+  }
+  const names = new Set<string>();
+  for (const value of input) {
+    if (typeof value !== "string" || value.trim() === "") {
+      return {
+        ok: false,
+        message: "collections must contain only non-empty collection names",
+      };
+    }
+    names.add(value.trim().toLowerCase());
+  }
+  if (names.size === 0) {
+    return { ok: false, message: "collections must list at least one name" };
+  }
+  if (names.size > MAX_REQUEST_COLLECTIONS) {
+    return {
+      ok: false,
+      message: `collections must list at most ${MAX_REQUEST_COLLECTIONS} names`,
+    };
+  }
+  return {
+    ok: true,
+    value: [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+  };
+}
+
+/** Error text when a request names both `collection` and `collections`. */
+export const COLLECTION_AND_COLLECTIONS_MESSAGE =
+  "Pass either collection or collections, not both";
+
+/** Names in `requested` that are not configured, in request order. */
+export function unknownCollections(
+  requested: readonly string[],
+  configured: readonly { name: string }[]
+): string[] {
+  const known = new Set(configured.map(({ name }) => name.toLowerCase()));
+  return requested.filter((name) => !known.has(name));
+}
+
+/** The existing unknown-collection message, naming every unknown name. */
+export function unknownCollectionsMessage(names: readonly string[]): string {
+  return names.length === 1
+    ? `Collection not found: ${names[0]}`
+    : `Collections not found: ${names.join(", ")}`;
+}
+
+export type CollectionScopeResult =
+  | { ok: true; collections: string[] | undefined }
+  | { ok: false; kind: "validation" | "not_found"; message: string };
+
+/**
+ * Resolve a request's `collections` allowlist against the configured
+ * collections. Absent `collections` resolves to undefined (unchanged
+ * single-collection behaviour). Both inputs together, a malformed list, or
+ * any unknown name is refused.
+ */
+export function resolveCollectionScope(
+  input: { collection?: unknown; collections?: unknown },
+  configured: readonly { name: string }[]
+): CollectionScopeResult {
+  if (input.collections === undefined)
+    return { ok: true, collections: undefined };
+  if (input.collection !== undefined) {
+    return {
+      ok: false,
+      kind: "validation",
+      message: COLLECTION_AND_COLLECTIONS_MESSAGE,
+    };
+  }
+  const normalized = normalizeCollectionList(input.collections);
+  if (!normalized.ok) {
+    return { ok: false, kind: "validation", message: normalized.message };
+  }
+  const unknown = unknownCollections(normalized.value, configured);
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      kind: "not_found",
+      message: unknownCollectionsMessage(unknown),
+    };
+  }
+  return { ok: true, collections: normalized.value };
+}

package/src/core/errors.ts

@@ -13,6 +13,11 @@ export const MCP_ERRORS = {
     code: "JOB_CONFLICT",
     message: "Another job is already running.",
   },
+  QUEUE_FULL: {
+    code: "QUEUE_FULL",
+    message:
+      "Too many reindex jobs are waiting. Retry after the running job finishes.",
+  },
   INVALID_PATH: {
     code: "INVALID_PATH",
     message: "Path violates safety rules.",