@gmickel/gno 1.16.0 → 1.18.0

package/src/cli/options.ts

@@ -33,6 +33,8 @@ export const CMD = {
   collectionList: "collection.list",
   contextList: "context.list",
   contextCheck: "context.check",
+  contextBuild: "context.build",
+  contextVerify: "context.verify",
   modelsList: "models.list",
   tagsList: "tags.list",
   linksList: "links.list",
@@ -60,6 +62,8 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.collectionList]: ["terminal", "json", "md"],
   [CMD.contextList]: ["terminal", "json", "md"],
   [CMD.contextCheck]: ["terminal", "json", "md"],
+  [CMD.contextBuild]: ["terminal", "json", "md"],
+  [CMD.contextVerify]: ["terminal", "json", "md"],
   [CMD.modelsList]: ["terminal", "json"],
   [CMD.tagsList]: ["terminal", "json", "md"],
   [CMD.linksList]: ["terminal", "json", "md"],

package/src/cli/program.ts

@@ -210,6 +210,42 @@ function parseCsvValues(raw: unknown): string[] | undefined {
   return values.length > 0 ? values : undefined;
 }
 
+function parseContextInteger(
+  name: string,
+  value: unknown,
+  allowZero = false
+): number {
+  const raw = typeof value === "string" ? value : String(value);
+  if (!/^\d+$/.test(raw)) {
+    throw new CliError("VALIDATION", `--${name} must be an integer`, {
+      details: { contextCode: "invalid_budget" },
+    });
+  }
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed) || (allowZero ? parsed < 0 : parsed < 1)) {
+    throw new CliError(
+      "VALIDATION",
+      `--${name} must be ${allowZero ? "non-negative" : "positive"}`,
+      { details: { contextCode: "invalid_budget" } }
+    );
+  }
+  return parsed;
+}
+
+function validateContextOutputPath(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim() || value === "-") {
+    throw new CliError(
+      "VALIDATION",
+      "--output requires an explicit file path",
+      {
+        details: { contextCode: "invalid_filter" },
+      }
+    );
+  }
+  return value;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Program Factory
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1624,6 +1660,148 @@ function wireManagementCommands(program: Command): void {
       await contextCheck(format as "terminal" | "json" | "md");
     });
 
+  contextCmd
+    .command("build <goal...>")
+    .description("Build a deterministic evidence Capsule")
+    .requiredOption("--budget <tokens>", "global token budget")
+    .option("--bytes <bytes>", "global byte budget")
+    .option("--query <query>", "retrieval query (defaults to goal)")
+    .option(
+      "--query-mode <mode:text>",
+      "structured mode entry (repeatable): term:<text>, intent:<text>, or hyde:<text>",
+      (value: string, previous: string[] = []) => [...previous, value],
+      []
+    )
+    .option(
+      "-c, --collection <name>",
+      "collection filter (repeatable)",
+      (value: string, previous: string[] = []) => [...previous, value],
+      []
+    )
+    .option("--uri-prefix <uri>", "canonical GNO URI prefix")
+    .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("--author <text>", "filter by author")
+    .option("--lang <code>", "language hint (BCP-47)")
+    .option("--since <date>", "modified-at lower bound")
+    .option("--until <date>", "modified-at upper bound")
+    .option("--graph", "enable graph neighbor expansion")
+    .option("--fast", "use lexical-first fast retrieval")
+    .option("--thorough", "use a wider retrieval pool")
+    .option("-n, --limit <num>", "maximum retrieved results")
+    .option("-C, --candidate-limit <num>", "maximum rerank candidates")
+    .option("--safety-margin <tokens>", "reserved token margin", "0")
+    .option("--safety-margin-bytes <bytes>", "reserved byte margin", "0")
+    .option("--output <path>", "write only to this explicit file")
+    .option("--json", "canonical JSON output")
+    .option("--md", "readable Markdown output")
+    .action(async (goalParts: string[], cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.contextBuild, format);
+      const outputPath = validateContextOutputPath(cmdOpts.output);
+      if (cmdOpts.fast && cmdOpts.thorough) {
+        throw new CliError("VALIDATION", "Choose either --fast or --thorough");
+      }
+      const globals = getGlobals();
+      const { contextBuild } = await import("./commands/context-build");
+      let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
+      if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
+        const { parseQueryModeSpecs } = await import("../pipeline/query-modes");
+        const parsed = parseQueryModeSpecs(cmdOpts.queryMode as string[]);
+        if (!parsed.ok) {
+          throw new CliError("VALIDATION", parsed.error.message, {
+            details: { contextCode: "invalid_filter" },
+          });
+        }
+        queryModes = parsed.value;
+      }
+      const output = await contextBuild(goalParts.join(" "), {
+        configPath: globals.config,
+        indexName: globals.index,
+        budgetTokens: parseContextInteger("budget", cmdOpts.budget),
+        budgetBytes:
+          cmdOpts.bytes === undefined
+            ? undefined
+            : parseContextInteger("bytes", cmdOpts.bytes),
+        safetyMarginTokens: parseContextInteger(
+          "safety-margin",
+          cmdOpts.safetyMargin ?? "0",
+          true
+        ),
+        safetyMarginBytes: parseContextInteger(
+          "safety-margin-bytes",
+          cmdOpts.safetyMarginBytes ?? "0",
+          true
+        ),
+        query: cmdOpts.query as string | undefined,
+        queryModes,
+        collections: cmdOpts.collection as string[],
+        uriPrefix: cmdOpts.uriPrefix as string | undefined,
+        tagsAll: parseCsvValues(cmdOpts.tagsAll),
+        tagsAny: parseCsvValues(cmdOpts.tagsAny),
+        categories: parseCsvValues(cmdOpts.category),
+        author: cmdOpts.author as string | undefined,
+        lang: cmdOpts.lang as string | undefined,
+        since: cmdOpts.since as string | undefined,
+        until: cmdOpts.until as string | undefined,
+        graph: Boolean(cmdOpts.graph),
+        limit:
+          cmdOpts.limit === undefined
+            ? undefined
+            : parseContextInteger("limit", cmdOpts.limit),
+        candidateLimit:
+          cmdOpts.candidateLimit === undefined
+            ? undefined
+            : parseContextInteger("candidate-limit", cmdOpts.candidateLimit),
+        depthPolicy: cmdOpts.fast
+          ? "fast"
+          : cmdOpts.thorough
+            ? "thorough"
+            : "balanced",
+        format: format === "json" ? "json" : "md",
+      });
+      if (outputPath !== undefined) {
+        await Bun.write(outputPath, output);
+        return;
+      }
+      await writeOutput(output, format === "json" ? "json" : "md");
+    });
+
+  contextCmd
+    .command("verify <file>")
+    .description("Verify a saved Context Capsule without rebuilding it")
+    .option("--output <path>", "write only to this explicit file")
+    .option("--json", "canonical JSON receipt")
+    .option("--md", "readable Markdown receipt")
+    .action(
+      async (
+        file: string,
+        cmdOpts: Record<string, unknown>,
+        command: Command
+      ) => {
+        const format = getFormat(cmdOpts);
+        assertFormatSupported(CMD.contextVerify, format);
+        const outputPath = validateContextOutputPath(cmdOpts.output);
+        const globals = getGlobals();
+        const explicitIndexName =
+          command.getOptionValueSourceWithGlobals("index") === "cli"
+            ? globals.index
+            : undefined;
+        const { contextVerify } = await import("./commands/context-verify");
+        const output = await contextVerify(file, {
+          configPath: globals.config,
+          indexName: explicitIndexName,
+          format: format === "json" ? "json" : "md",
+        });
+        if (outputPath !== undefined) {
+          await Bun.write(outputPath, output);
+          return;
+        }
+        await writeOutput(output, format === "json" ? "json" : "md");
+      }
+    );
+
   contextCmd
     .command("rm <uri>")
     .description("Remove context item")
@@ -2628,20 +2806,46 @@ function wireGraphCommand(program: Command): void {
 // Serve Command (web UI)
 // ─────────────────────────────────────────────────────────────────────────────
 
-function wireDaemonCommand(program: Command): void {
-  const daemonCmd = program
-    .command("daemon")
-    .description("Start headless continuous indexing")
+function addGatewayOptions(
+  command: Command,
+  hostDescription = "HTTP listen address (default: 127.0.0.1)"
+): Command {
+  return command
+    .option("--host <address>", hostDescription)
+    .option("--mcp-token-file <path>", "restrictive bearer token file")
+    .option(
+      "--mcp-allowed-host <host>",
+      "exact allowed Host header (repeatable)",
+      (value: string, previous: string[] = []) => [...previous, value]
+    )
     .option(
-      "--no-sync-on-start",
-      "skip initial sync and only watch future file changes"
+      "--mcp-allowed-origin <origin>",
+      "exact allowed Origin (repeatable)",
+      (value: string, previous: string[] = []) => [...previous, value]
     )
-    // Local `--json` so `gno daemon --status --json` parses cleanly in any
-    // argv position. Mirrors the serve wiring: gated to --status only.
     .option(
-      "--json",
-      "JSON output (applies to --status; see process-status schema)"
+      "--mcp-enable-write",
+      "authorize HTTP MCP mutation tools (independent of authentication)"
     );
+}
+
+function wireDaemonCommand(program: Command): void {
+  const daemonCmd = addGatewayOptions(
+    program
+      .command("daemon")
+      .description("Start headless continuous indexing")
+      .option("-p, --port <num>", "MCP gateway port", "3000")
+      .option(
+        "--no-sync-on-start",
+        "skip initial sync and only watch future file changes"
+      )
+      // Local `--json` so `gno daemon --status --json` parses cleanly in any
+      // argv position. Mirrors the serve wiring: gated to --status only.
+      .option(
+        "--json",
+        "JSON output (applies to --status; see process-status schema)"
+      )
+  );
 
   // --detach / --status / --stop are mutually exclusive. Use Commander's
   // Option API so the conflict error is the native "option '--status'
@@ -2695,8 +2899,8 @@ function wireDaemonCommand(program: Command): void {
  * the foreground + detached-child paths boot the runtime.
  *
  * Mirrors `handleServeAction` exactly — same helper imports, same JSON
- * gating, same detached-child verification + pid-file cleanup. Daemon has no
- * `--port`, so the foreground path skips port validation entirely.
+ * gating, same detached-child verification + pid-file cleanup. Daemon's port
+ * identifies its headless MCP gateway.
  */
 async function handleDaemonAction(
   cmdOpts: Record<string, unknown>,
@@ -2749,7 +2953,9 @@ async function handleDaemonAction(
   }
 
   if (cmdOpts.detach) {
+    const port = parsePositiveInt("port", cmdOpts.port);
     await runDaemonDetach({
+      port,
       paths,
       spawnDetached,
       argv: resolveCliArgv(cmd),
@@ -2776,6 +2982,8 @@ async function handleDaemonAction(
     installPidFileCleanup(paths.pidFile);
   }
 
+  const port = parsePositiveInt("port", cmdOpts.port);
+
   const { daemon } = await import("./commands/daemon.js");
   const result = await daemon({
     configPath: globals.config,
@@ -2784,6 +2992,12 @@ async function handleDaemonAction(
     verbose: globals.verbose,
     quiet: globals.quiet,
     noSyncOnStart: cmdOpts.syncOnStart === false,
+    port,
+    host: cmdOpts.host as string | undefined,
+    tokenFile: cmdOpts.mcpTokenFile as string | undefined,
+    allowedHosts: cmdOpts.mcpAllowedHost as string[] | undefined,
+    allowedOrigins: cmdOpts.mcpAllowedOrigin as string[] | undefined,
+    enableWrite: cmdOpts.mcpEnableWrite === true ? true : undefined,
   });
   if (!result.success) {
     throw new CliError("RUNTIME", result.error);
@@ -2817,8 +3031,9 @@ async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
     process.stdout.write("gno daemon status\n");
     process.stdout.write(`${"─".repeat(50)}\n`);
     if (status.running) {
-      // Daemon is headless — no port to print.
-      process.stdout.write(`  running  yes (pid ${status.pid})\n`);
+      process.stdout.write(
+        `  running  yes (pid ${status.pid}, port ${status.port})\n`
+      );
       if (status.version) {
         process.stdout.write(`  version  ${status.version}\n`);
       }
@@ -2913,6 +3128,7 @@ async function runDaemonStop(deps: DaemonStopDeps): Promise<void> {
 }
 
 interface DaemonDetachDeps {
+  port: number;
   paths: { pidFile: string; logFile: string };
   spawnDetached: typeof import("./detach.js").spawnDetached;
   /**
@@ -2933,24 +3149,28 @@ async function runDaemonDetach(deps: DaemonDetachDeps): Promise<void> {
     argv: childArgv,
     pidFile: deps.paths.pidFile,
     logFile: deps.paths.logFile,
+    port: deps.port,
   });
-  // Daemon is headless — print pid only (no URL).
+  // Daemon has no Web UI URL; its listener exists solely for MCP.
   process.stdout.write(`PID ${result.pid}\n`);
 }
 
 function wireServeCommand(program: Command): void {
-  const serveCmd = program
-    .command("serve")
-    .description("Start web UI server")
-    .option("-p, --port <num>", "port to listen on", "3000")
-    // Local `--json` so `gno serve --status --json` parses cleanly in any
-    // argv position. Global `--json` already exists on the root program
-    // (see line 208); resolution goes through `getFormat()` /
-    // `getGlobals()` which precedence-merges local over global.
-    .option(
-      "--json",
-      "JSON output (applies to --status; see process-status schema)"
-    );
+  const serveCmd = addGatewayOptions(
+    program
+      .command("serve")
+      .description("Start web UI server")
+      .option("-p, --port <num>", "port to listen on", "3000")
+      // Local `--json` so `gno serve --status --json` parses cleanly in any
+      // argv position. Global `--json` already exists on the root program
+      // (see line 208); resolution goes through `getFormat()` /
+      // `getGlobals()` which precedence-merges local over global.
+      .option(
+        "--json",
+        "JSON output (applies to --status; see process-status schema)"
+      ),
+    "loopback HTTP listen address (default: 127.0.0.1)"
+  );
 
   // --detach / --status / --stop are mutually exclusive. Use Commander's
   // Option API so the conflict error is the native "option '--status'
@@ -3097,6 +3317,11 @@ async function handleServeAction(
     port,
     configPath: globals.config,
     index: globals.index,
+    host: cmdOpts.host as string | undefined,
+    tokenFile: cmdOpts.mcpTokenFile as string | undefined,
+    allowedHosts: cmdOpts.mcpAllowedHost as string[] | undefined,
+    allowedOrigins: cmdOpts.mcpAllowedOrigin as string[] | undefined,
+    enableWrite: cmdOpts.mcpEnableWrite === true ? true : undefined,
   });
 
   if (!result.success) {

package/src/config/index.ts

@@ -50,6 +50,8 @@ export {
   CollectionSchema,
   type Config,
   ConfigSchema,
+  HttpGatewayConfigSchema,
+  HttpGatewayLimitsSchema,
   CONTENT_TYPE_GRAPH_HINTS,
   type ContentTypeConfig,
   type ContentTypeGraphHint,
@@ -67,3 +69,4 @@ export {
   type ScopeType,
   ScopeTypeSchema,
 } from "./types";
+export type { HttpGatewayConfig } from "./types";

package/src/config/types.ts

@@ -245,6 +245,40 @@ export const ModelConfigSchema = z.object({
 
 export type ModelConfig = z.infer<typeof ModelConfigSchema>;
 
+// ────────────────────────────────────────────────────────────────────────────
+// Resident HTTP gateway schema
+// ────────────────────────────────────────────────────────────────────────────
+
+export const HttpGatewayLimitsSchema = z.object({
+  maxBodyBytes: z
+    .number()
+    .int()
+    .min(1)
+    .max(16 * 1024 * 1024)
+    .optional(),
+  maxRequestsPerMinute: z.number().int().min(1).max(100_000).optional(),
+  maxConcurrentRequests: z.number().int().min(1).max(10_000).optional(),
+  maxQueuedRequests: z.number().int().min(0).max(10_000).optional(),
+  maxSessions: z.number().int().min(1).max(10_000).optional(),
+  sessionIdleTimeoutMs: z.number().int().min(1_000).optional(),
+});
+
+export const HttpGatewayConfigSchema = z.object({
+  /** Literal listen address. Defaults to IPv4 loopback. */
+  host: z.string().min(1).optional(),
+  /** Bearer token file. Required for wildcard/non-loopback binding. */
+  tokenFile: z.string().min(1).optional(),
+  /** Exact Host header allowlist. */
+  allowedHosts: z.array(z.string().min(1)).optional(),
+  /** Exact Origin allowlist. Origin-less non-browser clients remain supported. */
+  allowedOrigins: z.array(z.string().min(1)).optional(),
+  /** Separate mutation authorization; authentication alone never enables it. */
+  enableWrite: z.boolean().optional(),
+  limits: HttpGatewayLimitsSchema.optional(),
+});
+
+export type HttpGatewayConfig = z.infer<typeof HttpGatewayConfigSchema>;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Content Type Schema
 // ─────────────────────────────────────────────────────────────────────────────
@@ -301,6 +335,9 @@ export const ConfigSchema = z.object({
 
   /** Model configuration */
   models: ModelConfigSchema.optional(),
+
+  /** Resident Streamable HTTP MCP gateway configuration */
+  gateway: HttpGatewayConfigSchema.optional(),
 });
 
 export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {