@gmickel/gno 2.12.2 → 2.13.0

package/src/sdk/client.ts

@@ -110,6 +110,7 @@ import {
 import { publishCapture } from "../core/capture-publish";
 import { projectCollectionEgressPolicy } from "../core/collection-egress-policy-projection";
 import { CollectionEgressPolicyService } from "../core/collection-egress-policy-service";
+import { resolveCollectionScope } from "../core/collection-scope";
 import { applyConfigChange } from "../core/config-mutation";
 import { getDocumentCapabilities } from "../core/document-capabilities";
 import { EgressAuditService } from "../core/egress-audit";
@@ -196,7 +197,7 @@ import {
 } from "../llm/inference-scope";
 import { LlmAdapter } from "../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../llm/policy";
-import { resolveModelUri } from "../llm/registry";
+import { modelCollectionForList, resolveModelUri } from "../llm/registry";
 import {
   answerTraceTerminalStatus,
   generateGroundedAnswer,
@@ -476,6 +477,27 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  /** Normalize and validate a search/vsearch/query `collections` allowlist. */
+  private withCollectionScope<
+    T extends { collection?: string; collections?: string[] },
+  >(options: T): T {
+    const scope = resolveCollectionScope(options, this.config.collections);
+    if (!scope.ok) throw sdkError("VALIDATION", scope.message);
+    return scope.collections === undefined
+      ? options
+      : { ...options, collections: scope.collections };
+  }
+
+  private modelCollection(
+    type: "embed" | "expand" | "rerank",
+    options: { collection?: string; collections?: string[] }
+  ): string | undefined {
+    return (
+      options.collection ??
+      modelCollectionForList(this.config, type, options.collections)
+    );
+  }
+
   private getCollections(collection?: string) {
     if (!collection) {
       return this.config.collections;
@@ -541,6 +563,7 @@ class GnoClientImpl implements GnoClient {
     answer?: boolean;
     rerank?: boolean;
     collection?: string;
+    collections?: string[];
     requiredEmbed?: boolean;
     requiredExpand?: boolean;
     requiredAnswer?: boolean;
@@ -551,9 +574,9 @@ class GnoClientImpl implements GnoClient {
     rerankModel?: string;
   }): Promise<RuntimePorts> {
     this.assertOpen();
-    const egressCollections = options.collection
-      ? [options.collection]
-      : ("all" as const);
+    const egressCollections =
+      options.collections ??
+      (options.collection ? [options.collection] : ("all" as const));
 
     let embedPort: EmbeddingPort | null = null;
     let expandPort: GenerationPort | null = null;
@@ -567,7 +590,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "embed",
           options.embedModel,
-          options.collection
+          this.modelCollection("embed", options)
         ),
         {
           egressCollections,
@@ -612,7 +635,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "expand",
           options.expandModel ?? options.genModel,
-          options.collection
+          this.modelCollection("expand", options)
         ),
         {
           egressCollections,
@@ -665,7 +688,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "rerank",
           options.rerankModel,
-          options.collection
+          this.modelCollection("rerank", options)
         ),
         {
           egressCollections,
@@ -735,6 +758,7 @@ class GnoClientImpl implements GnoClient {
     options: GnoSearchOptions
   ): Promise<SearchResults> {
     this.assertOpen();
+    options = this.withCollectionScope(options);
     let traceSession: RetrievalTraceSession | null = null;
     try {
       const { projectHints, ...searchOptions } = options;
@@ -789,6 +813,7 @@ class GnoClientImpl implements GnoClient {
     options: GnoVectorSearchOptions
   ): Promise<SearchResults> {
     this.assertOpen();
+    options = this.withCollectionScope(options);
 
     let ports: RuntimePorts | null = null;
     let traceSession: RetrievalTraceSession | null = null;
@@ -805,7 +830,7 @@ class GnoClientImpl implements GnoClient {
         this.config,
         "embed",
         options.model,
-        options.collection
+        this.modelCollection("embed", options)
       );
       traceSession = unwrapStore(
         await startRetrievalTraceRequest({
@@ -823,6 +848,7 @@ class GnoClientImpl implements GnoClient {
         requiredEmbed: true,
         embedModel: options.model,
         collection: options.collection,
+        collections: options.collections,
       });
       if (!ports.embedPort || !ports.vectorIndex) {
         throw sdkError(
@@ -882,6 +908,7 @@ class GnoClientImpl implements GnoClient {
     options: GnoQueryOptions
   ): Promise<SearchResults> {
     this.assertOpen();
+    options = this.withCollectionScope(options);
 
     const normalizedInput = normalizeStructuredQueryInput(
       query,
@@ -905,14 +932,14 @@ class GnoClientImpl implements GnoClient {
       this.config,
       "embed",
       options.embedModel,
-      options.collection
+      this.modelCollection("embed", options)
     );
     const expandUri = expandRequested
       ? resolveModelUri(
           this.config,
           "expand",
           options.expandModel ?? options.genModel,
-          options.collection
+          this.modelCollection("expand", options)
         )
       : undefined;
     const rerankUri = rerankRequested
@@ -920,7 +947,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "rerank",
           options.rerankModel,
-          options.collection
+          this.modelCollection("rerank", options)
         )
       : undefined;
     let ports: RuntimePorts | null = null;
@@ -956,6 +983,7 @@ class GnoClientImpl implements GnoClient {
         genModel: options.genModel,
         rerankModel: options.rerankModel,
         collection: options.collection,
+        collections: options.collections,
       });
       return attachRetrievalTraceMetadata(
         this.decorateSearchResults(

package/src/sdk/convert.ts

@@ -0,0 +1,27 @@
+/**
+ * SDK conversion of one file to the Markdown GNO would index (no client,
+ * config or index needed).
+ *
+ * @module src/sdk/convert
+ */
+
+import {
+  type ConvertFileResult,
+  convertFile as convertOneFile,
+} from "../ingestion/convert-file";
+import { sdkError } from "./errors";
+
+/**
+ * Convert one file to the Markdown GNO would index for it; nothing is
+ * persisted. Failures throw `GnoSdkError` with `details.reason` set to the
+ * same reason `gno convert` reports.
+ */
+export async function convertFile(path: string): Promise<ConvertFileResult> {
+  const result = await convertOneFile(path);
+  if (result.ok) return result.value;
+  const { reason, message, validation, details } = result.error;
+  let code: "NOT_FOUND" | "VALIDATION" | "RUNTIME" = "RUNTIME";
+  if (reason === "NOT_FOUND") code = "NOT_FOUND";
+  else if (validation) code = "VALIDATION";
+  throw sdkError(code, message, { details: { reason, ...details } });
+}

package/src/sdk/index.ts

@@ -27,6 +27,8 @@ export type { IndexStatus } from "../store/types";
 
 export { GnoSdkError, sdkError } from "./errors";
 export { createGnoClient } from "./client";
+export { convertFile } from "./convert";
+export type { ConvertFileResult } from "../ingestion/convert-file";
 export type {
   DocumentSection,
   GnoAskOptions,

package/src/sdk/types.ts

@@ -179,7 +179,7 @@ export type GnoQueryOptions = Omit<
   GnoProjectHintOptions;
 export type GnoAskOptions = Omit<
   AskOptions,
-  "contentTypeRules" | "projectAffinity"
+  "collections" | "contentTypeRules" | "projectAffinity"
 > &
   GnoModelOverrides &
   GnoProjectHintOptions;

package/src/serve/jobs.ts

@@ -16,11 +16,13 @@ export interface JobProgress {
 export interface JobStatus {
   id: string;
   type: JobType;
-  status: "running" | "completed" | "failed";
+  status: "queued" | "running" | "completed" | "failed";
   createdAt: number;
   progress?: JobProgress;
   result?: SyncResult;
   error?: string;
+  /** Reindex jobs: the collection (null = all) and merged paths (null = whole). */
+  scope?: JobRecord["scope"];
 }
 
 export interface StartJobSuccess {
@@ -49,6 +51,7 @@ const fromResidentRecord = (record: JobRecord): JobStatus => ({
   progress: record.progress,
   result: record.result,
   error: record.error,
+  ...(record.scope ? { scope: record.scope } : {}),
 });
 
 function cleanupExpiredJobs(now = Date.now()): void {

package/src/serve/public/components/IndexingProgress.tsx

@@ -24,7 +24,7 @@ import { Badge } from "./ui/badge";
 export interface JobStatus {
   id: string;
   type: "add" | "sync";
-  status: "running" | "completed" | "failed";
+  status: "queued" | "running" | "completed" | "failed";
   createdAt: number;
   result?: SyncResult;
   error?: string;
@@ -138,7 +138,7 @@ export function IndexingProgress({
       setStatus(data);
       setFetchError(null);
 
-      if (data.status === "running") {
+      if (data.status === "queued" || data.status === "running") {
         pollTimeout = setTimeout(() => {
           void poll();
         }, 1000);
@@ -187,6 +187,20 @@ export function IndexingProgress({
 
   // Compact mode
   if (compact) {
+    if (status?.status === "queued") {
+      return (
+        <div
+          aria-live="polite"
+          className={cn("flex items-center gap-2 text-sm", className)}
+        >
+          <Loader2Icon className="size-4 animate-spin text-muted-foreground" />
+          <span className="text-muted-foreground">
+            Queued... {formatElapsed(elapsed)}
+          </span>
+        </div>
+      );
+    }
+
     if (status?.status === "running") {
       return (
         <div
@@ -237,6 +251,14 @@ export function IndexingProgress({
       {/* Status header */}
       <div className="flex items-center justify-between">
         <div className="flex items-center gap-2">
+          {status?.status === "queued" && (
+            <>
+              <Loader2Icon className="size-5 animate-spin text-muted-foreground" />
+              <span className="font-medium">
+                Queued behind another indexing job
+              </span>
+            </>
+          )}
           {status?.status === "running" && (
             <>
               <Loader2Icon className="size-5 animate-spin text-primary" />
@@ -264,7 +286,7 @@ export function IndexingProgress({
         <div className="flex items-center gap-1.5 text-muted-foreground text-sm">
           <TimerIcon className="size-4" />
           <span>
-            {status?.status === "running"
+            {status?.status === "queued" || status?.status === "running"
               ? formatElapsed(elapsed)
               : formatDuration(status?.result?.totalDurationMs ?? elapsed)}
           </span>

package/src/serve/routes/api.ts

@@ -16,7 +16,6 @@ import type {
   EgressPolicy,
   ModelPreset,
 } from "../../config/types";
-import type { JobManager } from "../../core/job-manager";
 import type { ProjectAffinityScoringInput } from "../../pipeline/project-affinity";
 import type {
   AskResult,
@@ -57,6 +56,7 @@ import {
   type EgressRelaxationConfirmation,
 } from "../../core/collection-egress-policy-service";
 import { parsePolicySetBody } from "../../core/collection-egress-policy-validation";
+import { resolveCollectionScope } from "../../core/collection-scope";
 import {
   type ConnectorVerificationCode,
   getConnectorVerificationRemediation,
@@ -82,6 +82,7 @@ import {
   planCreateFolder,
   planDuplicateRefactor,
 } from "../../core/file-refactors";
+import { JobError, type JobManager } from "../../core/job-manager";
 import {
   MemoryError,
   type MemoryErrorCode,
@@ -111,6 +112,7 @@ import {
   resolveRemoteProjectAffinity,
 } from "../../core/project-affinity-surface";
 import { projectRecordEvidenceMetadata } from "../../core/record-metadata";
+import { resolveReindexScope } from "../../core/reindex-paths";
 import {
   isLeaseBusy,
   localRequestLedger,
@@ -303,6 +305,8 @@ export interface SearchRequestBody {
   limit?: number;
   minScore?: number;
   collection?: string;
+  /** Collection allowlist (1-256 names); not combined with `collection`. */
+  collections?: string[];
   intent?: string;
   exclude?: string;
   since?: string;
@@ -323,6 +327,8 @@ export interface QueryRequestBody {
   limit?: number;
   minScore?: number;
   collection?: string;
+  /** Collection allowlist (1-256 names); not combined with `collection`. */
+  collections?: string[];
   lang?: string;
   intent?: string;
   candidateLimit?: number;
@@ -496,6 +502,7 @@ export interface ImportPreviewRequestBody {
 export interface SyncRequestBody {
   collection?: string;
   gitPull?: boolean;
+  paths?: string[];
 }
 
 export interface CreateDocRequestBody {
@@ -651,6 +658,42 @@ function parseRestMetadataFilter(
   return { ok: true, filter: normalizeMetadataPredicate(parsed.data) };
 }
 
+/**
+ * Resolve a search/query `collections` allowlist: 400 VALIDATION for malformed
+ * input or `collection` with `collections`, 404 NOT_FOUND for unknown names.
+ */
+async function parseRestCollectionScope(
+  body: { collection?: unknown; collections?: unknown },
+  configured: readonly { name: string }[] | null,
+  store: SqliteAdapter
+): Promise<
+  | { ok: true; collections: string[] | undefined }
+  | { ok: false; response: Response }
+> {
+  if (body.collections === undefined)
+    return { ok: true, collections: undefined };
+  let names = configured;
+  if (!names) {
+    const stored = await store.getCollections();
+    if (!stored.ok) {
+      return {
+        ok: false,
+        response: errorResponse("RUNTIME", stored.error.message, 500),
+      };
+    }
+    names = stored.value;
+  }
+  const scope = resolveCollectionScope(body, names);
+  if (scope.ok) return { ok: true, collections: scope.collections };
+  return {
+    ok: false,
+    response:
+      scope.kind === "validation"
+        ? errorResponse("VALIDATION", scope.message)
+        : errorResponse("NOT_FOUND", scope.message, 404),
+  };
+}
+
 function fileRefactorHttpErrorResponse(error: FileRefactorHttpError): Response {
   return errorResponse(error.code, error.message, error.status, error.details);
 }
@@ -1780,6 +1823,9 @@ export async function handleSync(
   if (body.gitPull !== undefined && typeof body.gitPull !== "boolean") {
     return errorResponse("VALIDATION", "gitPull must be a boolean");
   }
+  if (body.paths !== undefined && !Array.isArray(body.paths)) {
+    return errorResponse("VALIDATION", "paths must be an array of strings");
+  }
 
   // Get collections to sync (case-insensitive matching)
   const collectionName = body.collection?.toLowerCase();
@@ -1801,31 +1847,95 @@ export async function handleSync(
     return errorResponse("VALIDATION", "No collections to sync");
   }
 
-  // Start background sync job
-  const jobResult = await startJob(
-    "sync",
-    async (): Promise<SyncResult> => {
-      const result = await defaultSyncService.syncAll(
-        collections,
-        store,
-        withContentTypeRules(
-          {
-            gitPull: body.gitPull,
-            runUpdateCmd: true,
-          },
-          ctxHolder.config
-        )
-      );
-      recordContentMutation(result, ctxHolder.markContentMutation);
-      if (hasContentMutation(result)) {
-        if (ctxHolder.scheduler) {
-          await ctxHolder.scheduler.triggerNow();
-        }
-      }
-      return result;
+  const options = withContentTypeRules(
+    {
+      gitPull: body.gitPull,
+      runUpdateCmd: true,
     },
-    ctxHolder.jobManager
+    ctxHolder.config
   );
+  let paths: string[] | null;
+  try {
+    // A path-level sync runs no update command; only git pull conflicts.
+    paths = await resolveReindexScope(
+      body.collection ? (collections[0] ?? null) : null,
+      body.paths,
+      { gitPull: body.gitPull }
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const separator = message.indexOf(": ");
+    const code = separator > 0 ? message.slice(0, separator) : "";
+    return errorResponse(
+      code === "INVALID_PATH" ? "INVALID_PATH" : "VALIDATION",
+      separator > 0 ? message.slice(separator + 2) : message
+    );
+  }
+
+  // Captured now: a queued pass runs after this request's context is gone.
+  const config = ctxHolder.config;
+  const runSync = async (
+    scopedPaths: string[] | null,
+    passOptions: { gitPull?: boolean; runUpdateCmd?: boolean }
+  ): Promise<SyncResult> => {
+    const collection = collections[0];
+    const result =
+      scopedPaths && collection
+        ? wrapCollectionSync(
+            await defaultSyncService.syncPaths(
+              collection,
+              store,
+              scopedPaths,
+              withContentTypeRules({}, config)
+            )
+          )
+        : await defaultSyncService.syncAll(
+            collections,
+            store,
+            withContentTypeRules({ ...passOptions }, config)
+          );
+    recordContentMutation(result, ctxHolder.markContentMutation);
+    if (hasContentMutation(result)) {
+      if (ctxHolder.scheduler) {
+        await ctxHolder.scheduler.triggerNow();
+      }
+    }
+    return result;
+  };
+
+  const manager = ctxHolder.jobManager;
+  if (manager) {
+    try {
+      const accepted = await manager.submitReindex({
+        type: "sync",
+        collection: body.collection ? (collections[0]?.name ?? null) : null,
+        paths,
+        // A whole sync over REST always runs the collection's update command.
+        options: { gitPull: body.gitPull ?? false, runUpdateCmd: true },
+        run: async (scope) => ({
+          kind: "sync",
+          value: await runSync(scope.paths, scope.options),
+        }),
+      });
+      return jsonResponse(
+        { jobId: accepted.jobId, status: accepted.status },
+        202
+      );
+    } catch (error) {
+      if (error instanceof JobError && error.code === "QUEUE_FULL") {
+        return errorResponse("QUEUE_FULL", error.message, 429);
+      }
+      if (error instanceof JobError) {
+        return errorResponse("CONFLICT", error.message, 409, {
+          activeJobId: manager.getActiveJob()?.id ?? "",
+        });
+      }
+      throw error;
+    }
+  }
+
+  // Standalone fallback (unit fixtures without a resident job manager).
+  const jobResult = startJob("sync", () => runSync(paths, options));
 
   if (!jobResult.ok) {
     return jobConflictResponse(jobResult);
@@ -1834,6 +1944,20 @@ export async function handleSync(
   return jsonResponse({ jobId: jobResult.jobId }, 202);
 }
 
+function wrapCollectionSync(
+  result: Awaited<ReturnType<typeof defaultSyncService.syncPaths>>
+): SyncResult {
+  return {
+    collections: [result],
+    totalDurationMs: result.durationMs,
+    totalFilesProcessed: result.filesProcessed,
+    totalFilesAdded: result.filesAdded,
+    totalFilesUpdated: result.filesUpdated,
+    totalFilesErrored: result.filesErrored,
+    totalFilesSkipped: result.filesSkipped,
+  };
+}
+
 /**
  * GET /api/docs
  * Query params: collection, limit (default 20), offset (default 0), tagsAll, tagsAny
@@ -4587,6 +4711,13 @@ export async function handleSearch(
   const parsedFilter = parseRestMetadataFilter(body.filter);
   if (!parsedFilter.ok) return parsedFilter.response;
   const filter = parsedFilter.filter;
+  const collectionScope = await parseRestCollectionScope(
+    body,
+    context?.config.collections ?? null,
+    store
+  );
+  if (!collectionScope.ok) return collectionScope.response;
+  const { collections } = collectionScope;
   let projectAffinity: ProjectAffinityScoringInput | undefined;
   try {
     projectAffinity = context
@@ -4606,6 +4737,7 @@ export async function handleSearch(
     limit: Math.min(body.limit || 10, 50),
     minScore: body.minScore,
     collection: body.collection,
+    collections,
     intent: body.intent?.trim() || undefined,
     exclude,
     tagsAll,
@@ -4785,6 +4917,13 @@ export async function handleQuery(
   const parsedFilter = parseRestMetadataFilter(body.filter);
   if (!parsedFilter.ok) return parsedFilter.response;
   const filter = parsedFilter.filter;
+  const collectionScope = await parseRestCollectionScope(
+    body,
+    ctx.config.collections,
+    ctx.store
+  );
+  if (!collectionScope.ok) return collectionScope.response;
+  const { collections } = collectionScope;
   let projectAffinity: ProjectAffinityScoringInput | undefined;
   try {
     projectAffinity = await resolveRemoteProjectAffinity(
@@ -4804,6 +4943,7 @@ export async function handleQuery(
     limit: Math.min(body.limit ?? 20, 50),
     minScore: body.minScore,
     collection: body.collection,
+    collections,
     lang: body.lang,
     intent: body.intent?.trim() || undefined,
     candidateLimit: