argsbarg 2.1.1 → 3.1.0

package/src/index.ts

@@ -20,6 +20,8 @@ export type {
   CliMcpServerConfig,
   CliMcpToolConfig,
   CliInstallConfig,
+  CliDocsConfig,
+  CliDocsTopic,
   CliOption,
   CliPositional,
 } from "./types.ts";

package/src/install/index.ts

@@ -1,4 +1,5 @@
 import { readSync } from "node:fs";
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { cliSkillInstall } from "../skill/install.ts";
 import { checkMcpConflict, expectedMcpEntry } from "./mcp-config.ts";
@@ -130,7 +131,7 @@ export async function cliInstall(root: CliProgram, rawOpts: Record<string, strin
   }
 
   // MCP conflict checks before planning
-  if (!opts.uninstall && root.mcpServer && (opts.all || opts.mcp)) {
+  if (!opts.uninstall && resolveCapabilities(root).mcp && (opts.all || opts.mcp)) {
     const entry = expectedMcpEntry(root);
     const yes = !!opts.yes;
     for (const p of [paths.cursorMcpPath, paths.claudeMcpPath]) {

package/src/install/install.test.ts

@@ -11,8 +11,9 @@ import { parseInstallOpts } from "./index.ts";
 
 const fixture: CliProgram = {
   key: "testapp",
+  version: "0.0.0",
   description: "Test",
-  mcpServer: { name: "testapp" },
+  mcpServer: { enabled: true },
   handler: () => {},
 };
 

package/src/install/paths.ts

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CliProgram } from "../types.ts";
-import { sanitizeToolSegment } from "../mcp/tools.ts";
+import { sanitizeToolSegment, mcpServerId } from "../mcp/tools.ts";
 
 export interface InstallPaths {
   bindir: string;
@@ -63,7 +63,7 @@ export function resolveInstallPaths(root: CliProgram, opts: { prefix?: string })
     claudeMcpPath: join(home, ".claude.json"),
     bashRc: join(home, ".bashrc"),
     zshRc: join(home, ".zshrc"),
-    mcpName: root.mcpServer?.name ?? root.key,
+    mcpName: mcpServerId(root),
     skillDirName,
   };
 }

package/src/install/plan.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { installBinary } from "./binary.ts";
 import { installCompletions } from "./completions.ts";
@@ -46,7 +47,7 @@ function wantsSkill(opts: InstallOpts): boolean {
 }
 
 function wantsMcp(opts: InstallOpts, root: CliProgram): boolean {
-  return !!(opts.all || opts.mcp) && root.mcpServer !== undefined;
+  return !!(opts.mcp || opts.all) && resolveCapabilities(root).mcp;
 }
 
 /** Builds install actions for normal mode (--all / scoped targets). */
@@ -154,7 +155,7 @@ export function buildUpdatePlan(root: CliProgram, paths: InstallPaths, opts: Ins
     bin: true,
     completions: detected.bashCompletion || detected.zshCompletion || detected.fishCompletion,
     skill: detected.cursorSkill || detected.claudeSkill,
-    mcp: (detected.cursorMcp || detected.claudeMcp) && root.mcpServer !== undefined,
+    mcp: (detected.cursorMcp || detected.claudeMcp) && resolveCapabilities(root).mcp,
     dry: opts.dry,
   };
   const plan = buildInstallPlan(root, paths, scoped);

package/src/install/uninstall.ts

@@ -1,5 +1,6 @@
 import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { uninstallBinary } from "./binary.ts";
 import { uninstallCompletions } from "./completions.ts";
@@ -77,7 +78,7 @@ export function buildUninstallPlan(
     });
   }
 
-  if ((all || opts.mcp) && root.mcpServer !== undefined) {
+  if ((all || opts.mcp) && resolveCapabilities(root).mcp) {
     if (detected.cursorMcp) {
       actions.push({
         summary: `cursor mcp: ${paths.cursorMcpPath}`,

package/src/invoke.ts

@@ -5,8 +5,10 @@ process.exit so MCP tool calls can run handlers repeatedly.
 */
 
 import { CliContext } from "./context.ts";
+import { builtinInterceptRoot } from "./builtins/dispatch.ts";
+import { cliPresentationRoot } from "./builtins/presentation.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
-import { type CliNode, type CliProgram, isCliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { format } from "node:util";
 
 /** Outcome of a non-exiting CLI invocation. */
@@ -49,8 +51,18 @@ function findChild(cmds: CliNode[], name: string): CliNode | undefined {
  * Never calls process.exit.
  */
 export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult> {
-  let pr = parse(root, argv);
-  pr = postParseValidate(root, pr);
+  let parseRoot: CliNode = root;
+  if (isCliLeaf(root)) {
+    const intercept = builtinInterceptRoot(root, argv);
+    if (intercept.parseRoot !== root) {
+      parseRoot = intercept.parseRoot;
+    }
+  } else {
+    parseRoot = cliPresentationRoot(root);
+  }
+
+  let pr = parse(parseRoot, argv);
+  pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
     return {
@@ -82,7 +94,7 @@ export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliIn
     };
   }
 
-  let current: CliProgram = root;
+  let current: CliNode = parseRoot;
   for (const seg of pr.path) {
     if (!isCliRouter(current)) {
       return {

package/src/mcp/tools.ts

@@ -3,14 +3,24 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for cliInvoke.
 */
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { CliProgram, CliLeaf, CliNode, CliOption, CliOptionKind, CliPositional, isCliLeaf, isCliRouter } from "../types.ts";
 
-/** Default URI for the CLI schema MCP resource. */
-export const MCP_SCHEMA_URI_DEFAULT = "argsbarg://schema";
+/** Default URI pattern for the CLI schema MCP resource (`<mcpId>://schema`). */
+export function defaultMcpSchemaUri(mcpId: string): string {
+  return `${mcpId}://schema`;
+}
+
+/** Sanitizes a command key segment for MCP tool names and server identity. */
+export function sanitizeToolSegment(key: string): string {
+  return key.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** MCP server id derived from the program root key (sanitized). */
+export function mcpServerId(root: CliProgram): string {
+  return sanitizeToolSegment(root.key);
+}
 
 /** One MCP tool derived from a leaf CLI command. */
 export interface McpToolDef {
@@ -32,11 +42,6 @@ export function mcpToolDescription(path: string[], rootKey: string, description:
   return `${prefix} — ${description}`;
 }
 
-/** Sanitizes a command key segment for MCP tool names. */
-export function sanitizeToolSegment(key: string): string {
-  return key.replace(/[^a-zA-Z0-9]/g, "_");
-}
-
 /** Builds the MCP tool name for a leaf at the given path. */
 export function mcpToolName(root: CliProgram, path: string[]): string {
   if (path.length === 0) {
@@ -150,7 +155,7 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
   /** Walks the command tree and appends leaf tools. */
   function walk(cmd: CliNode, path: string[]): void {
     if (isCliLeaf(cmd)) {
-      if (cmd.key === "completion" || cmd.key === "install" || cmd.key === "mcp") {
+      if (cmd.key === "completion" || cmd.key === "install" || cmd.key === "mcp" || cmd.key === "version") {
         return;
       }
       if (cmd.mcpTool?.enabled === false) {
@@ -181,28 +186,20 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
   return out;
 }
 
-/** Reads package.json version from cwd synchronously. */
-function resolveMcpVersionFromPackageJson(): string | undefined {
-  try {
-    const text = readFileSync(join(process.cwd(), "package.json"), "utf8");
-    const version = (JSON.parse(text) as { version?: string }).version;
-    return typeof version === "string" ? version : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /** Resolves MCP server name and version for initialize. */
 export function resolveMcpServerInfo(root: CliProgram): { name: string; version: string } {
   return {
-    name: root.mcpServer?.name ?? root.key,
-    version: root.mcpServer?.version ?? resolveMcpVersionFromPackageJson() ?? "0.0.0",
+    name: mcpServerId(root),
+    version: root.version,
   };
 }
 
 /** Resolves the schema resource URI for this app. */
 export function resolveMcpSchemaUri(root: CliProgram): string {
-  return root.mcpServer?.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+  if (root.mcpServer?.schemaResourceUri) {
+    return root.mcpServer.schemaResourceUri;
+  }
+  return defaultMcpSchemaUri(mcpServerId(root));
 }
 
 /** Converts flat MCP tool arguments to argv for cliInvoke. */

package/src/runtime.ts

@@ -32,7 +32,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   const caps = resolveCapabilities(program);
 
   if (argv.length >= 1 && argv[0] === "mcp" && !caps.mcp) {
-    process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
+    process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
     process.exit(1);
   }
 
@@ -41,6 +41,11 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(1);
   }
 
+  if (argv.length >= 1 && argv[0] === "docs" && !caps.docs) {
+    process.stderr.write("docs is not enabled. Set docs: { enabled: true } on the program root.\n");
+    process.exit(1);
+  }
+
   let parseRoot: CliNode;
   let completionParseRoot: CliRouter = cliRootMergedWithBuiltins(program);
   let isLeafCompletionIntercept = false;

package/src/schema.ts

@@ -5,7 +5,7 @@ This module serializes the CLI schema tree to JSON for machine-readable introspe
 import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
 
-const RESERVED = new Set(["completion", "install", "mcp"]);
+const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
 
 function exportCommand(cmd: CliNode): CliSchemaExport {
   const out: CliSchemaExport = {

package/src/skill/generate.ts

@@ -69,46 +69,14 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     "## When to use",
     "",
-    `Use this skill when working with **${root.key}** — shell commands, automation, or agent tool calls for this application.`,
+    `Use this skill when working with **${root.key}** — shell commands and automation for this application.`,
     "",
     "## Execution",
     "",
+    "Invoke via shell:",
+    "",
   ];
 
-  if (root.mcpServer !== undefined) {
-    lines.push(
-      "**Prefer MCP** when a host has the server connected:",
-      "",
-      "```bash",
-      `${root.key} mcp`,
-      "```",
-      "",
-      "Example Cursor `mcp.json` entry:",
-      "",
-      "```json",
-      JSON.stringify(
-        {
-          mcpServers: {
-            [root.mcpServer.name ?? root.key]: {
-              command: root.key,
-              args: ["mcp"],
-            },
-          },
-        },
-        null,
-        2,
-      ),
-      "```",
-      "",
-      "When MCP tools are available, use `tools/call` with flat JSON arguments. Read the schema resource for full shapes.",
-      "",
-      "Otherwise invoke via shell:",
-      "",
-    );
-  } else {
-    lines.push("Invoke via shell:", "");
-  }
-
   lines.push("```bash", `${root.key} <subcommand> [options] [args]`, "```", "", "## Commands", "");
 
   if (tools.length === 0) {
@@ -124,7 +92,6 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "## Pitfalls",
     "",
     "- Use `--` before tokens that look like flags when they are positional arguments.",
-    "- Under MCP (`ctx.invocation === \"mcp\"`), child processes must not inherit stdout — use piped stdout.",
     "- Required environment variables are listed per command in descriptions (`requires env`).",
     "",
     "## Reference",

package/src/types.test.ts

@@ -18,8 +18,9 @@ const _leafOnly: CliLeaf = {
 
 const _program: CliProgram = {
   key: "app",
+  version: "0.0.0",
   description: "",
-  mcpServer: {},
+  mcpServer: { enabled: true },
   commands: [],
 };
 
@@ -27,7 +28,7 @@ const _badMcpOnNode = {
   key: "x",
   description: "",
   // @ts-expect-error mcpServer is program-root only
-  mcpServer: {},
+  mcpServer: { enabled: true },
   commands: [],
 } satisfies CliNode;
 

package/src/types.ts

@@ -89,13 +89,12 @@ export interface CliPositional {
 
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
+ * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
  */
 export interface CliMcpServerConfig {
-  /** `initialize` serverInfo.name (default: root `key`). */
-  name?: string;
-  /** `initialize` serverInfo.version (default: see resolveMcpVersion). */
-  version?: string;
-  /** Resource URI for schema export (default: `"argsbarg://schema"`). */
+  /** When `true`, enables the `mcp` built-in and MCP stdio server. */
+  enabled: boolean;
+  /** Resource URI for schema export (default: `<sanitized root key>://schema`). */
   schemaResourceUri?: string;
   /**
    * Capture the user's login shell environment at MCP server start and merge it
@@ -110,7 +109,7 @@ export interface CliMcpServerConfig {
    */
   envFile?: string;
   /**
-   * Custom MCP resources exposed alongside the built-in argsbarg://schema resource.
+   * Custom MCP resources exposed alongside the built-in schema resource.
    * URIs must be unique and must not equal schemaResourceUri.
    */
   resources?: CliMcpResource[];
@@ -161,6 +160,34 @@ export interface CliInstallConfig {
   prefix?: string;
 }
 
+/**
+ * One bundled documentation topic for the `docs` built-in (program root only).
+ */
+export interface CliDocsTopic {
+  /** Bundled markdown (use compile-time text imports in the consumer). */
+  text: string;
+  /** Leaf help text for `myapp docs <key> -h`. Auto-generated from key when omitted. */
+  description?: string;
+}
+
+/**
+ * Enables `myapp docs` and bundled markdown topics (program root only).
+ * Must include `enabled: true`; omit `docs` entirely to disable.
+ */
+export interface CliDocsConfig {
+  /** When `true`, enables the `docs` built-in command group. */
+  enabled: boolean;
+  /** Router description for `myapp docs` (default: "Print bundled CLI documentation."). */
+  description?: string;
+  /**
+   * Subcommand for bare `myapp docs` (maps to router `fallbackCommand`).
+   * When omitted, uses the first key in `topics` (insertion order).
+   */
+  defaultTopic?: string;
+  /** Topic key → bundled markdown. Reserved keys: `mcp`, `all` (supplied by the built-in). */
+  topics: Record<string, CliDocsTopic>;
+}
+
 /**
  * Base properties shared by all nodes in the user command tree.
  */
@@ -209,10 +236,14 @@ export type CliNode = CliLeaf | CliRouter;
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
-  /** When set, enables the `mcp` built-in subcommand. */
+  /** Program version (printed by the `version` built-in and MCP serverInfo). */
+  version: string;
+  /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
   /** Opt-out and defaults for `install`. */
   install?: CliInstallConfig;
+  /** When set with `enabled: true`, enables the `docs` built-in command group. */
+  docs?: CliDocsConfig;
 };
 
 /** True when the node is a leaf (has a handler). */

package/src/validate.ts

@@ -12,10 +12,57 @@ import {
   isCliLeaf,
   isCliRouter,
 } from "./types.ts";
-import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
+import { resolveMcpSchemaUri } from "./mcp/tools.ts";
+import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
+
+/** Validates `docs` configuration on the program root. */
+function validateDocsConfig(docs: import("./types.ts").CliDocsConfig): void {
+  const keys = Object.keys(docs.topics);
+  if (keys.length === 0) {
+    throw new CliSchemaValidationError("docs.topics must be non-empty");
+  }
+  for (const reserved of DOCS_BUILTIN_TOPIC_KEYS) {
+    if (reserved in docs.topics) {
+      throw new CliSchemaValidationError(
+        `docs.topics key '${reserved}' is reserved for the docs built-in`,
+      );
+    }
+  }
+  if (docs.defaultTopic !== undefined && !(docs.defaultTopic in docs.topics)) {
+    throw new CliSchemaValidationError(
+      `docs.defaultTopic '${docs.defaultTopic}' is not a key in docs.topics`,
+    );
+  }
+  for (const key of keys) {
+    const text = docs.topics[key]?.text;
+    if (text === undefined || text.length === 0) {
+      throw new CliSchemaValidationError(`docs.topics['${key}'].text must be non-empty`);
+    }
+  }
+}
 
 /** Validates a program schema. */
 export function cliValidateProgram(program: CliProgram): void {
+  if (!program.version || program.version.trim().length === 0) {
+    throw new CliSchemaValidationError("CliProgram.version is required");
+  }
+
+  if (program.mcpServer !== undefined && program.mcpServer.enabled !== true) {
+    throw new CliSchemaValidationError(
+      "mcpServer requires enabled: true; omit mcpServer to disable MCP",
+    );
+  }
+
+  if (program.docs !== undefined && program.docs.enabled !== true) {
+    throw new CliSchemaValidationError(
+      "docs requires enabled: true; omit docs to disable bundled documentation",
+    );
+  }
+
+  if (program.docs?.enabled === true) {
+    validateDocsConfig(program.docs);
+  }
+
   const caps = resolveCapabilities(program);
   const reserved = reservedCommandNames(caps);
 
@@ -43,6 +90,11 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
         "install is only supported on the program root (not on " + node.key + ")",
       );
     }
+    if (rogue.docs !== undefined) {
+      throw new CliSchemaValidationError(
+        "docs is only supported on the program root (not on " + node.key + ")",
+      );
+    }
   }
 
   if (isCliLeaf(node)) {
@@ -58,8 +110,8 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     }
   }
 
-  if (isRoot && program.mcpServer?.resources) {
-    const schemaUri = program.mcpServer.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+  if (isRoot && program.mcpServer?.enabled === true && program.mcpServer.resources) {
+    const schemaUri = resolveMcpSchemaUri(program);
     const uris = program.mcpServer.resources.map((r) => r.uri);
     if (uris.includes(schemaUri)) {
       throw new CliSchemaValidationError(