argsbarg 3.0.0 → 3.2.0

package/src/install/update.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import type { CliProgram } from "../types.ts";
+import { runInstallMutation } from "./index.ts";
+import { installErr } from "./status.ts";
+
+/** Downloads the latest release and reinstalls installed artifacts (`myapp update`). */
+export async function cliUpdate(root: CliProgram): Promise<never> {
+  const hook = root.install?.updateGetLatest;
+  if (!hook) {
+    installErr("update is not configured. Set install.updateGetLatest on the program root.");
+    process.exit(1);
+  }
+
+  let artifact: Awaited<ReturnType<typeof hook>>;
+  try {
+    artifact = await hook({ version: root.version });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    installErr(message);
+    process.exit(1);
+  }
+
+  if (!artifact.path || !existsSync(artifact.path)) {
+    installErr(`updateGetLatest returned missing binary: ${JSON.stringify(artifact.path)}`);
+    process.exit(1);
+  }
+
+  if (artifact.version !== undefined && artifact.version === root.version) {
+    process.stdout.write(`Already at v${root.version}\n`);
+    await artifact.cleanup?.();
+    process.exit(0);
+  }
+
+  const currentVersion = root.version;
+  try {
+    await runInstallMutation(root, {
+      reinstall: "1",
+      yes: "1",
+      quiet: "1",
+      from: artifact.path,
+    });
+  } catch (err) {
+    await artifact.cleanup?.();
+    installErr(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  await artifact.cleanup?.();
+
+  if (artifact.version !== undefined && artifact.version !== currentVersion) {
+    process.stdout.write(`Updated ${root.key} ${currentVersion} → ${artifact.version}\n`);
+  }
+
+  process.exit(0);
+}

package/src/invoke.ts

@@ -5,12 +5,14 @@ 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. */
-export type CliInvokeKind = "ok" | "help" | "schema" | "error";
+export type CliInvokeKind = "ok" | "help" | "error";
 
 /** Result of cliInvoke: captured output and exit metadata without process.exit. */
 export interface CliInvokeResult {
@@ -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 {
@@ -62,16 +74,6 @@ export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliIn
     };
   }
 
-  if (pr.kind === ParseKind.Schema) {
-    return {
-      kind: "schema",
-      exitCode: 1,
-      stdout: "",
-      stderr: "",
-      errorMsg: "Schema export is not available via MCP tool calls.",
-    };
-  }
-
   if (pr.kind === ParseKind.Error) {
     return {
       kind: "error",
@@ -82,7 +84,7 @@ export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliIn
     };
   }
 
-  let current: CliNode = root;
+  let current: CliNode = parseRoot;
   for (const seg of pr.path) {
     if (!isCliRouter(current)) {
       return {

package/src/mcp/tools.ts

@@ -134,7 +134,7 @@ export function allMcpResources(root: CliProgram): McpResourceEntry[] {
   const builtIn: McpResourceEntry = {
     uri: schemaUri,
     name: "cli-schema",
-    description: "Full CLI command tree (same as --schema).",
+    description: "Full CLI command tree (same as docs schema).",
     mimeType: "application/json",
     load: () => cliSchemaJson(root),
   };

package/src/parse.ts

@@ -29,8 +29,6 @@ export enum ParseKind {
   Ok = "ok",
   /** User requested help (explicit or implicit). */
   Help = "help",
-  /** User requested machine-readable schema export (`--schema`). */
-  Schema = "schema",
   /** User error (unknown command, bad option, etc.). */
   Error = "error",
 }
@@ -59,18 +57,12 @@ export interface ParseResult {
 
 const helpShort = "-h";
 const helpLong = "--help";
-const schemaLong = "--schema";
 
 /** Returns true if the argv token is `-h` or `--help`. */
 function isHelpTok(tok: string): boolean {
   return tok === helpShort || tok === helpLong;
 }
 
-/** Returns true if the argv token is `--schema`. */
-function isSchemaTok(tok: string): boolean {
-  return tok === schemaLong;
-}
-
 /** Looks up a subcommand or routing node by `key`. */
 function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
@@ -195,7 +187,6 @@ function consumeOptions(
     const tok = argv[idx];
 
     if (isHelpTok(tok)) break;
-    if (isSchemaTok(tok)) break;
     if (!tok.startsWith("-")) break;
 
     if (tok === "--") {
@@ -371,20 +362,6 @@ function helpResult(p: string[], explicit: boolean): ParseResult {
   };
 }
 
-/** Builds a schema-export result for the program root. */
-function schemaResult(): ParseResult {
-  return {
-    kind: ParseKind.Schema,
-    path: [],
-    opts: {},
-    args: [],
-    helpExplicit: false,
-    helpPath: [],
-    errorMsg: "",
-    errorHelpPath: [],
-  };
-}
-
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
@@ -420,10 +397,6 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     return helpResult([], true);
   }
 
-  if (i < argv.length && !forcePositionals && isSchemaTok(argv[i])) {
-    return schemaResult();
-  }
-
   // Determine which subcommand to route to
   let cmdName: string;
   let node: CliNode | undefined;

package/src/runtime.ts

@@ -10,7 +10,6 @@ import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.t
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
-import { cliSchemaJson } from "./schema.ts";
 import { cliValidateProgram } from "./validate.ts";
 
 function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
@@ -41,6 +40,18 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(1);
   }
 
+  if (argv.length >= 1 && argv[0] === "update" && !caps.update) {
+    process.stderr.write(
+      "update is not enabled. Set install.updateGetLatest on the program root.\n",
+    );
+    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;
@@ -68,11 +79,6 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
-  if (pr.kind === ParseKind.Schema) {
-    process.stdout.write(cliSchemaJson(program));
-    process.exit(0);
-  }
-
   if (pr.kind === "error") {
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;

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", "update"]);
 
 function exportCommand(cmd: CliNode): CliSchemaExport {
   const out: CliSchemaExport = {
@@ -44,8 +44,13 @@ function exportCommand(cmd: CliNode): CliSchemaExport {
   return out;
 }
 
+/** Returns the JSON-safe command tree (handlers omitted). */
+export function cliSchemaExport(root: CliProgram): CliSchemaExport {
+  return exportCommand(root);
+}
+
 export function cliSchemaJson(root: CliProgram): string {
-  return JSON.stringify(exportCommand(root), null, 2) + "\n";
+  return JSON.stringify(cliSchemaExport(root), null, 2) + "\n";
 }
 
 export type { CliSchemaExport };

package/src/skill/generate.ts

@@ -4,7 +4,7 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
-import { collectMcpTools, mcpServerId, sanitizeToolSegment } from "../mcp/tools.ts";
+import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
 import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
@@ -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?.enabled === true) {
-    lines.push(
-      "**Prefer MCP** when a host has the server connected:",
-      "",
-      "```bash",
-      `${root.key} mcp`,
-      "```",
-      "",
-      "Example Cursor `mcp.json` entry:",
-      "",
-      "```json",
-      JSON.stringify(
-        {
-          mcpServers: {
-            [mcpServerId(root)]: {
-              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,12 +92,11 @@ 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",
     "",
-    "See `reference.md` in this skill directory for the full `--schema` JSON export.",
+    "See `reference.md` in this skill directory for the full `docs schema` JSON export.",
     "",
   );
 
@@ -163,7 +130,7 @@ function buildReferenceMd(root: CliProgram): string {
   return [
     `# ${root.key} — CLI reference`,
     "",
-    "Generated from the program `--schema` export. Handlers and runtime-only nodes are omitted.",
+    "Generated from the program `docs schema` export. Handlers and runtime-only nodes are omitted.",
     "",
     "```json",
     cliSchemaJson(root).trimEnd(),

package/src/types.ts

@@ -153,11 +153,56 @@ export interface CliMcpToolConfig {
 /**
  * Opt-out and defaults for the `install` built-in (program root only).
  */
+export interface CliUpdateArtifact {
+  /** Path to an executable binary to copy into the install location. */
+  path: string;
+  /** Release version of `path` (used for already-current checks and success messages). */
+  version?: string;
+  /** Called after reinstall completes (e.g. remove a temp download directory). */
+  cleanup?: () => void | Promise<void>;
+}
+
+/** Fetches the latest release binary for the `update` built-in. */
+export type CliUpdateGetLatest = (ctx: { version: string }) => Promise<CliUpdateArtifact>;
+
 export interface CliInstallConfig {
   /** When `false`, hide/disable `install` (default: enabled). */
   enabled?: boolean;
   /** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
   prefix?: string;
+  /**
+   * When set, enables the `update` built-in (`myapp update`).
+   * Should download or locate the latest release binary and return its path.
+   */
+  updateGetLatest?: CliUpdateGetLatest;
+}
+
+/**
+ * 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>;
 }
 
 /**
@@ -214,6 +259,8 @@ export type CliProgram = CliNode & {
   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

@@ -13,6 +13,33 @@ import {
   isCliRouter,
 } from "./types.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 {
@@ -26,6 +53,27 @@ export function cliValidateProgram(program: CliProgram): void {
     );
   }
 
+  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);
+  }
+
+  if (program.install?.updateGetLatest !== undefined) {
+    if (program.install.enabled === false) {
+      throw new CliSchemaValidationError(
+        "install.updateGetLatest requires install to be enabled (omit install.enabled: false)",
+      );
+    }
+    if (typeof program.install.updateGetLatest !== "function") {
+      throw new CliSchemaValidationError("install.updateGetLatest must be a function");
+    }
+  }
+
   const caps = resolveCapabilities(program);
   const reserved = reservedCommandNames(caps);
 
@@ -53,6 +101,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)) {
@@ -124,12 +177,6 @@ function validateOptions(scopeKey: string, options: import("./types.ts").CliOpti
       );
     }
 
-    if (opt.name === "schema") {
-      throw new CliSchemaValidationError(
-        `Option name "schema" is reserved for --schema: ${scopeKey}/${opt.name}`,
-      );
-    }
-
     if (opt.shortName !== undefined) {
       if (opt.shortName === "h") {
         throw new CliSchemaValidationError(