argsbarg 3.3.13 → 3.4.0

package/src/builtins/presentation.ts

@@ -1,5 +1,6 @@
 import type { CliCapabilities } from "../capabilities.ts";
 import { resolveCapabilities } from "../capabilities.ts";
+import { presentationNode, visibleOptions } from "../hidden.ts";
 import type { CliLeaf, CliNode, CliProgram, CliRouter } from "../types.ts";
 import { isCliLeaf, isCliRouter } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
@@ -8,10 +9,10 @@ import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
-/** Built-in command nodes injected for help, schema, and completions. */
-export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+/** All built-in command nodes for argv parsing (includes hidden builtins). */
+export function parseBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
   const builtins: CliNode[] = [
-    cliBuiltinCompletionGroup(program.key),
+    cliBuiltinCompletionGroup(program),
     cliBuiltinVersionCommand(),
   ];
   if (caps.install) {
@@ -22,14 +23,49 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
     builtins.push(docsGroup);
   }
   if (caps.mcp) {
-    builtins.push(cliBuiltinMcpCommand());
+    builtins.push(cliBuiltinMcpCommand(program));
   }
   return builtins;
 }
 
+/** Built-in subtrees visible in help, schema, and completions (hidden builtins omitted). */
+export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+  return parseBuiltins(program, caps).filter((b) => !b.hidden);
+}
+
+/**
+ * Full command tree for argv parsing, including hidden commands and builtins.
+ * Routing programs merge user commands with builtins; leaf programs wrap builtins only.
+ */
+export function cliParseRoot(program: CliProgram): CliRouter {
+  const caps = resolveCapabilities(program);
+  const builtins = parseBuiltins(program, caps);
+
+  if (isCliLeaf(program)) {
+    return {
+      key: program.key,
+      description: program.description,
+      notes: program.notes,
+      options: program.options,
+      commands: builtins,
+    };
+  }
+
+  return {
+    key: program.key,
+    description: program.description,
+    notes: program.notes,
+    options: program.options,
+    fallbackCommand: program.fallbackCommand,
+    fallbackMode: program.fallbackMode,
+    commands: [...program.commands, ...builtins],
+  };
+}
+
 /**
  * Returns a schema suitable for help display, including capability-built-in subtrees.
- * Routing programs get builtins merged; leaf programs are wrapped as a tiny router.
+ * Hidden commands and options are omitted. Routing programs get builtins merged;
+ * leaf programs are wrapped as a tiny router.
  */
 export function cliPresentationRoot(program: CliProgram): CliRouter {
   const caps = resolveCapabilities(program);
@@ -41,19 +77,23 @@ export function cliPresentationRoot(program: CliProgram): CliRouter {
       key: program.key,
       description: program.description,
       notes,
-      options: program.options,
+      options: visibleOptions(program.options),
       commands: builtins,
     };
   }
 
+  const userCommands = program.commands
+    .map((ch) => presentationNode(ch))
+    .filter((ch): ch is CliNode => ch !== null);
+
   return {
     key: program.key,
     description: program.description,
     notes,
-    options: program.options,
+    options: visibleOptions(program.options),
     fallbackCommand: program.fallbackCommand,
     fallbackMode: program.fallbackMode,
-    commands: [...program.commands, ...builtins],
+    commands: [...userCommands, ...builtins],
   };
 }
 
@@ -64,8 +104,7 @@ export function presentationRootNotes(program: CliProgram, caps: CliCapabilities
     parts.push(program.notes!.trim());
   }
   if (caps.docs) {
-    const cmd = `${program.key} docs skill`;
-    parts.push(`Agents: run \`${cmd}\` to learn how to use this app`);
+    parts.push(`For AI agents: \`${program.key} docs skill\`.`);
   }
   if (parts.length === 0) {
     return undefined;
@@ -75,4 +114,3 @@ export function presentationRootNotes(program: CliProgram, caps: CliCapabilities
 
 /** Presentation tree may include builtin leaf stubs. */
 export type CliPresentationNode = CliNode | CliLeaf;
-

package/src/docs/api-guide.test.ts

@@ -105,3 +105,33 @@ test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   const md = generateApiGuide(fixture);
   expect(md).toContain("Invoke `myapp run`.");
 });
+
+test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
+  const fixture: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    commands: [
+      {
+        key: "run",
+        description: "Run.",
+        outputSchema: {
+          type: "object",
+          properties: { id: { type: "string" } },
+          required: ["id"],
+        },
+        handler: () => {},
+      },
+    ],
+  };
+  const schema = cliSchemaExport(fixture);
+  expect(schema.commands![0]!.outputSchema).toEqual({
+    type: "object",
+    properties: { id: { type: "string" } },
+    required: ["id"],
+  });
+  const md = generateApiGuide(fixture);
+  expect(md).toContain("#### Output");
+  expect(md).toContain('"id"');
+  expect(md).toContain('"type": "string"');
+});

package/src/docs/api-guide.ts

@@ -52,6 +52,20 @@ function formatNotesBlockquote(notes: string, appKey: string): string {
     .join("\n");
 }
 
+/** Markdown section for leaf outputSchema (docs api / skill reference). */
+function formatOutputSchemaSection(schema: Record<string, unknown>): string[] {
+  return [
+    "#### Output",
+    "",
+    "JSON Schema for structured stdout (typically with `--json`, or via MCP when the handler emits JSON):",
+    "",
+    "```json",
+    JSON.stringify(schema, null, 2),
+    "```",
+    "",
+  ];
+}
+
 /** Fallback routing note when present on a router node. */
 function fallbackLine(node: CliSchemaExport): string | null {
   if (node.fallbackCommand === undefined) {
@@ -103,6 +117,10 @@ function renderCommandNode(
     lines.push("");
   }
 
+  if (node.outputSchema !== undefined) {
+    lines.push(...formatOutputSchemaSection(node.outputSchema));
+  }
+
   const children = node.commands ?? [];
   if (children.length > 0) {
     lines.push("#### Subcommands", "");

package/src/docs/builtin.ts

@@ -36,6 +36,11 @@ function docsLeaf(program: CliProgram, key: string, description: string): CliLea
   };
 }
 
+/** Help notes for the `docs` router. */
+function docsRouterNotes(): string {
+  return "Topics print to stdout. Add --save to write files under ./docs/.";
+}
+
 /** Built-in `docs` router with bundled topic subcommands. */
 export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   const docs = program.docs!;
@@ -54,26 +59,14 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
 
   leaves.push(
     docsLeaf(program, "schema", "Print the full command tree as JSON."),
-    docsLeaf(program, "api", "Print the command tree as markdown."),
-    {
-      key: "skill",
-      description: "Print generated SKILL.md (compact command index).",
-      notes: [
-        "Prefer `{argsbarg:program} install --skill --yes` for agents: it persists an optimized skill bundle",
-        "(`SKILL.md` index + `reference.md` full API) to your skill directory.",
-        "`docs skill` prints the index only; use `docs api` or installed `reference.md` for full detail.",
-      ].join(" "),
-      options: [DOCS_SAVE_OPTION],
-      mcpTool: { enabled: false },
-      handler: (ctx) => {
-        runDocsTopic(program, "skill", ctx);
-      },
-    },
+    docsLeaf(program, "api", "Print the full command reference as markdown."),
+    docsLeaf(program, "skill", "Print a reference agent SKILL, use `install --skill` for optimized."),
   );
 
   return {
     key: "docs",
     description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
+    notes: docsRouterNotes(),
     options: [DOCS_SAVE_OPTION],
     fallbackCommand: docsEffectiveDefaultTopic(docs),
     fallbackMode: CliFallbackMode.MissingOnly,

package/src/docs/docs.test.ts

@@ -153,7 +153,7 @@ test("docs skill prints Cursor SKILL.md", async () => {
   expect(result.stdout).toContain("---");
   expect(result.stdout).toContain("name: myapp");
   expect(result.stdout).toContain("## Commands");
-  expect(result.stdout).toContain("read `reference.md`");
+  expect(result.stdout).toContain("For full detail, open `reference.md`");
   expect(result.stdout).not.toContain("#### Options");
   expect(result.stdout).not.toContain("mcp.json");
 });
@@ -164,9 +164,11 @@ test("docs skill help recommends install --skill", async () => {
   expect(docsNode && "commands" in docsNode).toBe(true);
   if (docsNode && "commands" in docsNode) {
     const skill = docsNode.commands.find((c) => c.key === "skill");
-    expect(skill?.description).toContain("compact command index");
-    expect(skill?.notes).toContain("install --skill --yes");
-    expect(skill?.notes).toContain("reference.md");
+    expect(skill?.description).toContain("reference agent SKILL");
+    expect(skill?.description).toContain("install --skill");
+    expect(skill?.notes).toBeUndefined();
+    expect(docsNode.notes).toContain("--save");
+    expect(docsNode.notes).not.toContain("install --skill");
   }
 });
 

package/src/help.ts

@@ -8,6 +8,7 @@ style no matter how help is reached.
 */
 
 import { CliNode, CliOption, CliOptionKind, CliPositional, CliRouter, isCliLeaf, isCliRouter } from "./types.ts";
+import { visibleOptions, visibleSubcommands } from "./hidden.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
 
@@ -372,9 +373,9 @@ function rowsForPositionals(defs: CliPositional[], color: boolean): HelpRow[] {
   return defs.map((p) => ({ label: cliPositionalLabel(p, color), description: p.description }));
 }
 
-/** Table rows for subcommands, sorted by key. */
+/** Table rows for subcommands, sorted by key (hidden commands omitted). */
 function rowsForSubcommands(cmds: CliNode[]): HelpRow[] {
-  return cmds
+  return visibleSubcommands(cmds)
     .sort((a, b) => a.key.localeCompare(b.key))
     .map((c) => ({ label: c.key, description: c.description }));
 }
@@ -420,7 +421,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color), hw, color);
+    const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(schema.options), color), hw, color);
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -470,7 +471,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color), hw, color);
+  const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(node.options), color), hw, color);
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));

package/src/hidden-mcpb.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { cliPresentationRoot, cliParseRoot } from "./builtins/presentation.ts";
+import { exportPresentationBuiltins } from "./builtins/export.ts";
+import { cliHelpRender } from "./help.ts";
+import { cliSchemaExport } from "./schema.ts";
+import { collectMcpTools } from "./mcp/tools.ts";
+import { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+import { CliOptionKind, type CliProgram } from "./types.ts";
+
+const hiddenFixture: CliProgram = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "Hidden demo.",
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "public",
+      description: "Visible command.",
+      handler: () => {},
+    },
+    {
+      key: "secret",
+      hidden: true,
+      description: "Hidden command.",
+      handler: () => {},
+    },
+    {
+      key: "flags",
+      description: "Command with hidden option.",
+      options: [
+        {
+          name: "visible",
+          description: "Shown in help.",
+          kind: CliOptionKind.Presence,
+        },
+        {
+          name: "secret-flag",
+          hidden: true,
+          description: "Hidden option.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
+      handler: () => {},
+    },
+  ],
+};
+
+describe("hidden commands and options", () => {
+  test("parse root includes hidden commands", () => {
+    const parse = cliParseRoot(hiddenFixture);
+    expect(parse.commands?.map((c) => c.key)).toContain("secret");
+  });
+
+  test("presentation root omits hidden commands", () => {
+    const presentation = cliPresentationRoot(hiddenFixture);
+    const keys = presentation.commands?.map((c) => c.key) ?? [];
+    expect(keys).toContain("public");
+    expect(keys).not.toContain("secret");
+  });
+
+  test("root help omits hidden commands", () => {
+    const help = cliHelpRender(cliParseRoot(hiddenFixture), [], false);
+    expect(help).toContain("public");
+    expect(help).not.toContain("secret");
+  });
+
+  test("hidden command -h still works", () => {
+    const help = cliHelpRender(cliParseRoot(hiddenFixture), ["secret"], false);
+    expect(help).toContain("Hidden command.");
+  });
+
+  test("help omits hidden options", () => {
+    const help = cliHelpRender(cliParseRoot(hiddenFixture), ["flags"], false);
+    expect(help).toContain("--visible");
+    expect(help).not.toContain("secret-flag");
+  });
+
+  test("schema export omits hidden nodes and options", () => {
+    const schema = cliSchemaExport(hiddenFixture);
+    const keys = schema.commands?.map((c) => c.key) ?? [];
+    expect(keys).toContain("public");
+    expect(keys).not.toContain("secret");
+    const flags = schema.commands?.find((c) => c.key === "flags");
+    expect(flags?.options?.map((o) => o.name)).toEqual(["visible"]);
+  });
+
+  test("MCP tools omit hidden commands", () => {
+    const tools = collectMcpTools(hiddenFixture);
+    expect(tools.map((t) => t.name)).toEqual(["public", "flags"]);
+  });
+});
+
+describe("mcp router", () => {
+  test("presentation exposes mcp bundle but not hidden serve", () => {
+    const builtins = exportPresentationBuiltins(hiddenFixture);
+    const mcp = builtins.find((b) => b.key === "mcp");
+    expect(mcp).toBeDefined();
+    expect(mcp?.commands?.map((c) => c.key)).toEqual(["bundle"]);
+    expect(mcp?.fallbackCommand).toBe("serve");
+  });
+
+  test("mcp help lists bundle", () => {
+    const help = cliHelpRender(cliParseRoot(hiddenFixture), ["mcp"], false);
+    expect(help).toContain("bundle");
+    expect(help).not.toMatch(/│ serve\s/);
+  });
+});
+
+describe("mcp bundle", () => {
+  test("generateMcpManifest uses mcpServerId and binary entry", () => {
+    const manifest = generateMcpManifest(hiddenFixture, "myapp");
+    expect(manifest.name).toBe("myapp");
+    expect(manifest.manifest_version).toBe("0.3");
+    expect((manifest.server as { type: string }).type).toBe("binary");
+    expect((manifest.server as { entry_point: string }).entry_point).toBe("myapp");
+    const mcpConfig = (manifest.server as { mcp_config: { command: string; args: string[] } }).mcp_config;
+    expect(mcpConfig.command).toBe("${__dirname}/myapp");
+    expect(mcpConfig.args).toEqual(["mcp"]);
+    expect((manifest.compatibility as { platforms: string[] }).platforms).toEqual(["darwin"]);
+  });
+
+  test("defaultMcpBundlePaths", () => {
+    const cwd = "/tmp/work";
+    const paths = defaultMcpBundlePaths(hiddenFixture, cwd);
+    expect(paths.binaryPath).toBe(join(cwd, "dist", "myapp"));
+    expect(paths.outPath).toBe(join(cwd, "dist", "myapp.mcpb"));
+  });
+
+  test("packMcpBundle writes zip with manifest and binary on darwin", () => {
+    if (process.platform !== "darwin") {
+      return;
+    }
+    const work = mkdtempSync(join(tmpdir(), "mcpb-test-"));
+    try {
+      const dist = join(work, "dist");
+      mkdirSync(dist, { recursive: true });
+      const binaryPath = join(dist, "myapp");
+      writeFileSync(binaryPath, "#!/bin/sh\necho hi\n", { mode: 0o755 });
+
+      const outPath = packMcpBundle(hiddenFixture, { cwd: work });
+      expect(outPath).toBe(join(dist, "myapp.mcpb"));
+
+      const zip = readFileSync(outPath);
+      expect(zip.length).toBeGreaterThan(0);
+      expect(zip.indexOf(Buffer.from("manifest.json"))).toBeGreaterThanOrEqual(0);
+      expect(zip.indexOf(Buffer.from("myapp"))).toBeGreaterThanOrEqual(0);
+    } finally {
+      rmSync(work, { recursive: true, force: true });
+    }
+  });
+});

package/src/hidden.ts

@@ -0,0 +1,32 @@
+/*
+Filters hidden commands and options from presentation surfaces (help, schema, completions).
+Parsing still uses the full tree via cliParseRoot.
+*/
+
+import type { CliNode, CliOption, CliRouter } from "./types.ts";
+import { isCliLeaf, isCliRouter } from "./types.ts";
+
+/** Options visible in help, schema, completions, and MCP tool schemas. */
+export function visibleOptions(options: CliOption[] | undefined): CliOption[] {
+  return (options ?? []).filter((o) => !o.hidden);
+}
+
+/** Strips hidden commands and options from one node for presentation export. */
+export function presentationNode(node: CliNode): CliNode | null {
+  if (node.hidden) {
+    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 (parent may be any node in the parse tree). */
+export function visibleSubcommands(cmds: CliNode[]): CliNode[] {
+  return cmds.filter((c) => !c.hidden);
+}