@gmickel/gno 2.12.2 → 2.14.0

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
@@ -2556,6 +2625,7 @@ function wireRetrievalCommands(program: Command): void {
       "Skip first N results",
       parsePositiveInt.bind(null, "offset")
     )
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--json", "JSON output")
     .option("--files", "File protocol output")
     .option("--md", "Markdown output")
@@ -2564,6 +2634,7 @@ function wireRetrievalCommands(program: Command): void {
         const format = getFormat(cmdOpts);
         assertFormatSupported(CMD.ls, format);
         const globals = getGlobals();
+        const filter = parseCliMetadataFilter(cmdOpts.filter);
 
         const { ls, formatLs } = await import("./commands/ls");
         const result = await ls(scope, {
@@ -2571,6 +2642,7 @@ function wireRetrievalCommands(program: Command): void {
           indexName: globals.index,
           limit: cmdOpts.limit as number | undefined,
           offset: cmdOpts.offset as number | undefined,
+          filter,
           json: format === "json",
           files: format === "files",
           md: format === "md",
@@ -2583,6 +2655,14 @@ function wireRetrievalCommands(program: Command): void {
           );
         }
 
+        // JSON carries warnings in meta; other formats keep stdout clean.
+        if (format !== "json") {
+          for (const warning of result.data.meta.warnings ?? []) {
+            process.stderr.write(
+              `Warning: ${warning.code}: ${warning.message}\n`
+            );
+          }
+        }
         const output = formatLs(result, {
           json: format === "json",
           files: format === "files",

package/src/config/loader.ts

@@ -126,11 +126,21 @@ export async function loadConfigFromPath(
   const result = ConfigSchema.safeParse(parsed);
 
   if (!result.success) {
+    // Collection `audit` mistakes name the setting; other issues keep the
+    // generic message.
+    const auditIssues = result.error.issues.filter((issue) =>
+      issue.path.includes("audit")
+    );
     return {
       ok: false,
       error: {
         code: "VALIDATION_ERROR",
-        message: "Config validation failed",
+        message:
+          auditIssues.length > 0
+            ? `Config validation failed: ${auditIssues
+                .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+                .join("; ")}`
+            : "Config validation failed",
         issues: result.error.issues,
       },
     };

package/src/config/types.ts

@@ -114,6 +114,74 @@ const COLLECTION_NAME_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 /** Collection scope key pattern: name (1-64 chars) followed by colon */
 const COLLECTION_SCOPE_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}:$/;
 
+/** Most globs one collection's `audit.paths` may list. */
+export const COLLECTION_AUDIT_MAX_PATHS = 64;
+const COLLECTION_AUDIT_MAX_GLOB_CHARS = 1024;
+
+/**
+ * A path glob in `pattern` syntax: relative, no `..` segment, balanced
+ * `{}` / `[]`. Bun.Glob accepts nearly any string, so the shape is checked.
+ */
+export function isValidAuditPathGlob(glob: string): boolean {
+  if (glob.trim() !== glob || glob.length === 0) return false;
+  if (glob.includes("\0") || glob.startsWith("/")) return false;
+  if (glob.split("/").includes("..")) return false;
+  let braces = 0;
+  let inClass = false;
+  for (const char of glob) {
+    if (inClass) {
+      if (char === "]") inClass = false;
+      continue;
+    }
+    if (char === "[") inClass = true;
+    else if (char === "{") braces += 1;
+    else if (char === "}") {
+      braces -= 1;
+      if (braces < 0) return false;
+    }
+  }
+  return braces === 0 && !inClass;
+}
+
+/**
+ * Opt-in, report-only audit rules for one collection (`gno audit links`).
+ * They never block indexing, retrieval or editing.
+ */
+export const CollectionAuditSchema = z
+  .object({
+    /** Other collections this one may link to; its own is always allowed. */
+    linkCollections: z
+      .array(
+        z
+          .string()
+          .regex(
+            COLLECTION_NAME_REGEX,
+            "audit.linkCollections entries must be collection names"
+          )
+      )
+      .max(256)
+      .optional(),
+    /** `report` lists external URLs written in documents. Not egress. */
+    externalUrls: z.enum(["report", "ignore"]).optional(),
+    /** Each document path must match at least one glob. */
+    paths: z
+      .array(
+        z
+          .string()
+          .max(COLLECTION_AUDIT_MAX_GLOB_CHARS)
+          .refine(isValidAuditPathGlob, {
+            message:
+              "audit.paths entries must be relative globs without '..' and with balanced {} and []",
+          })
+      )
+      .min(1, "audit.paths must list at least one glob")
+      .max(COLLECTION_AUDIT_MAX_PATHS)
+      .optional(),
+  })
+  .strict();
+
+export type CollectionAuditConfig = z.infer<typeof CollectionAuditSchema>;
+
 export const CollectionSchema = z.object({
   /** Unique collection identifier (lowercase) */
   name: z
@@ -184,6 +252,9 @@ export const CollectionSchema = z.object({
    */
   memoryManaged: z.boolean().optional(),
 
+  /** Opt-in report-only link and path rules for `gno audit links`. */
+  audit: CollectionAuditSchema.optional(),
+
   /** Optional per-collection model overrides */
   models: z
     .object({
@@ -616,7 +687,25 @@ export const ConfigSchema = z.object({
   editorUriTemplate: z.string().min(1).optional(),
 
   /** Collection definitions */
-  collections: z.array(CollectionSchema).default([]),
+  collections: z
+    .array(CollectionSchema)
+    .superRefine((collections, ctx) => {
+      const names = new Set(collections.map(({ name }) => name));
+      for (const [index, collection] of collections.entries()) {
+        for (const [
+          position,
+          name,
+        ] of collection.audit?.linkCollections?.entries() ?? []) {
+          if (names.has(name)) continue;
+          ctx.addIssue({
+            code: "custom",
+            message: `Collection "${collection.name}" audit.linkCollections names unknown collection "${name}"`,
+            path: [index, "audit", "linkCollections", position],
+          });
+        }
+      }
+    })
+    .default([]),
 
   /** Context metadata */
   contexts: z.array(ContextSchema).default([]),