@gmickel/gno 2.3.3 → 2.5.1

package/src/app/context-runtime.ts

@@ -63,6 +63,7 @@ export const buildContextCapsule = async (
     deps.config.collections.map((collection) => collection.name)
   );
   const noRerank = normalized.depthPolicy === "fast" || normalized.noRerank;
+  let metadataCoverageIncomplete = false;
   const plan = await compileContextEvidence<ContextCapsuleV1>(
     {
       goal: normalized.goal,
@@ -74,6 +75,7 @@ export const buildContextCapsule = async (
       tagsAll: normalized.tagsAll,
       tagsAny: normalized.tagsAny,
       categories: normalized.categories,
+      filter: normalized.filter,
       author: normalized.author ?? undefined,
       lang: normalized.lang ?? undefined,
       intent: normalized.intent ?? undefined,
@@ -104,8 +106,14 @@ export const buildContextCapsule = async (
             store: deps.store,
             hydration: deps.hydration,
             config: deps.config,
-            vectorIndex: deps.vectorIndex ?? null,
-            embedPort: deps.embedPort ?? null,
+            vectorIndex:
+              normalized.depthPolicy === "fast"
+                ? null
+                : (deps.vectorIndex ?? null),
+            embedPort:
+              normalized.depthPolicy === "fast"
+                ? null
+                : (deps.embedPort ?? null),
             expandPort: null,
             rerankPort: requestNoRerank ? null : (deps.rerankPort ?? null),
           },
@@ -124,10 +132,26 @@ export const buildContextCapsule = async (
             result.error.cause
           );
         }
+        if (
+          normalized.filter &&
+          result.value.meta.warnings?.some(
+            (warning) =>
+              warning.code === "METADATA_COVERAGE_UNKNOWN" ||
+              warning.code === "METADATA_COVERAGE_INCOMPLETE"
+          )
+        ) {
+          metadataCoverageIncomplete = true;
+        }
         return result.value;
       },
       projectCanonical: (draft, snapshots) =>
-        projectContextCapsule(draft, snapshots, normalized, deps),
+        projectContextCapsule(
+          draft,
+          snapshots,
+          normalized,
+          deps,
+          metadataCoverageIncomplete
+        ),
     }
   );
   if (!plan.projection) {

package/src/app/context-surface.ts

@@ -5,6 +5,10 @@ import { z } from "zod";
 import type { ContextCapsuleBuildInput } from "./context-runtime-types";
 
 import { ContextCapsuleContractError } from "../core/context-capsule";
+import {
+  metadataPredicateSchema,
+  METADATA_FILTER_DESCRIPTION,
+} from "../core/typed-metadata";
 
 const queryModeSchema = z
   .object({
@@ -28,6 +32,9 @@ export const contextBuildSurfaceSchema = z
     tagsAll: stringList.optional(),
     tagsAny: stringList.optional(),
     categories: stringList.optional(),
+    filter: metadataPredicateSchema
+      .optional()
+      .describe(METADATA_FILTER_DESCRIPTION),
     author: z.string().optional(),
     lang: z.string().optional(),
     intent: z.string().optional(),

package/src/app/verified-ask.ts

@@ -184,6 +184,7 @@ export const buildVerifiedAsk = async (
       tagsAll: options.tagsAll,
       tagsAny: options.tagsAny,
       categories: options.categories,
+      filter: options.filter,
       author: options.author,
       lang: options.lang,
       intent: options.intent,

package/src/cli/commands/ask.ts

@@ -323,6 +323,7 @@ export async function ask(
       until: options.until,
       categories: options.categories,
       author: options.author,
+      filter: options.filter,
       tagsAll: options.tagsAll,
       tagsAny: options.tagsAny,
       exclude: options.exclude,

package/src/cli/commands/audit.ts

@@ -21,6 +21,7 @@ import {
 import { runWorkspaceAudit } from "../../core/audit-workspace";
 import { normalizeTag, validateTag } from "../../core/tags";
 import { normalizeCollectionName } from "../../core/validation";
+import { windowsPrivatePath } from "../../core/windows-private-path";
 import { SqliteAdapter } from "../../store/sqlite/adapter";
 
 export interface AuditCommandOptions {
@@ -218,12 +219,15 @@ export const writeAuditReport = async (
   );
   const temporaryPath = join(temporaryDirectory, "report");
   try {
+    if (process.platform === "win32")
+      await windowsPrivatePath(temporaryDirectory, true);
     await Bun.write(temporaryPath, `${formatAuditReport(report, options)}\n`, {
       createPath: false,
       mode: 0o600,
     });
     await chmod(temporaryPath, 0o600);
     await rename(temporaryPath, path);
+    if (process.platform === "win32") await windowsPrivatePath(path);
   } finally {
     await unlink(temporaryPath).catch(() => undefined);
     await rmdir(temporaryDirectory).catch(() => undefined);

package/src/cli/commands/context-build.ts

@@ -124,6 +124,7 @@ export const contextBuild = async (
         until: options.until,
         categories: options.categories,
         author: options.author,
+        filter: options.filter,
         graph: options.graph,
         candidateLimit: options.candidateLimit,
         queryModes: options.queryModes,

package/src/cli/commands/context-compiled.ts

@@ -0,0 +1,136 @@
+import { previewCompiledContext } from "../../app/compiled-context";
+import {
+  compileContextFile,
+  checkContextFile,
+  refreshContextFile,
+} from "../../app/compiled-context-files";
+/** Explicit local compiled context operations. */
+import { createGnoClient } from "../../sdk/client";
+import { CliError } from "../errors";
+import { contextCliError } from "./context-build";
+import { initStore } from "./shared";
+
+export interface CompiledCommandOptions {
+  configPath?: string;
+  indexName?: string;
+  capsulePath?: string;
+  capsuleOutputPath?: string;
+  outputPath?: string;
+  budgetTokens?: number;
+  budgetBytes?: number;
+  json?: boolean;
+}
+
+export async function contextCompiled(
+  operation: "preview" | "compile" | "check" | "refresh",
+  options: CompiledCommandOptions
+): Promise<{
+  output: string;
+  status?: "current" | "stale" | "conflict" | "unverifiable";
+}> {
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) throw new CliError("RUNTIME", initialized.error);
+  const deps = {
+    store: initialized.store,
+    config: initialized.config,
+    indexName: options.indexName,
+  };
+  try {
+    if (operation === "check") {
+      if (!options.outputPath)
+        throw new CliError("VALIDATION", "Artifact path required");
+      const result = await checkContextFile(
+        { outputPath: options.outputPath, capsulePath: options.capsulePath },
+        deps
+      );
+      return {
+        output: options.json
+          ? JSON.stringify(result)
+          : `${result.status}: ${result.reasons.join("; ") || "verified current"}`,
+        status: result.status,
+      };
+    }
+    if (operation === "refresh") {
+      if (!options.outputPath || !options.capsuleOutputPath)
+        throw new CliError(
+          "VALIDATION",
+          "Artifact and Capsule output paths required"
+        );
+      const result = await refreshContextFile(
+        {
+          outputPath: options.outputPath,
+          capsuleOutputPath: options.capsuleOutputPath,
+        },
+        deps,
+        async (request) => {
+          const client = await createGnoClient({
+            configPath: options.configPath,
+            indexName: options.indexName,
+          });
+          try {
+            return await client.context(request);
+          } finally {
+            await client.close();
+          }
+        }
+      );
+      return {
+        output: options.json
+          ? JSON.stringify(result)
+          : `${result.status}: ${result.outputPath}`,
+      };
+    }
+    if (!options.capsulePath || !options.budgetTokens)
+      throw new CliError("VALIDATION", "Capsule path and budget required");
+    if (operation === "compile") {
+      if (!options.outputPath)
+        throw new CliError("VALIDATION", "Output path required");
+      const result = await compileContextFile(
+        {
+          capsulePath: options.capsulePath,
+          outputPath: options.outputPath,
+          budgetTokens: options.budgetTokens,
+          budgetBytes: options.budgetBytes,
+        },
+        deps
+      );
+      return {
+        output: options.json
+          ? JSON.stringify(result)
+          : `${result.status}: ${result.outputPath}`,
+      };
+    }
+    const source = Bun.file(options.capsulePath);
+    if (source.size > 4 * 1024 * 1024)
+      throw new CliError("VALIDATION", "Capsule exceeds byte limit");
+    const capsule: unknown = await source.json();
+    const result = await previewCompiledContext(
+      {
+        capsule,
+        budgetTokens: options.budgetTokens,
+        budgetBytes: options.budgetBytes,
+      },
+      deps
+    );
+    return { output: options.json ? JSON.stringify(result) : result.markdown };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    if (
+      error instanceof SyntaxError ||
+      (error instanceof Error && error.name === "ZodError")
+    ) {
+      throw new CliError(
+        "VALIDATION",
+        "Invalid compiled context input; provide a valid Capsule and budget"
+      );
+    }
+    throw contextCliError(error);
+  } finally {
+    await initialized.store.close();
+  }
+}

package/src/cli/commands/search.ts

@@ -113,6 +113,7 @@ export async function search(
         until: options.until,
         categories: options.categories,
         author: options.author,
+        filter: options.filter,
         intent: options.intent,
         exclude: options.exclude,
       },

package/src/cli/commands/status.ts

@@ -87,6 +87,11 @@ function formatTerminal(
 ): string {
   const lines: string[] = [];
 
+  if (indexStatus.typedMetadata) {
+    lines.push(
+      `Typed metadata: ${indexStatus.typedMetadata.pending} pending sync, ${indexStatus.typedMetadata.invalid} invalid`
+    );
+  }
   lines.push(`Index: ${indexStatus.indexName}`);
   lines.push(`Config: ${indexStatus.configPath}`);
   lines.push(`Database: ${indexStatus.dbPath}`);
@@ -200,6 +205,10 @@ function formatMarkdown(
   lines.push(`- **Documents**: ${indexStatus.activeDocuments}`);
   lines.push(`- **Chunks**: ${indexStatus.totalChunks}`);
   lines.push(`- **Embedding backlog**: ${indexStatus.embeddingBacklog}`);
+  if (indexStatus.typedMetadata)
+    lines.push(
+      `- **Typed metadata**: ${indexStatus.typedMetadata.pending} pending sync, ${indexStatus.typedMetadata.invalid} invalid`
+    );
   lines.push(`- **Recent errors**: ${indexStatus.recentErrors}`);
 
   const chunking = formatChunkingStatus(indexStatus.chunking);
@@ -347,6 +356,7 @@ export function formatStatus(
         totalDocuments: s.activeDocuments,
         totalChunks: s.totalChunks,
         embeddingBacklog: s.embeddingBacklog,
+        typedMetadata: s.typedMetadata,
         chunking: s.chunking,
         lastUpdated: s.lastUpdatedAt,
         healthy: isStatusHealthy(s, result.activation),

package/src/cli/errors.ts

@@ -15,7 +15,9 @@ export type CliErrorCode =
   | "NOT_RUNNING"
   | "BUSY"
   | "AUDIT_FINDINGS"
-  | "AUDIT_PARTIAL";
+  | "AUDIT_PARTIAL"
+  | "CONTEXT_STALE"
+  | "CONTEXT_CONFLICT";
 
 export interface CliErrorOptions {
   details?: Record<string, unknown>;
@@ -72,10 +74,15 @@ export function exitCodeFor(err: CliError): 1 | 2 | 3 | 4 | 5 {
   if (err.code === "VALIDATION") {
     return 1;
   }
-  if (err.code === "NOT_RUNNING") {
+  if (err.code === "NOT_RUNNING" || err.code === "CONTEXT_STALE") {
     return 3;
   }
-  if (err.code === "BUSY" || err.code === "AUDIT_FINDINGS") return 4;
+  if (
+    err.code === "BUSY" ||
+    err.code === "AUDIT_FINDINGS" ||
+    err.code === "CONTEXT_CONFLICT"
+  )
+    return 4;
   if (err.code === "AUDIT_PARTIAL") return 5;
   return 2;
 }

package/src/cli/options.ts

@@ -9,6 +9,10 @@ import {
   normalizeProjectAffinityValues,
   ProjectAffinityInputError,
 } from "../core/project-affinity-surface";
+import {
+  normalizeMetadataPredicate,
+  type MetadataPredicate,
+} from "../core/typed-metadata";
 import { CliError } from "./errors";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -259,3 +263,18 @@ export function parseOptionalFloat(
   }
   return num;
 }
+
+export const parseCliMetadataFilter = (
+  value: unknown
+): MetadataPredicate | undefined => {
+  if (value === undefined) return undefined;
+  try {
+    if (typeof value !== "string") throw new Error("Expected JSON text");
+    return normalizeMetadataPredicate(JSON.parse(value));
+  } catch (error) {
+    throw new CliError(
+      "VALIDATION",
+      `filter: ${error instanceof Error ? error.message : "Invalid predicate"}`
+    );
+  }
+};

package/src/cli/program.ts

@@ -49,6 +49,7 @@ import {
   collectRepeatableValue,
   getDefaultLimit,
   parseCliProjectAffinityOptions,
+  parseCliMetadataFilter,
   parseOptionalFloat,
   parsePositiveInt,
 } from "./options";
@@ -652,6 +653,7 @@ function wireSearchCommands(program: Command): void {
       "modified-at upper bound (ISO date/time or token)"
     )
     .option("--category <values>", "require category match (comma-separated)")
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
     .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option(
@@ -736,6 +738,7 @@ function wireSearchCommands(program: Command): void {
           until: cmdOpts.until as string | undefined,
           categories,
           author: cmdOpts.author as string | undefined,
+          filter: parseCliMetadataFilter(cmdOpts.filter),
           intent: cmdOpts.intent as string | undefined,
           exclude,
           tagsAll,
@@ -790,6 +793,7 @@ function wireSearchCommands(program: Command): void {
       "modified-at upper bound (ISO date/time or token)"
     )
     .option("--category <values>", "require category match (comma-separated)")
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
     .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option(
@@ -864,6 +868,7 @@ function wireSearchCommands(program: Command): void {
         until: cmdOpts.until as string | undefined,
         categories,
         author: cmdOpts.author as string | undefined,
+        filter: parseCliMetadataFilter(cmdOpts.filter),
         intent: cmdOpts.intent as string | undefined,
         exclude,
         tagsAll,
@@ -916,6 +921,7 @@ function wireSearchCommands(program: Command): void {
       "modified-at upper bound (ISO date/time or token)"
     )
     .option("--category <values>", "require category match (comma-separated)")
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
     .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option(
@@ -1080,6 +1086,7 @@ function wireSearchCommands(program: Command): void {
             until: cmdOpts.until as string | undefined,
             categories,
             author: cmdOpts.author as string | undefined,
+            filter: parseCliMetadataFilter(cmdOpts.filter),
             intent: cmdOpts.intent as string | undefined,
             exclude,
             tagsAll,
@@ -1116,6 +1123,7 @@ function wireSearchCommands(program: Command): void {
           until: cmdOpts.until as string | undefined,
           categories,
           author: cmdOpts.author as string | undefined,
+          filter: parseCliMetadataFilter(cmdOpts.filter),
           intent: cmdOpts.intent as string | undefined,
           exclude,
           tagsAll,
@@ -1219,6 +1227,7 @@ function wireSearchCommands(program: Command): void {
       "modified-at upper bound (ISO date/time or token)"
     )
     .option("--category <values>", "require category match (comma-separated)")
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
     .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option(
@@ -1350,6 +1359,7 @@ function wireSearchCommands(program: Command): void {
         until: cmdOpts.until as string | undefined,
         categories,
         author: cmdOpts.author as string | undefined,
+        filter: parseCliMetadataFilter(cmdOpts.filter),
         intent: cmdOpts.intent as string | undefined,
         exclude,
         minScore,
@@ -2695,6 +2705,7 @@ function wireManagementCommands(program: Command): void {
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
     .option("--category <values>", "require category match (comma-separated)")
+    .option("--filter <json>", "typed custom metadata predicate (JSON)")
     .option("--author <text>", "filter by author")
     .option("--lang <code>", "language hint (BCP-47)")
     .option("--since <date>", "modified-at lower bound")
@@ -2765,6 +2776,7 @@ function wireManagementCommands(program: Command): void {
         tagsAny: parseCsvValues(cmdOpts.tagsAny),
         categories: parseCsvValues(cmdOpts.category),
         author: cmdOpts.author as string | undefined,
+        filter: parseCliMetadataFilter(cmdOpts.filter),
         lang: cmdOpts.lang as string | undefined,
         since: cmdOpts.since as string | undefined,
         until: cmdOpts.until as string | undefined,
@@ -2791,6 +2803,76 @@ function wireManagementCommands(program: Command): void {
       await writeOutput(output, format === "json" ? "json" : "md");
     });
 
+  const compiledCmd = contextCmd
+    .command("compiled")
+    .description("Compile, check and refresh verified project context");
+  for (const operation of ["preview", "compile", "check", "refresh"] as const) {
+    const command = compiledCmd
+      .command(
+        operation === "check" || operation === "refresh"
+          ? `${operation} <file>`
+          : operation
+      )
+      .description(`${operation} a separate managed context artifact`)
+      .option("--json", "JSON output");
+    if (operation === "preview" || operation === "compile") {
+      command
+        .requiredOption("--capsule <file>", "explicit Capsule JSON file")
+        .requiredOption("--budget <tokens>", "whole-output token budget")
+        .option("--bytes <bytes>", "whole-output byte budget");
+    }
+    if (operation === "compile")
+      command.requiredOption(
+        "--output <file>",
+        "new *.gno-context.md artifact"
+      );
+    if (operation === "check")
+      command.option("--capsule <file>", "relocated Capsule JSON file");
+    if (operation === "refresh")
+      command.requiredOption(
+        "--capsule-output <file>",
+        "explicit refreshed Capsule destination"
+      );
+    command.action(async (...args: unknown[]) => {
+      const file =
+        operation === "check" || operation === "refresh"
+          ? (args[0] as string)
+          : undefined;
+      const opts = args[file === undefined ? 0 : 1] as Record<string, unknown>;
+      const globals = getGlobals();
+      const { contextCompiled } = await import("./commands/context-compiled");
+      const result = await contextCompiled(operation, {
+        configPath: globals.config,
+        indexName: globals.index,
+        capsulePath: opts.capsule as string | undefined,
+        capsuleOutputPath: opts.capsuleOutput as string | undefined,
+        outputPath: file ?? (opts.output as string | undefined),
+        budgetTokens:
+          opts.budget === undefined
+            ? undefined
+            : parseContextInteger("budget", opts.budget),
+        budgetBytes:
+          opts.bytes === undefined
+            ? undefined
+            : parseContextInteger("bytes", opts.bytes),
+        json: Boolean(opts.json || globals.json),
+      });
+      await writeOutput(
+        result.output,
+        opts.json || globals.json ? "json" : "terminal"
+      );
+      if (result.status && result.status !== "current") {
+        const code =
+          result.status === "stale"
+            ? "CONTEXT_STALE"
+            : result.status === "conflict"
+              ? "CONTEXT_CONFLICT"
+              : "RUNTIME";
+        throw new CliError(code, result.status, { silent: true });
+      }
+    });
+  }
+
   contextCmd
     .command("verify <file>")
     .description("Verify a saved Context Capsule without rebuilding it")

package/src/converters/types.ts

@@ -1,3 +1,4 @@
+import type { TypedMetadata } from "../core/typed-metadata";
 /**
  * Converter subsystem types.
  * PRD §8.2 - Converter interfaces
@@ -157,6 +158,7 @@ export const RECORD_METADATA_LIMITS = {
 
 /** Metadata shared by export adapters and later search/get projections. */
 export interface RecordMetadata {
+  custom?: TypedMetadata;
   author?: string;
   participants?: string[];
   categories?: string[];