argsbarg 3.0.0 → 3.2.0

package/src/builtins/presentation.ts

@@ -5,7 +5,9 @@ import { isCliLeaf, isCliRouter } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinUpdateCommand } from "./update.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[] {
@@ -16,6 +18,13 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
   if (caps.install) {
     builtins.push(cliBuiltinInstallCommand(program));
   }
+  if (caps.update) {
+    builtins.push(cliBuiltinUpdateCommand(program));
+  }
+  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
+  if (docsGroup) {
+    builtins.push(docsGroup);
+  }
   if (caps.mcp) {
     builtins.push(cliBuiltinMcpCommand());
   }

package/src/builtins/shell-helpers.ts

@@ -20,5 +20,3 @@ export function mainName(schemaName: string): string {
 
 export const kHelpLong = "--help";
 export const kHelpShort = "-h";
-export const kSchemaLong = "--schema";
-export const kSchemaDesc = "Print the full command tree as JSON.";

package/src/builtins/update.ts

@@ -0,0 +1,14 @@
+import type { CliLeaf, CliProgram } from "../types.ts";
+import { cliUpdate } from "../install/update.ts";
+
+/** Built-in `update` command (enabled when `install.updateGetLatest` is set). */
+export function cliBuiltinUpdateCommand(program: CliProgram): CliLeaf {
+  return {
+    key: "update",
+    description: "Download and install the latest release.",
+    mcpTool: { enabled: false },
+    handler: async () => {
+      await cliUpdate(program);
+    },
+  };
+}

package/src/capabilities.ts

@@ -10,14 +10,19 @@ export interface CliCapabilities {
   completion: true;
   mcp: boolean;
   install: boolean;
+  docs: boolean;
+  update: boolean;
 }
 
 /** Resolves which capabilities are enabled for a program. */
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
+  const install = program.install?.enabled !== false;
   return {
     completion: true,
     mcp: program.mcpServer?.enabled === true,
-    install: program.install?.enabled !== false,
+    install,
+    docs: program.docs?.enabled === true,
+    update: install && typeof program.install?.updateGetLatest === "function",
   };
 }
 
@@ -27,6 +32,12 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.install) {
     names.push("install");
   }
+  if (caps.update) {
+    names.push("update");
+  }
+  if (caps.docs) {
+    names.push("docs");
+  }
   if (caps.mcp) {
     names.push("mcp");
   }

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

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import { CliOptionKind } from "../types.ts";
+import { generateApiGuide } from "./api-guide.ts";
+import { cliSchemaExport } from "../schema.ts";
+
+const nestedFixture: CliProgram = {
+  key: "nested.ts",
+  version: "1.0.0",
+  description: "Nested groups demo.",
+  docs: { enabled: true, topics: { readme: { text: "# readme\n" } } },
+  commands: [
+    {
+      key: "stat",
+      description: "File metadata.",
+      commands: [
+        {
+          key: "owner",
+          description: "Ownership helpers.",
+          commands: [
+            {
+              key: "lookup",
+              description: "Resolve owner info.",
+              options: [
+                {
+                  name: "user-name",
+                  description: "User to look up.",
+                  kind: CliOptionKind.String,
+                  shortName: "u",
+                },
+              ],
+              positionals: [
+                {
+                  name: "path",
+                  description: "File or directory.",
+                  kind: CliOptionKind.String,
+                },
+              ],
+              handler: () => {},
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
+  const md = generateApiGuide(nestedFixture);
+  const schema = cliSchemaExport(nestedFixture);
+  expect(md).toContain("`nested.ts stat owner lookup`");
+  expect(md).toContain("`--user-name` (`-u`)");
+  expect(md).toContain("`<path>`");
+  expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
+});

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

@@ -0,0 +1,61 @@
+import { CliFallbackMode, type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
+import {
+  DOCS_ROUTER_DESCRIPTION,
+  docsEffectiveDefaultTopic,
+  docsEnabled,
+  docsIncludesMcpTopic,
+  docsTopicDescription,
+  docsUserTopicKeys,
+  printDocsTopic,
+} from "./resolve.ts";
+
+function docsLeaf(program: CliProgram, key: string, description: string): CliLeaf {
+  return {
+    key,
+    description,
+    mcpTool: { enabled: false },
+    handler: () => {
+      printDocsTopic(program, key);
+    },
+  };
+}
+
+/** Built-in `docs` router with bundled topic subcommands. */
+export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
+  const docs = program.docs!;
+  const leaves: CliLeaf[] = [];
+
+  for (const key of docsUserTopicKeys(docs)) {
+    const topic = docs.topics[key]!;
+    leaves.push(docsLeaf(program, key, docsTopicDescription(key, topic.description)));
+  }
+
+  if (docsIncludesMcpTopic(program)) {
+    leaves.push(
+      docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."),
+    );
+  }
+
+  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."),
+  );
+
+  return {
+    key: "docs",
+    description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
+    fallbackCommand: docsEffectiveDefaultTopic(docs),
+    fallbackMode: CliFallbackMode.MissingOnly,
+    commands: leaves,
+  };
+}
+
+/** Returns the docs built-in when enabled. */
+export function cliBuiltinDocsGroupIfEnabled(program: CliProgram): CliRouter | null {
+  if (!docsEnabled(program)) {
+    return null;
+  }
+  return cliBuiltinDocsGroup(program);
+}

package/src/docs/docs.test.ts

@@ -0,0 +1,167 @@
+import { expect, test } from "bun:test";
+import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { completionBashScript } from "../completion.ts";
+import { cliInvoke } from "../index.ts";
+import type { CliProgram } from "../types.ts";
+import { cliValidateProgram } from "../validate.ts";
+import { combineAllDocs, docsEffectiveDefaultTopic } from "./resolve.ts";
+import { generateMcpGuide } from "./mcp-guide.ts";
+
+function docsFixture(mcp = true): CliProgram {
+  return {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    mcpServer: mcp ? { enabled: true } : undefined,
+    docs: {
+      enabled: true,
+      topics: {
+        readme: { text: "# Hello README\n" },
+        arch: { text: "# Architecture\n", description: "Contributor notes." },
+      },
+    },
+    commands: [
+      {
+        key: "run",
+        description: "Run something.",
+        handler: () => {},
+      },
+    ],
+  };
+}
+
+test("docs reserved when enabled", () => {
+  const root: CliProgram = {
+    ...docsFixture(),
+    commands: [
+      {
+        key: "docs",
+        description: "conflict",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: docs/);
+});
+
+test("docs rejects reserved topic keys", () => {
+  const root = docsFixture();
+  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/);
+});
+
+test("docsEffectiveDefaultTopic uses first topic key", () => {
+  expect(docsEffectiveDefaultTopic(docsFixture().docs!)).toBe("readme");
+});
+
+test("bare docs prints first topic via cliInvoke", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Hello README");
+});
+
+test("docs readme prints bundled text", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "readme"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Hello README");
+});
+
+test("docs defaultTopic override", async () => {
+  const root = docsFixture();
+  root.docs!.defaultTopic = "arch";
+  const result = await cliInvoke(root, ["docs"]);
+  expect(result.stdout).toContain("Architecture");
+});
+
+test("docs mcp when MCP enabled", async () => {
+  const result = await cliInvoke(docsFixture(true), ["docs", "mcp"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("MCP server (myapp)");
+  expect(result.stdout).toContain("myapp mcp");
+});
+
+test("docs mcp absent from router when MCP disabled", async () => {
+  const root = docsFixture(false);
+  const presentation = cliPresentationRoot(root);
+  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 === "mcp")).toBe(false);
+  }
+  const result = await cliInvoke(root, ["docs", "mcp"]);
+  expect(result.exitCode).not.toBe(0);
+});
+
+test("docs all concatenates user topics and mcp", () => {
+  const program = docsFixture(true);
+  const combined = combineAllDocs(program);
+  expect(combined).toContain("Hello README");
+  expect(combined).toContain("Architecture");
+  expect(combined).toContain("MCP server (myapp)");
+});
+
+test("presentation includes docs subtree", () => {
+  const presentation = cliPresentationRoot(docsFixture());
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode).toBeDefined();
+  expect(docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme")).toBe(
+    true,
+  );
+});
+
+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", () => {
+  const guide = generateMcpGuide(docsFixture(true));
+  expect(guide).toContain("myapp://schema");
+});

package/src/docs/mcp-guide.ts

@@ -0,0 +1,118 @@
+import { collectOptionDefs } from "../parse.ts";
+import {
+  collectMcpTools,
+  mcpServerId,
+  resolveMcpSchemaUri,
+  type McpToolDef,
+} from "../mcp/tools.ts";
+import { type CliProgram, CliOptionKind } from "../types.ts";
+
+/** Formats one exposed MCP tool for the auto-generated MCP guide. */
+function formatToolLine(root: CliProgram, tool: McpToolDef): string {
+  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
+  let line = `- \`${cliPath}\` — ${tool.description}`;
+  const opts = collectOptionDefs(root, tool.path);
+  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
+  if (flags.length > 0) {
+    line += ` (flags: ${flags.join(", ")})`;
+  }
+  return line;
+}
+
+/** Generates the auto `docs mcp` markdown guide from schema and MCP config. */
+export function generateMcpGuide(root: CliProgram): string {
+  const tools = collectMcpTools(root);
+  const schemaUri = resolveMcpSchemaUri(root);
+  const serverId = mcpServerId(root);
+  const mcp = root.mcpServer!;
+
+  const lines: string[] = [
+    `# MCP server (${root.key})`,
+    "",
+    `${root.key} exposes an MCP server via argsbarg. Each exposed leaf command becomes an MCP tool.`,
+    "",
+    "## Quick start",
+    "",
+    "```bash",
+    `${root.key} mcp`,
+    "```",
+    "",
+    "Cursor / Claude `mcp.json` entry:",
+    "",
+    "```json",
+    JSON.stringify(
+      {
+        mcpServers: {
+          [serverId]: {
+            command: root.key,
+            args: ["mcp"],
+          },
+        },
+      },
+      null,
+      2,
+    ),
+    "```",
+    "",
+    "Or run:",
+    "",
+    "```bash",
+    `${root.key} install --mcp --yes`,
+    "```",
+    "",
+  ];
+
+  if (mcp.shellEnv || mcp.envFile) {
+    lines.push("## Environment", "");
+    if (mcp.shellEnv) {
+      lines.push(
+        "- **`shellEnv`** — captures login-shell environment at MCP startup (PATH, toolchain shims, exports).",
+      );
+    }
+    if (mcp.envFile) {
+      lines.push(
+        "- **`envFile`** — loads `" + mcp.envFile + "` after shell env (overrides for its keys).",
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## What agents get",
+    "",
+    "| Mechanism | Purpose |",
+    "|-----------|---------|",
+    "| `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} docs schema\` |`,
+    "",
+    "## Exposed tools",
+    "",
+  );
+
+  if (tools.length === 0) {
+    lines.push("(No MCP tools exposed.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatToolLine(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Tool arguments",
+    "",
+    "Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
+    `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 `docs schema` are not available through tool calls.",
+    `Run \`${root.key} docs\` for bundled user documentation.`,
+    "",
+  );
+
+  return lines.join("\n");
+}