argsbarg 2.1.1 → 3.1.0

package/src/capabilities.ts

@@ -10,23 +10,28 @@ export interface CliCapabilities {
   completion: true;
   mcp: boolean;
   install: boolean;
+  docs: boolean;
 }
 
 /** Resolves which capabilities are enabled for a program. */
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
   return {
     completion: true,
-    mcp: program.mcpServer !== undefined,
+    mcp: program.mcpServer?.enabled === true,
     install: program.install?.enabled !== false,
+    docs: program.docs?.enabled === true,
   };
 }
 
 /** Reserved top-level command names for the given capabilities. */
 export function reservedCommandNames(caps: CliCapabilities): string[] {
-  const names = ["completion"];
+  const names = ["completion", "version"];
   if (caps.install) {
     names.push("install");
   }
+  if (caps.docs) {
+    names.push("docs");
+  }
   if (caps.mcp) {
     names.push("mcp");
   }

package/src/docs/builtin.ts

@@ -0,0 +1,58 @@
+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, "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,121 @@
+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.mcp = { 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("completions offer docs subcommands", () => {
+  const bash = completionBashScript(cliPresentationRoot(docsFixture()));
+  expect(bash).toContain("docs) echo");
+  expect(bash).toContain("readme) 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} --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} --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.",
+    `Run \`${root.key} docs\` for bundled user documentation.`,
+    "",
+  );
+
+  return lines.join("\n");
+}

package/src/docs/resolve.ts

@@ -0,0 +1,88 @@
+import type { CliDocsConfig, CliProgram } from "../types.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 type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
+
+/** Default router description for the `docs` built-in. */
+export const DOCS_ROUTER_DESCRIPTION = "Print bundled CLI documentation.";
+
+/** Returns whether bundled docs are enabled on the program root. */
+export function docsEnabled(program: CliProgram): boolean {
+  return program.docs?.enabled === true;
+}
+
+/** User topic keys in declaration order. */
+export function docsUserTopicKeys(docs: CliDocsConfig): string[] {
+  return Object.keys(docs.topics);
+}
+
+/** Subcommand used when argv is bare `myapp docs`. */
+export function docsEffectiveDefaultTopic(docs: CliDocsConfig): string {
+  if (docs.defaultTopic !== undefined) {
+    return docs.defaultTopic;
+  }
+  const keys = docsUserTopicKeys(docs);
+  if (keys.length === 0) {
+    throw new Error("docs.topics must be non-empty");
+  }
+  return keys[0]!;
+}
+
+/** Whether MCP auto-guide topic is included. */
+export function docsIncludesMcpTopic(program: CliProgram): boolean {
+  return docsEnabled(program) && program.mcpServer?.enabled === true;
+}
+
+/** Leaf help description for a user topic. */
+export function docsTopicDescription(key: string, custom?: string): string {
+  if (custom) {
+    return custom;
+  }
+  if (key === "readme") {
+    return "Print README (user guide).";
+  }
+  const label = key.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `Print ${label} documentation.`;
+}
+
+/** Ordered keys for `docs all` (user topics, then auto `mcp` when enabled). */
+export function docsPrintOrder(program: CliProgram): string[] {
+  const docs = program.docs!;
+  const order = docsUserTopicKeys(docs);
+  if (docsIncludesMcpTopic(program)) {
+    order.push("mcp");
+  }
+  return order;
+}
+
+/** Markdown body for one docs topic key. */
+export function docsTopicText(program: CliProgram, topic: string): string {
+  const docs = program.docs!;
+  if (topic === "mcp") {
+    if (!docsIncludesMcpTopic(program)) {
+      throw new Error("Unknown docs topic 'mcp'.");
+    }
+    return generateMcpGuide(program);
+  }
+  const entry = docs.topics[topic];
+  if (!entry) {
+    throw new Error(`Unknown docs topic '${topic}'.`);
+  }
+  return entry.text;
+}
+
+/** All bundled docs concatenated with horizontal rules. */
+export function combineAllDocs(program: CliProgram): string {
+  return docsPrintOrder(program)
+    .map((key) => docsTopicText(program, key).trim())
+    .join("\n\n---\n\n");
+}
+
+/** Writes one docs topic (or `all`) to stdout. */
+export function printDocsTopic(program: CliProgram, topic: string): void {
+  const content = topic === "all" ? combineAllDocs(program) : docsTopicText(program, topic);
+  process.stdout.write(`${content}\n`);
+}