argsbarg 6.1.1 → 6.1.3

package/src/mcp/tools.ts

@@ -3,11 +3,8 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for Cli.invoke.
 */
 
-import { docsMcpResources } from "../docs/mcp-resources.ts";
-import { cliResolveNotes } from "../help.ts";
-import { visibleOptions } from "../hidden.ts";
-import { collectOptionDefs } from "../parse.ts";
-import { cliSchemaJson } from "../schema.ts";
+import { collectOptionDefs } from "~/core/parse.ts";
+import { cliSchemaJson } from "~/core/schema.ts";
 import {
   type CliLeaf,
   type CliNode,
@@ -17,8 +14,12 @@ import {
   type CliProgram,
   CliValueFormat,
   isCliLeaf,
+  isJsonLeaf,
   leafOutputSchema,
-} from "../types.ts";
+} from "~/core/types.ts";
+import { docsMcpResources } from "~/docs/mcp-resources.ts";
+import { cliResolveNotes } from "~/help.ts";
+import { isMcpHidden, visibleOptions } from "~/runtime/exposure.ts";
 
 const DURATION_PATTERN = "^\\d+[hdms]?$";
 
@@ -27,7 +28,7 @@ export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
 }
 
-export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "../docs/mcp-resources.ts";
+export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "~/docs/mcp-resources.ts";
 
 /** Sanitizes a command key segment for MCP tool names and server identity. */
 export function sanitizeToolSegment(key: string): string {
@@ -43,8 +44,6 @@ export function mcpServerId(root: CliProgram): string {
 export interface McpToolDef {
   /** MCP tool name (underscore-separated, sanitized segments). */
   name: string;
-  /** HTTP API tool name (hyphen-separated path; preserves command key spelling). */
-  apiName: string;
   /** Tool description from the leaf command. */
   description: string;
   /** Command path segments from the program root. */
@@ -71,14 +70,6 @@ export function mcpToolName(root: CliProgram, path: string[]): string {
   return path.map(sanitizeToolSegment).join("_");
 }
 
-/** Builds the HTTP API tool name for a leaf at the given path (hyphen-joined, unsanitized). */
-export function apiToolName(root: CliProgram, path: string[]): string {
-  if (path.length === 0) {
-    return root.key;
-  }
-  return path.join("-");
-}
-
 /** JSON Schema property for one option. */
 function optionProperty(opt: CliOption): Record<string, unknown> {
   const base: Record<string, unknown> = { description: opt.description };
@@ -121,7 +112,7 @@ function optionProperty(opt: CliOption): Record<string, unknown> {
   }
 }
 
-function formatMcpOptionValue(opt: CliOption, val: unknown): string | { error: string } {
+export function formatMcpOptionValue(opt: CliOption, val: unknown): string | { error: string } {
   if (opt.format === CliValueFormat.CommaList) {
     if (Array.isArray(val)) {
       const items = val.map(String).filter(Boolean);
@@ -150,6 +141,10 @@ function positionalProperty(p: CliPositional): Record<string, unknown> {
 
 /** Builds inputSchema for a leaf command. */
 function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Record<string, unknown> {
+  if (isJsonLeaf(leaf) && leaf.inputSchema !== undefined) {
+    return leaf.inputSchema;
+  }
+
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
 
@@ -233,13 +228,12 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
       if (cmd.key === "completion" || cmd.key === "configure" || cmd.key === "mcp" || cmd.key === "version") {
         return;
       }
-      if (cmd.hidden || cmd.mcpTool?.enabled === false) {
+      if (isMcpHidden(cmd)) {
         return;
       }
       const outputSchema = leafOutputSchema(cmd);
       out.push({
         name: mcpToolName(root, path),
-        apiName: apiToolName(root, path),
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
@@ -286,6 +280,10 @@ export function mcpToolCallToArgv(
   tool: McpToolDef,
   args: Record<string, unknown>,
 ): string[] | { error: string } {
+  if (isJsonLeaf(tool.leaf)) {
+    return [...tool.path];
+  }
+
   const argv = [...tool.path];
 
   for (const opt of collectOptionDefs(root, tool.path)) {

package/src/{capabilities.ts → runtime/capabilities.ts}

@@ -3,12 +3,12 @@ Internal capability resolver — decides which platform builtins are active for
 Not exported from the public package barrel.
 */
 
-import { configCommandsEnabled } from "./config/entry.ts";
-import type { CliProgram } from "./types.ts";
+import { configCommandsEnabled } from "~/config/entry.ts";
+import type { CliProgram } from "~/core/types.ts";
 
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {
-  api: boolean;
+  http: boolean;
   completion: boolean;
   mcp: boolean;
   configure: boolean;
@@ -20,11 +20,11 @@ export interface CliCapabilities {
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
   const configure = program.configure?.enabled !== false;
   return {
-    api: program.apiServer?.enabled === true,
+    http: program.httpServer?.enabled === true,
     completion: program.completion?.enabled !== false,
     mcp: program.mcpServer?.enabled === true,
     configure,
-    docs: program.docs?.enabled === true,
+    docs: program.docs?.enabled !== false,
     configCommands: configCommandsEnabled(program),
   };
 }
@@ -44,8 +44,8 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.mcp) {
     names.push("mcp");
   }
-  if (caps.api) {
-    names.push("api");
+  if (caps.http) {
+    names.push("http");
   }
   return names;
 }
@@ -65,14 +65,14 @@ export function skipsRequiredAppConfigExit(path: string[], caps: CliCapabilities
   return false;
 }
 
-export type CapabilityFeature = "api" | "mcp" | "configure" | "docs" | "completion";
+export type CapabilityFeature = "http" | "mcp" | "configure" | "docs" | "completion";
 
 /** Stderr message when a disabled built-in is invoked from the CLI. */
 export function capabilityDeniedMessage(feature: CapabilityFeature): string {
   switch (feature) {
     case "completion":
       return "Shell completion is not available for this app.\n";
-    case "api":
+    case "http":
       return "HTTP API is not available for this app.\n";
     case "mcp":
       return "MCP is not available for this app.\n";
@@ -97,8 +97,8 @@ export function assertBuiltinAllowed(argv: string[], caps: CliCapabilities): voi
     process.stderr.write(capabilityDeniedMessage("mcp"));
     process.exit(1);
   }
-  if (first === "api" && !caps.api) {
-    process.stderr.write(capabilityDeniedMessage("api"));
+  if (first === "http" && !caps.http) {
+    process.stderr.write(capabilityDeniedMessage("http"));
     process.exit(1);
   }
   if (first === "configure" && !caps.configure) {

package/src/{cli-errors.ts → runtime/cli-errors.ts}

@@ -2,12 +2,12 @@
 Handler error helper with contextual help.
 */
 
-import { cliPresentationRoot } from "./builtins/presentation.ts";
-import type { CliContext } from "./context.ts";
-import { cliHelpRender } from "./help.ts";
+import { cliPresentationRoot } from "~/builtins/presentation.ts";
+import type { CliContext } from "~/core/context.ts";
+import { cliHelpRender } from "~/help.ts";
 
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
-  if (ctx.invocation === "api" || ctx.invocation === "mcp") {
+  if (ctx.invocation === "http" || ctx.invocation === "mcp") {
     throw new Error(msg);
   }
   const color = process.stderr.isTTY;

package/src/{cli.ts → runtime/cli.ts}

@@ -2,30 +2,46 @@
 Runtime entry point: validate program, cache derived state, run / invoke / MCP serve.
 */
 
+import { randomUUID } from "node:crypto";
 import { format } from "node:util";
-import { apiServeHttp } from "./api/server.ts";
-import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
-import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
+import { builtinInterceptRoot, dispatchBuiltin } from "~/builtins/dispatch.ts";
+import { cliParseRoot, cliPresentationRoot } from "~/builtins/presentation.ts";
+import { bootstrapAppConfig, type EnsureAppConfigOpts, ensureAppConfig } from "~/config/bootstrap.ts";
+import { type AnyAppConfigSnapshot, createAppConfigSnapshot } from "~/config/context.ts";
+import { readAppConfigFileRaw, resolveAppConfigPath } from "~/config/file.ts";
+import { effectiveJsonSchema } from "~/config/schema.ts";
+import { CliContext } from "~/core/context.ts";
+import { LeafInputError, preloadPipableJson } from "~/core/leaf-inputs.ts";
+import { ParseKind, type ParseResult, parse, postParseValidate } from "~/core/parse.ts";
+import { type CliSchemaRootExport, cliSchemaExport } from "~/core/schema.ts";
+import type {
+  CliHandler,
+  CliInvocation,
+  CliLeaf,
+  CliLocals,
+  CliNode,
+  CliProgram,
+  CliRespondOptions,
+  CliRouter,
+  InvokeFailureKind,
+} from "~/core/types.ts";
+import { isCliLeaf, isCliRouter } from "~/core/types.ts";
+import { cliValidateProgram } from "~/core/validate.ts";
+import { cliHelpRender } from "~/help.ts";
+import { isBuiltinInvokePath } from "~/hooks/builtin.ts";
+import { buildInvokeHookContext, classifyFailureKind, runErrorPipeline, runHook } from "~/hooks/run.ts";
+import { httpServeHttp } from "~/http/server.ts";
+import { LogEmitter } from "~/log/emitter.ts";
+import { bootstrapMcpEnv } from "~/mcp/env.ts";
+import { mcpServeStdioLoop } from "~/mcp/server.ts";
+import { createServerRuntime, type ServerHandleContext } from "~/server/context.ts";
+import { resolveHttpServeConfig, resolveMcpServeConfig, type ServeOverrides } from "~/server/overrides.ts";
 import {
   assertBuiltinAllowed,
   type CliCapabilities,
   resolveCapabilities,
   skipsRequiredAppConfigExit,
 } from "./capabilities.ts";
-import { bootstrapAppConfig, type EnsureAppConfigOpts, ensureAppConfig } from "./config/bootstrap.ts";
-import { type AnyAppConfigSnapshot, createAppConfigSnapshot } from "./config/context.ts";
-import { readAppConfigFileRaw, resolveAppConfigPath } from "./config/file.ts";
-import { effectiveJsonSchema } from "./config/schema.ts";
-import { CliContext } from "./context.ts";
-import { cliHelpRender } from "./help.ts";
-import { LeafInputError, preloadPipableJson } from "./leaf-inputs.ts";
-import { bootstrapMcpEnv } from "./mcp/env.ts";
-import { mcpServeStdioLoop } from "./mcp/server.ts";
-import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
-import { type CliSchemaExport, cliSchemaExport } from "./schema.ts";
-import type { CliHandler, CliInvocation, CliLeaf, CliNode, CliProgram, CliRespondOptions, CliRouter } from "./types.ts";
-import { isCliLeaf, isCliRouter } from "./types.ts";
-import { cliValidateProgram } from "./validate.ts";
 
 /** Outcome of a non-exiting CLI invocation. */
 export type CliInvokeKind = "ok" | "help" | "error";
@@ -37,6 +53,8 @@ export interface CliInvokeResult {
   stdout: string;
   stderr: string;
   errorMsg?: string;
+  /** Classified failure for HTTP/MCP status mapping. */
+  failureKind?: InvokeFailureKind;
   /** Headless response payload when invocation is `api` or `mcp` and the handler succeeded. */
   response?: CliRespondOptions;
 }
@@ -66,6 +84,8 @@ export class Cli {
   private readonly parseRootMerged: CliRouter;
   private readonly presentationRoot: CliRouter;
   private _appConfig?: AnyAppConfigSnapshot;
+  /** Active HTTP/MCP server handle (set during serve). */
+  server?: ServerHandleContext;
 
   constructor(program: CliProgram) {
     cliValidateProgram(program);
@@ -86,7 +106,7 @@ export class Cli {
     return this._appConfig;
   }
 
-  exportCommandSchema(): CliSchemaExport {
+  exportCommandSchema(): CliSchemaRootExport {
     return cliSchemaExport(this.program);
   }
 
@@ -127,7 +147,7 @@ export class Cli {
 
     let preloadedJson: Record<string, unknown> = {};
     try {
-      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli");
+      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli", pr.args);
     } catch (err) {
       if (err instanceof LeafInputError) {
         this.exitLeafInputError(err, pr.path);
@@ -148,6 +168,8 @@ export class Cli {
       snapshot,
       undefined,
       preloadedJson,
+      pr.pathParams,
+      { requestId: randomUUID() } as CliLocals,
     );
     try {
       this.ensureValidatedLeafInputs(ctx, leaf);
@@ -169,7 +191,13 @@ export class Cli {
 
   async invoke(
     argv: string[],
-    opts?: { invocation?: CliInvocation; toolArgs?: Record<string, unknown> },
+    opts?: {
+      invocation?: CliInvocation;
+      toolArgs?: Record<string, unknown>;
+      requestId?: string;
+      http?: { request: Request; clientIp: string; requestId: string };
+      mcp?: { rpcMethod: string; toolName?: string; requestId: string };
+    },
   ): Promise<CliInvokeResult> {
     const invocation = opts?.invocation ?? "mcp";
     const prep = this.prepareDispatch(argv, { presentationFallback: true });
@@ -181,6 +209,7 @@ export class Cli {
           stdout: "",
           stderr: "",
           errorMsg: "Help is not available via tool calls.",
+          failureKind: "help",
         };
       }
       return {
@@ -189,6 +218,7 @@ export class Cli {
         stdout: "",
         stderr: prep.error.errorMsg,
         errorMsg: prep.error.errorMsg,
+        failureKind: "validation",
       };
     }
 
@@ -198,6 +228,8 @@ export class Cli {
       exitOnMissing: false,
     });
 
+    const runtime = this.server?.runtime;
+    const requestId = opts?.requestId ?? opts?.http?.requestId ?? opts?.mcp?.requestId ?? randomUUID();
     const ctx = new CliContext(
       this.program.key,
       pr.path,
@@ -207,8 +239,30 @@ export class Cli {
       invocation,
       snapshot,
       opts?.toolArgs,
+      {},
+      pr.pathParams,
+      { requestId } as CliLocals,
+      runtime,
     );
 
+    const skipHooks = isBuiltinInvokePath(pr.path);
+    const hooks = this.program.hooks;
+    const obscureUnexpected =
+      invocation === "http"
+        ? (this.server?.http?.obscureUnexpected ?? this.program.httpServer?.errors?.obscureUnexpected ?? false)
+        : invocation === "mcp"
+          ? (this.server?.mcp?.obscureUnexpected ?? this.program.mcpServer?.errors?.obscureUnexpected ?? false)
+          : false;
+    const emitter = this.server?.emitter;
+
+    const hookCtx = () =>
+      buildInvokeHookContext(ctx, {
+        path: pr.path,
+        runtime,
+        http: opts?.http,
+        mcp: opts?.mcp,
+      });
+
     let stdout = "";
     let stderr = "";
     const origExit = process.exit;
@@ -252,6 +306,33 @@ export class Cli {
       stderr += `${format(...args)}\n`;
     };
 
+    const finishError = async (
+      err: unknown,
+      kindOpts: Parameters<typeof classifyFailureKind>[1],
+    ): Promise<CliInvokeResult> => {
+      const failureKind = classifyFailureKind(err, kindOpts);
+      if (!skipHooks) {
+        const piped = await runErrorPipeline(hookCtx(), err, failureKind, hooks, emitter, obscureUnexpected);
+        return {
+          kind: "error",
+          exitCode: piped.clientError.exitCode ?? 1,
+          stdout,
+          stderr: `${piped.errorMsg}\n`,
+          errorMsg: piped.errorMsg,
+          failureKind: piped.failureKind,
+        };
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        kind: "error",
+        exitCode: 1,
+        stdout,
+        stderr: `${message}\n`,
+        errorMsg: message,
+        failureKind,
+      };
+    };
+
     try {
       if (pr.kind === ParseKind.Ok) {
         await dispatchBuiltin(this.program, pr, {
@@ -260,6 +341,10 @@ export class Cli {
         });
       }
 
+      if (!skipHooks) {
+        await runHook(() => hooks?.beforeInvoke?.(hookCtx()), "beforeInvoke");
+      }
+
       this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
@@ -267,53 +352,44 @@ export class Cli {
       }
 
       const response = ctx.getResponse();
-      return {
+      const okResult: CliInvokeResult = {
         kind: "ok",
         exitCode: 0,
         stdout,
         stderr,
         ...(response ? { response } : {}),
       };
+
+      if (!skipHooks) {
+        await runHook(() => hooks?.afterInvoke?.({ ...hookCtx(), result: okResult }), "afterInvoke");
+      }
+
+      return okResult;
     } catch (err) {
       if (err instanceof CliInvokeExit) {
         if (err.code === 0) {
           const response = ctx.getResponse();
-          return {
+          const okResult: CliInvokeResult = {
             kind: "ok",
             exitCode: 0,
             stdout,
             stderr,
             ...(response ? { response } : {}),
           };
+          if (!skipHooks) {
+            await runHook(() => hooks?.afterInvoke?.({ ...hookCtx(), result: okResult }), "afterInvoke");
+          }
+          return okResult;
         }
-        const msg = stderr.trim() || `Exit code ${err.code}`;
-        return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
+        return finishError(err, {});
       }
       if (err instanceof LeafInputError) {
-        return {
-          kind: "error",
-          exitCode: 1,
-          stdout,
-          stderr: `${err.message}\n`,
-          errorMsg: err.message,
-        };
+        return finishError(err, { parseError: true });
       }
       if (err instanceof Error) {
-        return {
-          kind: "error",
-          exitCode: 1,
-          stdout,
-          stderr: `${err.message}\n`,
-          errorMsg: err.message,
-        };
+        return finishError(err, {});
       }
-      return {
-        kind: "error",
-        exitCode: 1,
-        stdout,
-        stderr: "Unknown error\n",
-        errorMsg: "Unknown error",
-      };
+      return finishError(err, {});
     } finally {
       process.exit = origExit;
       process.stdout.write = origStdoutWrite;
@@ -325,12 +401,28 @@ export class Cli {
     }
   }
 
-  async serveMcp(): Promise<never> {
+  async serveMcp(overrides: ServeOverrides = {}): Promise<never> {
     try {
       if (this.program.mcpServer) {
         bootstrapMcpEnv(this.program.mcpServer);
       }
-      bootstrapAppConfig(this.program, { validateFile: false });
+      const resolved = resolveMcpServeConfig(this.program, overrides);
+      const runtime = createServerRuntime(this.program, "mcp");
+      const emitter = new LogEmitter({ program: this.program, resolved: resolved.log });
+      this.server = {
+        runtime,
+        emitter,
+        mcp: resolved,
+        mcpHooks: this.program.mcpServer?.hooks,
+      };
+      bootstrapAppConfig(this.program, { validateFile: "soft", runtime, emitter });
+      const shutdown = () => {
+        emitter.emit({ level: "info", message: "server stopping", action: "server.stop" });
+        process.exit(0);
+      };
+      process.once("SIGINT", shutdown);
+      process.once("SIGTERM", shutdown);
+      emitter.emitLifecycle(`${this.program.key} ${this.program.version} — MCP ready (stdio)`, "mcp.server.ready");
       await mcpServeStdioLoop(this);
       process.exit(0);
     } catch (err) {
@@ -343,10 +435,25 @@ export class Cli {
     }
   }
 
-  async serveApi(): Promise<never> {
+  async serveHttp(overrides: ServeOverrides = {}): Promise<never> {
     try {
-      bootstrapAppConfig(this.program, { validateFile: false });
-      await apiServeHttp(this);
+      const resolved = resolveHttpServeConfig(this.program, overrides);
+      const runtime = createServerRuntime(this.program, "http");
+      const emitter = new LogEmitter({ program: this.program, resolved: resolved.log });
+      this.server = {
+        runtime,
+        emitter,
+        http: resolved,
+        httpHooks: this.program.httpServer?.hooks,
+      };
+      bootstrapAppConfig(this.program, { validateFile: "soft", runtime, emitter });
+      const shutdown = () => {
+        emitter.emit({ level: "info", message: "server stopping", action: "server.stop" });
+        process.exit(0);
+      };
+      process.once("SIGINT", shutdown);
+      process.once("SIGTERM", shutdown);
+      await httpServeHttp(this, resolved);
       process.exit(0);
     } catch (err) {
       if (err instanceof Error) {
@@ -416,6 +523,7 @@ export class Cli {
             path: pr.path,
             args: pr.args,
             opts: pr.opts,
+            pathParams: pr.pathParams,
             helpExplicit: false,
             helpPath: [],
             errorMsg: msg,
@@ -432,6 +540,7 @@ export class Cli {
             path: pr.path,
             args: pr.args,
             opts: pr.opts,
+            pathParams: pr.pathParams,
             helpExplicit: false,
             helpPath: [],
             errorMsg: msg,
@@ -450,6 +559,7 @@ export class Cli {
           path: pr.path,
           args: pr.args,
           opts: pr.opts,
+          pathParams: pr.pathParams,
           helpExplicit: false,
           helpPath: [],
           errorMsg: msg,

package/src/runtime/exposure.ts

@@ -0,0 +1,102 @@
+/*
+Per-surface exposure helpers (cli, http, mcpTool).
+Parsing uses the full tree; presentation/schema/MCP/HTTP discovery use these filters.
+*/
+
+import type { CliLeaf, CliNode, CliNodeBase, CliOption } from "~/core/types.ts";
+import { isCliRouter } from "~/core/types.ts";
+
+/** True when the node is omitted from CLI help, schema, and completions (still invocable). */
+export function isCliHidden(node: CliNodeBase): boolean {
+  return node.cli?.hidden === true;
+}
+
+/** True when the option is omitted from CLI help, schema, and completions. */
+export function isOptionCliHidden(opt: CliOption): boolean {
+  return opt.cli?.hidden === true;
+}
+
+/** True when the node is omitted from cli-schema export. */
+export function isCliSchemaHidden(node: CliNodeBase): boolean {
+  if (node.cli?.schema?.enabled === false) {
+    return true;
+  }
+  if (node.cli?.schema?.hidden === true) {
+    return true;
+  }
+  return isCliHidden(node);
+}
+
+/** True when the node is omitted from shell completions. */
+export function isCliCompletionsHidden(node: CliNodeBase): boolean {
+  if (node.cli?.completions?.enabled === false) {
+    return true;
+  }
+  if (node.cli?.completions?.hidden === true) {
+    return true;
+  }
+  return isCliHidden(node);
+}
+
+/** True when the leaf is omitted from MCP tools/list. */
+export function isMcpHidden(leaf: CliLeaf): boolean {
+  if (leaf.mcpTool?.enabled === false) {
+    return true;
+  }
+  return leaf.mcpTool?.hidden === true;
+}
+
+/** True when the node is not callable via CLI (`cli.enabled: false`, cascades from parent). */
+export function isCliCallable(node: CliNodeBase, parentEnabled = true): boolean {
+  if (!parentEnabled) {
+    return false;
+  }
+  if (node.cli?.enabled === false) {
+    return false;
+  }
+  return true;
+}
+
+/** True when the leaf is omitted from HTTP route table / OpenAPI. */
+export function isHttpHidden(node: CliNodeBase): boolean {
+  return node.http?.hidden === true;
+}
+
+/** True when the leaf is not exposed on HTTP (disabled or hidden). */
+export function isHttpDisabled(node: CliNodeBase): boolean {
+  return node.http?.enabled === false;
+}
+
+/** Options visible in help, schema, completions, and MCP tool inputSchema. */
+export function visibleOptions(options: CliOption[] | undefined): CliOption[] {
+  return (options ?? []).filter((o) => !isOptionCliHidden(o));
+}
+
+/** Strips CLI-hidden commands and options from one node for presentation export. */
+export function presentationNode(node: CliNode): CliNode | null {
+  if (isCliHidden(node)) {
+    return null;
+  }
+  const options = visibleOptions(node.options);
+  if (isCliRouter(node)) {
+    const commands = node.commands.map((ch) => presentationNode(ch)).filter((ch): ch is CliNode => ch !== null);
+    return { ...node, options, commands };
+  }
+  return { ...node, options };
+}
+
+/** Subcommands visible in help listings. */
+export function visibleSubcommands(cmds: CliNode[]): CliNode[] {
+  return cmds.filter((c) => !isCliHidden(c));
+}
+
+/** Default HTTP response metadata from a leaf `http` block. */
+export function leafHttpResponseDefaults(leaf: CliLeaf): {
+  contentType?: string;
+  contentDisposition?: string;
+} {
+  return {
+    contentType: leaf.http?.successContentType,
+    contentDisposition: leaf.http?.contentDisposition,
+  };
+}