argsbarg 3.3.13 → 3.4.0

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/skill/generate.ts

@@ -107,14 +107,12 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
   lines.push(
     "## Pitfalls",
     "",
-    "- Use `--` before tokens that look like flags when they are positional arguments.",
-    "- Required environment variables are listed per command above (`requires env`) and in `reference.md`.",
+    "- Pass `--` before arguments that look like flags.",
+    "- Commands marked `[requires env: ...]` need those variables set in the shell.",
     "",
     "## Reference",
     "",
-    "This file is a command index. For full option tables, positionals, notes, and built-ins,",
-    `read \`reference.md\` in this skill directory (same content as \`${root.key} docs api\`).`,
-    "Search for the command path you need before invoking.",
+    `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs api\`).`,
     "",
   );
 

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) {