argsbarg 3.3.14 → 3.4.0

package/src/mcp/tools.ts

@@ -3,9 +3,11 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for cliInvoke.
 */
 
+import { cliResolveNotes } from "../help.ts";
 import { collectOptionDefs } from "../parse.ts";
+import { visibleOptions } from "../hidden.ts";
 import { cliSchemaJson } from "../schema.ts";
-import { CliProgram, CliLeaf, CliNode, CliOption, CliOptionKind, CliPositional, isCliLeaf, isCliRouter } from "../types.ts";
+import { CliProgram, CliLeaf, CliNode, CliOption, CliOptionKind, CliPositional, isCliLeaf, isCliRouter, leafOutputSchema } from "../types.ts";
 
 /** Default URI pattern for the CLI schema MCP resource (`<mcpId>://schema`). */
 export function defaultMcpSchemaUri(mcpId: string): string {
@@ -34,6 +36,8 @@ export interface McpToolDef {
   leaf: CliLeaf;
   /** JSON Schema for tools/call arguments. */
   inputSchema: Record<string, unknown>;
+  /** JSON Schema for structured tool results when set on the leaf `mcpTool`. */
+  outputSchema?: Record<string, unknown>;
 }
 
 /** Builds MCP tool description: "{cli path} — {description}". */
@@ -80,7 +84,7 @@ function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Reco
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
 
-  for (const opt of collectOptionDefs(root, path)) {
+  for (const opt of visibleOptions(collectOptionDefs(root, path))) {
     properties[opt.name] = optionProperty(opt);
     if (opt.required) {
       required.push(opt.name);
@@ -106,15 +110,21 @@ function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Reco
   return schema;
 }
 
-/** Resolves MCP tool description with optional override and requiresEnv suffix. */
+/** Resolves MCP tool description with optional override, requiresEnv suffix, and leaf notes. */
 function resolveToolDescription(root: CliProgram, path: string[], leaf: CliLeaf): string {
+  let desc: string;
   if (leaf.mcpTool?.description) {
-    return leaf.mcpTool.description;
+    desc = leaf.mcpTool.description;
+  } else {
+    desc = mcpToolDescription(path, root.key, leaf.description);
+    const env = leaf.mcpTool?.requiresEnv;
+    if (env && env.length > 0) {
+      desc += ` [requires env: ${env.join(", ")}]`;
+    }
   }
-  let desc = mcpToolDescription(path, root.key, leaf.description);
-  const env = leaf.mcpTool?.requiresEnv;
-  if (env && env.length > 0) {
-    desc += ` [requires env: ${env.join(", ")}]`;
+  const notes = (leaf.notes ?? "").trim();
+  if (notes.length > 0) {
+    desc += `\n\n${cliResolveNotes(notes, root.key)}`;
   }
   return desc;
 }
@@ -155,18 +165,25 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
   /** Walks the command tree and appends leaf tools. */
   function walk(cmd: CliNode, path: string[]): void {
     if (isCliLeaf(cmd)) {
-      if (cmd.key === "completion" || cmd.key === "install" || cmd.key === "mcp" || cmd.key === "version") {
+      if (
+        cmd.key === "completion" ||
+        cmd.key === "install" ||
+        cmd.key === "mcp" ||
+        cmd.key === "version"
+      ) {
         return;
       }
-      if (cmd.mcpTool?.enabled === false) {
+      if (cmd.hidden || cmd.mcpTool?.enabled === false) {
         return;
       }
+      const outputSchema = leafOutputSchema(cmd);
       out.push({
         name: mcpToolName(root, path),
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
         inputSchema: buildInputSchema(root, path, cmd),
+        ...(outputSchema === undefined ? {} : { outputSchema }),
       });
       return;
     }

package/src/runtime.ts

@@ -4,7 +4,7 @@ This module runs parsed commands, help, errors, completion, and leaf handlers.
 
 import { resolveCapabilities } from "./capabilities.ts";
 import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
-import { cliPresentationRoot } from "./builtins/presentation.ts";
+import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
 import type { CliRouter } from "./types.ts";
 import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { CliContext } from "./context.ts";
@@ -13,7 +13,7 @@ import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliValidateProgram } from "./validate.ts";
 
 function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
-  return cliPresentationRoot(program);
+  return cliParseRoot(program);
 }
 
 export async function cliRun(program: CliProgram, argv: string[] = process.argv.slice(2)): Promise<never> {
@@ -68,7 +68,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
-    process.stdout.write(cliHelpRender(cliPresentationRoot(program), pr.helpPath, false));
+    process.stdout.write(cliHelpRender(cliParseRoot(program), pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 

package/src/schema.ts

@@ -2,13 +2,18 @@
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
 */
 
-import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter, leafOutputSchema } from "./types.ts";
 import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
 import { cliResolveNotes } from "./help.ts";
+import { visibleOptions } from "./hidden.ts";
 
 const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
 
-function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport {
+function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
+  if (cmd.hidden) {
+    return null;
+  }
+
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -18,14 +23,19 @@ function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport {
     out.notes = cmd.notes;
   }
 
-  if ((cmd.options ?? []).length > 0) {
-    out.options = cmd.options;
+  const options = visibleOptions(cmd.options);
+  if (options.length > 0) {
+    out.options = options;
   }
 
   if (isCliLeaf(cmd)) {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
+    const outputSchema = leafOutputSchema(cmd);
+    if (outputSchema !== undefined) {
+      out.outputSchema = outputSchema;
+    }
     out.commands = exportPresentationBuiltins(root);
     return out;
   }
@@ -39,7 +49,9 @@ function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport {
 
   const children = isCliRouter(cmd) ? cmd.commands.filter((ch) => !RESERVED.has(ch.key)) : [];
   if (children.length > 0) {
-    out.commands = children.map((ch) => exportCommand(ch, root));
+    out.commands = children
+      .map((ch) => exportCommand(ch, root))
+      .filter((ch): ch is CliSchemaExport => ch !== null);
   }
 
   return out;
@@ -59,7 +71,15 @@ function resolveSchemaNotes(node: CliSchemaExport, appKey: string): CliSchemaExp
 
 /** Returns the JSON-safe command tree (handlers omitted). */
 export function cliSchemaExport(root: CliProgram): CliSchemaExport {
-  return resolveSchemaNotes(exportCommand(root, root), root.key);
+  const exported = exportCommand(root, root);
+  if (!exported) {
+    return {
+      key: root.key,
+      description: root.description,
+      commands: exportPresentationBuiltins(root),
+    };
+  }
+  return resolveSchemaNotes(exported, root.key);
 }
 
 export function cliSchemaJson(root: CliProgram): string {

package/src/types.ts

@@ -50,6 +50,8 @@ export enum CliFallbackMode {
 export interface CliOption {
   /** Option name (e.g., "name", "verbose"). */
   name: string;
+  /** When `true`, omit from help, schema, completions, and MCP tool inputSchema (still parseable). */
+  hidden?: boolean;
   /** Description shown in help. */
   description: string;
   /** Option kind: presence flag, string value, or number value. */
@@ -87,6 +89,19 @@ export interface CliPositional {
   argMax?: number;
 }
 
+/** Optional metadata for `mcp bundle` MCP Bundle output (program root `mcpServer.bundle` only). */
+export interface CliMcpBundleConfig {
+  author?: {
+    name: string;
+    email?: string;
+    url?: string;
+  };
+  /** Repo-relative path to a PNG icon copied into the bundle. */
+  icon?: string;
+  /** Manifest `long_description` (defaults to program description). */
+  longDescription?: string;
+}
+
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
@@ -113,6 +128,8 @@ export interface CliMcpServerConfig {
    * URIs must be unique and must not equal schemaResourceUri.
    */
   resources?: CliMcpResource[];
+  /** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
+  bundle?: CliMcpBundleConfig;
 }
 
 /**
@@ -148,6 +165,10 @@ export interface CliMcpToolConfig {
    * Empty string counts as absent.
    */
   requiresEnv?: string[];
+  /**
+   * @deprecated Set `outputSchema` on the leaf command instead.
+   */
+  outputSchema?: Record<string, unknown>;
 }
 
 /**
@@ -211,6 +232,8 @@ export interface CliDocsConfig {
 export interface CliNodeBase {
   /** Program or command key (e.g., "myapp", "stat", "owner"). */
   key: string;
+  /** When `true`, omit from help listings, schema, completions, and MCP tools (still invocable). */
+  hidden?: boolean;
   /** Short description shown in help. */
   description: string;
   /** Additional notes shown in help (`{argsbarg:program}` → program key). */
@@ -227,6 +250,11 @@ export type CliLeaf = CliNodeBase & {
   handler: CliHandler;
   /** Positional argument definitions. */
   positionals?: CliPositional[];
+  /**
+   * JSON Schema for structured stdout (e.g. with `--json` or MCP when the handler emits JSON).
+   * Exported in `docs schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
+   */
+  outputSchema?: Record<string, unknown>;
   /** Per-tool MCP exposure and metadata. */
   mcpTool?: CliMcpToolConfig;
 };
@@ -273,6 +301,11 @@ export function isCliRouter(node: CliNode): node is CliRouter {
   return "commands" in node && Array.isArray(node.commands);
 }
 
+/** Resolves structured stdout schema from the leaf (prefers leaf field over legacy `mcpTool.outputSchema`). */
+export function leafOutputSchema(leaf: CliLeaf): Record<string, unknown> | undefined {
+  return leaf.outputSchema ?? leaf.mcpTool?.outputSchema;
+}
+
 /**
  * Handler closure type for leaf commands.
  * Supports both sync and async handlers.

package/src/validate.ts

@@ -112,6 +112,22 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (isRoot && node.mcpTool !== undefined) {
       throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
     }
+    const outputSchema = node.outputSchema;
+    const legacyOutputSchema = node.mcpTool?.outputSchema;
+    if (outputSchema !== undefined && legacyOutputSchema !== undefined) {
+      throw new CliSchemaValidationError(
+        "Set outputSchema on the leaf only, not under mcpTool",
+      );
+    }
+    const resolved = outputSchema ?? legacyOutputSchema;
+    if (
+      resolved !== undefined &&
+      (typeof resolved !== "object" || resolved === null || Array.isArray(resolved))
+    ) {
+      throw new CliSchemaValidationError(
+        "outputSchema must be a JSON Schema object (not null or an array)",
+      );
+    }
   } else {
     const rogue = node as unknown as CliLeaf;
     if (rogue.mcpTool !== undefined) {