argsbarg 3.1.0 → 3.2.0

package/src/docs/api-guide.ts

@@ -0,0 +1,129 @@
+import type { CliSchemaExport } from "../builtins/export.ts";
+import { cliPositionalLabel } from "../help.ts";
+import { cliSchemaExport } from "../schema.ts";
+import type { CliOption, CliPositional, CliProgram } from "../types.ts";
+import { CliFallbackMode, CliOptionKind } from "../types.ts";
+
+/** CLI invocation path as a single string (`myapp stat owner lookup`). */
+function commandPath(rootKey: string, path: string[]): string {
+  if (path.length === 0) {
+    return rootKey;
+  }
+  return [rootKey, ...path].join(" ");
+}
+
+/** Human-readable option type for API tables. */
+function optionType(opt: CliOption): string {
+  if (opt.kind === CliOptionKind.Presence) {
+    return "flag";
+  }
+  if (opt.kind === CliOptionKind.Enum) {
+    return `enum (\`${(opt.choices ?? []).join("`, `")}\`)`;
+  }
+  return opt.kind;
+}
+
+/** Markdown table cell for one option flag. */
+function optionLabel(opt: CliOption): string {
+  const long = `\`--${opt.name}\``;
+  const short = opt.shortName ? ` (\`-${opt.shortName}\`)` : "";
+  return `${long}${short}`;
+}
+
+/** One options table row. */
+function formatOptionRow(opt: CliOption): string {
+  const req = opt.required ? "required" : "optional";
+  return `| ${optionLabel(opt)} | ${optionType(opt)} | ${req} | ${opt.description} |`;
+}
+
+/** One positionals table row. */
+function formatPositionalRow(p: CliPositional): string {
+  const label = cliPositionalLabel(p, false);
+  const req = (p.argMin ?? 1) > 0 ? "required" : "optional";
+  return `| \`${label}\` | ${p.kind} | ${req} | ${p.description} |`;
+}
+
+/** Fallback routing note when present on a router node. */
+function fallbackLine(node: CliSchemaExport): string | null {
+  if (node.fallbackCommand === undefined) {
+    return null;
+  }
+  const mode = node.fallbackMode ?? CliFallbackMode.MissingOnly;
+  return `**Default subcommand:** \`${node.fallbackCommand}\` (\`${mode}\`)`;
+}
+
+/** Renders one command node and recurses into subcommands. */
+function renderCommandNode(
+  rootKey: string,
+  path: string[],
+  node: CliSchemaExport,
+  lines: string[],
+): void {
+  const level = Math.min(path.length + 2, 6);
+  const heading = "#".repeat(level);
+  const cmd = commandPath(rootKey, path);
+
+  lines.push(`${heading} \`${cmd}\``, "", node.description, "");
+
+  if (node.notes) {
+    lines.push(`> ${node.notes}`, "");
+  }
+
+  const fb = fallbackLine(node);
+  if (fb) {
+    lines.push(fb, "");
+  }
+
+  if ((node.options ?? []).length > 0) {
+    lines.push("#### Options", "");
+    lines.push("| Option | Type | Required | Description |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const opt of node.options!) {
+      lines.push(formatOptionRow(opt));
+    }
+    lines.push("");
+  }
+
+  if ((node.positionals ?? []).length > 0) {
+    lines.push("#### Positionals", "");
+    lines.push("| Argument | Type | Required | Description |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const p of node.positionals!) {
+      lines.push(formatPositionalRow(p));
+    }
+    lines.push("");
+  }
+
+  const children = node.commands ?? [];
+  if (children.length > 0) {
+    lines.push("#### Subcommands", "");
+    for (const child of children) {
+      lines.push(`- \`${child.key}\` — ${child.description}`);
+    }
+    lines.push("");
+  }
+
+  for (const child of children) {
+    renderCommandNode(rootKey, [...path, child.key], child, lines);
+  }
+}
+
+/** Generates markdown API reference from the same export as `docs schema`. */
+export function generateApiGuide(program: CliProgram): string {
+  const schema = cliSchemaExport(program);
+  const lines: string[] = [
+    `# ${program.key} — CLI API reference`,
+    "",
+    schema.description,
+    "",
+    `Machine-readable export: \`${program.key} docs schema\``,
+    "",
+  ];
+
+  if (schema.notes) {
+    lines.push(`> ${schema.notes}`, "");
+  }
+
+  renderCommandNode(program.key, [], schema, lines);
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/docs/builtin.ts

@@ -37,6 +37,9 @@ 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."),
+    docsLeaf(program, "skill", "Print generated Cursor SKILL.md content."),
     docsLeaf(program, "all", "Print all bundled documentation combined."),
   );
 

package/src/docs/docs.test.ts

@@ -46,7 +46,13 @@ test("docs reserved when enabled", () => {
 
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
-  root.docs!.topics.mcp = { text: "nope" };
+  root.docs!.topics.schema = { text: "nope" };
+  expect(() => cliValidateProgram(root)).toThrow(/reserved/);
+  delete root.docs!.topics.schema;
+  root.docs!.topics.skill = { text: "nope" };
+  expect(() => cliValidateProgram(root)).toThrow(/reserved/);
+  delete root.docs!.topics.skill;
+  root.docs!.topics.api = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
@@ -109,10 +115,50 @@ test("presentation includes docs subtree", () => {
   );
 });
 
+test("docs schema prints JSON", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "schema"]);
+  expect(result.exitCode).toBe(0);
+  const schema = JSON.parse(result.stdout);
+  expect(schema.key).toBe("myapp");
+  expect(schema.commands.some((c: { key: string }) => c.key === "run")).toBe(true);
+});
+
+test("docs api prints markdown reference", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "api"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("# myapp — CLI API reference");
+  expect(result.stdout).toContain("## `myapp run`");
+  expect(result.stdout).toContain("Run something.");
+  expect(result.stdout).toContain("myapp docs schema");
+});
+
+test("docs skill prints Cursor SKILL.md", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "skill"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("---");
+  expect(result.stdout).toContain("name: myapp");
+  expect(result.stdout).toContain("## Commands");
+  expect(result.stdout).not.toContain("mcp.json");
+});
+
+test("presentation includes docs schema and skill", () => {
+  const presentation = cliPresentationRoot(docsFixture());
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode && "commands" in docsNode).toBe(true);
+  if (docsNode && "commands" in docsNode) {
+    expect(docsNode.commands.some((c) => c.key === "schema")).toBe(true);
+    expect(docsNode.commands.some((c) => c.key === "api")).toBe(true);
+    expect(docsNode.commands.some((c) => c.key === "skill")).toBe(true);
+  }
+});
+
 test("completions offer docs subcommands", () => {
   const bash = completionBashScript(cliPresentationRoot(docsFixture()));
   expect(bash).toContain("docs) echo");
   expect(bash).toContain("readme) echo");
+  expect(bash).toContain("schema) echo");
+  expect(bash).toContain("api) echo");
+  expect(bash).toContain("skill) echo");
 });
 
 test("generateMcpGuide includes schema URI", () => {

package/src/docs/mcp-guide.ts

@@ -84,7 +84,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "|-----------|---------|",
     "| `tools/list` | Callable tools for exposed leaf commands |",
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
-    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} --schema\` |`,
+    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs schema\` |`,
     "",
     "## Exposed tools",
     "",
@@ -103,13 +103,13 @@ export function generateMcpGuide(root: CliProgram): string {
     "## Tool arguments",
     "",
     "Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
-    `See \`${root.key} --schema\` or the schema resource for per-tool shapes.`,
+    `See \`${root.key} docs schema\` or the schema resource for per-tool shapes.`,
     "",
     "Varargs positionals accept a JSON array or a comma-separated string.",
     "",
     "## Protocol",
     "",
-    "Stdio NDJSON JSON-RPC. Help and `--schema` are not available through tool calls.",
+    "Stdio NDJSON JSON-RPC. Help and `docs schema` are not available through tool calls.",
     `Run \`${root.key} docs\` for bundled user documentation.`,
     "",
   );

package/src/docs/resolve.ts

@@ -1,8 +1,11 @@
 import type { CliDocsConfig, CliProgram } from "../types.ts";
+import { cliSchemaJson } from "../schema.ts";
+import { generateSkillBundle } from "../skill/generate.ts";
+import { generateApiGuide } from "./api-guide.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
 
 /** Built-in docs subcommand keys not allowed in `docs.topics`. */
-export const DOCS_BUILTIN_TOPIC_KEYS = ["mcp", "all"] as const;
+export const DOCS_BUILTIN_TOPIC_KEYS = ["mcp", "all", "schema", "api", "skill"] as const;
 
 export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
 
@@ -81,8 +84,36 @@ export function combineAllDocs(program: CliProgram): string {
     .join("\n\n---\n\n");
 }
 
+/** Writes CLI schema JSON to stdout (`docs schema`). */
+export function printDocsSchema(program: CliProgram): void {
+  process.stdout.write(cliSchemaJson(program));
+}
+
+/** Writes markdown API reference to stdout (`docs api`). */
+export function printDocsApi(program: CliProgram): void {
+  process.stdout.write(generateApiGuide(program));
+}
+
+/** Writes generated Cursor SKILL.md to stdout (`docs skill`). */
+export function printDocsSkill(program: CliProgram): void {
+  const bundle = generateSkillBundle(program, "cursor");
+  process.stdout.write(`${bundle.skillMd}\n`);
+}
+
 /** Writes one docs topic (or `all`) to stdout. */
 export function printDocsTopic(program: CliProgram, topic: string): void {
+  if (topic === "schema") {
+    printDocsSchema(program);
+    return;
+  }
+  if (topic === "api") {
+    printDocsApi(program);
+    return;
+  }
+  if (topic === "skill") {
+    printDocsSkill(program);
+    return;
+  }
   const content = topic === "all" ? combineAllDocs(program) : docsTopicText(program, topic);
   process.stdout.write(`${content}\n`);
 }

package/src/help.ts

@@ -346,16 +346,12 @@ function usageLines(
 }
 
 /** Table rows for named options, including synthetic built-in rows. */
-function rowsForOptions(defs: CliOption[], color: boolean, isRoot: boolean): HelpRow[] {
+function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
   const helpLabel = color
     ? style.aquaBold("--help, ") + style.greenBright("-h")
     : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
-  if (isRoot) {
-    const schemaLabel = color ? style.aquaBold("--schema") : "--schema";
-    rows.push({ label: schemaLabel, description: "Print the full command tree as JSON." });
-  }
   for (const o of defs) {
     const desc = o.required ? "(required) " + o.description : o.description;
     rows.push({ label: cliOptionLabel(o, color), description: desc });
@@ -401,7 +397,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color, true), hw, color);
+    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color), hw, color);
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -450,7 +446,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color, false), hw, color);
+  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color), hw, color);
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));

package/src/index.test.ts

@@ -500,8 +500,8 @@ test("leaf completion help prints correctly", async () => {
   expect(stderr.toString()).toBe("");
 });
 
-test("--schema exports JSON for nested CLIs", async () => {
-  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts --schema`.nothrow().quiet();
+test("docs schema exports JSON for nested CLIs", async () => {
+  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
   expect(stderr.toString()).toBe("");
 
@@ -516,15 +516,20 @@ test("--schema exports JSON for nested CLIs", async () => {
   expect(lookup.positionals[0].name).toBe("path");
 });
 
-test("--schema exports JSON for leaf roots", async () => {
-  const { stdout, exitCode } = await $`bun run examples/minimal.ts --schema`.nothrow().quiet();
+test("docs schema exports JSON for leaf roots", async () => {
+  const { stdout, exitCode } = await $`bun run examples/minimal.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
 
   const schema = JSON.parse(stdout.toString());
   expect(schema.key).toBe("minimal.ts");
   expect(schema.positionals[0].name).toBe("name");
   expect(schema.options[0].name).toBe("verbose");
-  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual(["completion", "version", "install"]);
+  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual([
+    "completion",
+    "version",
+    "install",
+    "docs",
+  ]);
 });
 
 test("version builtin prints program version", async () => {
@@ -540,10 +545,15 @@ test("leaf root help lists completion built-in", async () => {
   expect(stdout.toString()).toContain("Generate the autocompletion script for shells.");
 });
 
-test("parse recognizes --schema at the program root", () => {
-  const root= testProgram({
+test("root --schema is no longer a flag", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
     commands: [
       {
         key: "x",
@@ -553,8 +563,8 @@ test("parse recognizes --schema at the program root", () => {
     ],
   });
   cliValidateProgram(root);
-  const pr = parse(root, ["--schema"]);
-  expect(pr.kind).toBe(ParseKind.Schema);
+  const pr = parse(cliPresentationRoot(root), ["--schema"]);
+  expect(pr.kind).not.toBe(ParseKind.Ok);
 });
 
 test("cliSchemaJson omits handlers and completion built-ins", () => {
@@ -587,32 +597,15 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
   expect(schema).not.toHaveProperty("handler");
 });
 
-test("reserved option name schema is rejected", () => {
-  const root= testProgram({
-    key: "app",
-    description: "",
-    commands: [
-      {
-        key: "x",
-        description: "cmd",
-        options: [
-          {
-            name: "schema",
-            description: "",
-            kind: CliOptionKind.String,
-          },
-        ],
-        handler: () => {},
-      },
-    ],
-  });
-  expect(() => cliValidateProgram(root)).toThrow(/reserved for --schema/);
-});
-
-test("root help lists --schema built-in", () => {
-  const root= testProgram({
+test("docs help lists schema, api, and skill subcommands", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
     commands: [
       {
         key: "x",
@@ -621,14 +614,19 @@ test("root help lists --schema built-in", () => {
       },
     ],
   });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).toContain("--schema");
+  const help = cliHelpRender(cliPresentationRoot(root), ["docs"], false);
+  expect(help).toContain("schema");
   expect(help).toContain("Print the full command tree as JSON.");
+  expect(help).toContain("api");
+  expect(help).toContain("markdown");
+  expect(help).toContain("skill");
+  expect(help).toContain("SKILL.md");
 });
 
-test("nested help omits --schema built-in", () => {
-  const root= testProgram({
+test("root help omits legacy --schema flag", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
     commands: [
       {
@@ -638,37 +636,10 @@ test("nested help omits --schema built-in", () => {
       },
     ],
   });
-  const help = cliHelpRender(cliPresentationRoot(root), ["x"], false);
+  const help = cliHelpRender(cliPresentationRoot(root), [], false);
   expect(help).not.toContain("--schema");
 });
 
-test("completion scripts offer --schema at the program root only", () => {
-  const root= testProgram({
-    key: "myapp",
-    description: "",
-    commands: [
-      {
-        key: "stat",
-        description: "stats",
-        commands: [
-          {
-            key: "show",
-            description: "show",
-            handler: () => {},
-          },
-        ],
-      },
-    ],
-  });
-
-  const bash = completionBashScript(cliPresentationRoot(root));
-  expect(bash).toContain("A_myapp_0_opts+=('--schema')");
-  expect(bash).not.toContain("A_myapp_1_opts+=('--schema')");
-
-  const zsh = completionZshScript(cliPresentationRoot(root));
-  expect(zsh).toContain("'--schema:Print the full command tree as JSON.'");
-});
-
 const nestedMcpFixture = testProgram({
   key: "nested.ts",
   description: "Nested groups demo.",

package/src/index.ts

@@ -20,6 +20,8 @@ export type {
   CliMcpServerConfig,
   CliMcpToolConfig,
   CliInstallConfig,
+  CliUpdateArtifact,
+  CliUpdateGetLatest,
   CliDocsConfig,
   CliDocsTopic,
   CliOption,

package/src/install/binary.ts

@@ -16,8 +16,13 @@ export interface BinaryInstallResult {
   patchedZshRc: boolean;
 }
 
-/** Copies the running binary to the install path and patches rc files when shells are detected. */
-export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolean): BinaryInstallResult {
+/** Copies a binary to the install path and patches rc files when shells are detected. */
+export function installBinary(
+  root: CliProgram,
+  paths: InstallPaths,
+  dry: boolean,
+  sourcePath: string = process.execPath,
+): BinaryInstallResult {
   const changed: string[] = [];
   const shells = detectShells();
   let patchedBashRc = false;
@@ -25,7 +30,7 @@ export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolea
 
   if (!dry) {
     mkdirSync(paths.bindir, { recursive: true });
-    copyFileSync(process.execPath, paths.binaryPath);
+    copyFileSync(sourcePath, paths.binaryPath);
   }
   changed.push(paths.binaryPath);