argsbarg 1.4.3 → 1.5.0

package/src/builtins/dispatch.ts

@@ -0,0 +1,123 @@
+import { CliCommand } from "../types.ts";
+import { completionBashScript } from "./completion-bash.ts";
+import { completionFishScript } from "./completion-fish.ts";
+import { completionZshScript } from "./completion-zsh.ts";
+import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
+import { cliMcpServeStdio } from "../mcp.ts";
+import { cliInstall } from "../install/index.ts";
+import { isCompiledExecutable } from "../install/compiled.ts";
+import type { ParseResult } from "../parse.ts";
+import { ParseKind } from "../parse.ts";
+
+export interface DispatchBuiltinOpts {
+  isLeafCompletionIntercept: boolean;
+  parseRoot: CliCommand;
+}
+
+/**
+ * Handles built-in commands after parse.
+ */
+export async function dispatchBuiltin(
+  root: CliCommand,
+  pr: ParseResult,
+  opts: DispatchBuiltinOpts,
+): Promise<void> {
+  if (pr.kind !== ParseKind.Ok) {
+    return;
+  }
+  if (pr.path[0] === "completion") {
+    const schemaForCompletion = opts.isLeafCompletionIntercept ? root : opts.parseRoot;
+    if (pr.path[1] === "bash") {
+      process.stdout.write(completionBashScript(schemaForCompletion));
+      process.exit(0);
+    }
+    if (pr.path[1] === "zsh") {
+      process.stdout.write(completionZshScript(schemaForCompletion));
+      process.exit(0);
+    }
+    if (pr.path[1] === "fish") {
+      process.stdout.write(completionFishScript(schemaForCompletion));
+      process.exit(0);
+    }
+    return;
+  }
+
+  if (pr.path[0] === "mcp") {
+    if (!root.mcpServer) {
+      process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
+      process.exit(1);
+    }
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    await cliMcpServeStdio(root);
+    process.exit(0);
+  }
+
+  if (pr.path[0] === "install") {
+    if (!isCompiledExecutable()) {
+      process.stderr.write(
+        "install is only available in compiled binaries (bun build --compile).\n",
+      );
+      process.exit(1);
+    }
+    if (root.install?.enabled === false) {
+      process.stderr.write("install is disabled. Remove install.enabled: false from the program root.\n");
+      process.exit(1);
+    }
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: install " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    await cliInstall(root, pr.opts);
+  }
+}
+
+/** Built-in intercept roots for leaf programs. */
+export function builtinInterceptRoot(
+  root: CliCommand,
+  argv: string[],
+): { parseRoot: CliCommand; isLeafCompletionIntercept: boolean } {
+  if (!root.handler || argv.length < 1) {
+    return { parseRoot: root, isLeafCompletionIntercept: false };
+  }
+
+  const first = argv[0];
+  if (first === "completion") {
+    return {
+      parseRoot: {
+        key: root.key,
+        description: root.description,
+        commands: [completionGroup(root.key)],
+      } as CliCommand,
+      isLeafCompletionIntercept: true,
+    };
+  }
+
+  if (first === "install" && isCompiledExecutable() && root.install?.enabled !== false) {
+    return {
+      parseRoot: {
+        key: root.key,
+        description: root.description,
+        commands: [cliBuiltinInstallCommand(root)],
+      } as CliCommand,
+      isLeafCompletionIntercept: false,
+    };
+  }
+
+  if (first === "mcp" && root.mcpServer !== undefined) {
+    return {
+      parseRoot: {
+        key: root.key,
+        description: root.description,
+        commands: [cliBuiltinMcpCommand()],
+      } as CliCommand,
+      isLeafCompletionIntercept: false,
+    };
+  }
+
+  return { parseRoot: root, isLeafCompletionIntercept: false };
+}

package/src/builtins/export.ts

@@ -0,0 +1,46 @@
+import { CliCommand, CliFallbackMode, CliOption, CliPositional } from "../types.ts";
+import { cliBuiltinCompletionGroup } from "./completion-group.ts";
+import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { isCompiledExecutable } from "../install/compiled.ts";
+
+/** JSON-safe command node (no handlers). */
+export interface CliSchemaExport {
+  key: string;
+  description: string;
+  notes?: string;
+  options?: CliOption[];
+  fallbackCommand?: string;
+  fallbackMode?: CliFallbackMode;
+  commands?: CliSchemaExport[];
+  positionals?: CliPositional[];
+}
+
+function exportBuiltinNode(cmd: CliCommand): CliSchemaExport {
+  const out: CliSchemaExport = {
+    key: cmd.key,
+    description: cmd.description,
+  };
+  if ((cmd.notes ?? "").length > 0) {
+    out.notes = cmd.notes;
+  }
+  if ((cmd.options ?? []).length > 0) {
+    out.options = cmd.options;
+  }
+  if ((cmd.commands ?? []).length > 0) {
+    out.commands = (cmd.commands ?? []).map((ch) => exportBuiltinNode(ch));
+  }
+  return out;
+}
+
+/** Built-in subtrees matching help visibility for `--schema` export. */
+export function exportPresentationBuiltins(root: CliCommand): CliSchemaExport[] {
+  const builtins: CliSchemaExport[] = [exportBuiltinNode(cliBuiltinCompletionGroup(root.key))];
+  if (isCompiledExecutable() && root.install?.enabled !== false) {
+    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(root)));
+  }
+  if (root.mcpServer !== undefined) {
+    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand()));
+  }
+  return builtins;
+}

package/src/builtins/index.ts

@@ -0,0 +1,10 @@
+export { completionBashScript } from "./completion-bash.ts";
+export { completionZshScript } from "./completion-zsh.ts";
+export { completionFishScript } from "./completion-fish.ts";
+export { cliBuiltinCompletionGroup } from "./completion-group.ts";
+export { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
+export { cliBuiltinMcpCommand } from "./mcp.ts";
+export { cliPresentationRoot, presentationBuiltins } from "./presentation.ts";
+export { exportPresentationBuiltins, type CliSchemaExport } from "./export.ts";
+export { dispatchBuiltin, builtinInterceptRoot } from "./dispatch.ts";
+export { collectScopes, type ScopeRec } from "./scopes.ts";

package/src/builtins/install.ts

@@ -0,0 +1,99 @@
+import { CliCommand, CliOption, CliOptionKind } from "../types.ts";
+
+/** Install command options (dynamic: `--mcp` only when MCP is enabled). */
+export function installBuiltinOptions(root: CliCommand): CliOption[] {
+  const opts: CliOption[] = [
+    {
+      name: "all",
+      description: "Install binary, completions, skills, and MCP config (when enabled).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "bin",
+      description: "Copy this binary to your install directory (default ~/.local/bin).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "completions",
+      description:
+        "Install bash, zsh, and fish tab-completion scripts (each skipped silently if that shell is not on PATH).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "skill",
+      description: "Install Cursor and Claude Code skills when ~/.cursor or ~/.claude exists.",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "update",
+      description: "Update only artifacts already installed (always includes the binary).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "status",
+      description: "Print what is currently installed (read-only).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "uninstall",
+      description: "Remove installed artifacts (all detected, or limit with other flags).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "prefix",
+      description: "Install directory for the binary (default ~/.local/bin; overrides INSTALL_PREFIX).",
+      kind: CliOptionKind.String,
+    },
+    {
+      name: "yes",
+      description: "Skip the confirmation prompt.",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "dry",
+      description: "Show what would change without writing files.",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "json",
+      description: "Print changed paths (install/update/uninstall) or status JSON on stdout.",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "quiet",
+      description: "Suppress informational output (requires --yes).",
+      kind: CliOptionKind.Presence,
+    },
+  ];
+
+  if (root.mcpServer !== undefined) {
+    opts.splice(4, 0, {
+      name: "mcp",
+      description: "Add or update MCP server entries in Cursor and Claude config files.",
+      kind: CliOptionKind.Presence,
+    });
+  }
+
+  return opts;
+}
+
+/** Builds the `install` built-in command (compiled binaries only). */
+export function cliBuiltinInstallCommand(root: CliCommand): CliCommand {
+  return {
+    key: "install",
+    description: "Install the binary, shell completions, agent skills, and MCP config to your user environment.",
+    notes:
+      "Requires a compiled binary (bun build --compile).\n\n" +
+      "First-time setup:\n" +
+      `  {app} install --all --yes\n\n` +
+      "Refresh after upgrading:\n" +
+      `  {app} install --update\n\n` +
+      "See what is installed:\n" +
+      `  {app} install --status\n\n` +
+      "Remove everything:\n" +
+      `  {app} install --uninstall --yes\n\n` +
+      "Use --dry to preview changes, --json for machine-readable output.",
+    options: installBuiltinOptions(root),
+    handler: () => {},
+  };
+}

package/src/builtins/mcp.ts

@@ -0,0 +1,13 @@
+import { CliCommand, CliOption, CliOptionKind } from "../types.ts";
+
+/** Presence options for the top-level `mcp` built-in (leaf). */
+export function cliBuiltinMcpCommand(): CliCommand {
+  return {
+    key: "mcp",
+    description: "Run as an MCP server over stdio for AI agents.",
+    notes:
+      "Configure MCP clients with `command` set to this program name and `args` set to `[\"mcp\"]`.\n\n" +
+      "See docs/mcp.md for setup details.",
+    handler: () => {},
+  };
+}

package/src/builtins/presentation.ts

@@ -0,0 +1,39 @@
+import { CliCommand } from "../types.ts";
+import { isCompiledExecutable } from "../install/compiled.ts";
+import { cliBuiltinCompletionGroup } from "./completion-group.ts";
+import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+
+/** Built-in commands shown in help and merged for routing CLIs. */
+export function presentationBuiltins(root: CliCommand): CliCommand[] {
+  const builtins: CliCommand[] = [cliBuiltinCompletionGroup(root.key)];
+  if (isCompiledExecutable() && root.install?.enabled !== false) {
+    builtins.push(cliBuiltinInstallCommand(root));
+  }
+  if (root.mcpServer !== undefined) {
+    builtins.push(cliBuiltinMcpCommand());
+  }
+  return builtins;
+}
+
+/**
+ * Returns a schema suitable for help display, including reserved built-in subtrees.
+ * Routing roots get builtins merged; leaf roots are wrapped as a tiny router.
+ */
+export function cliPresentationRoot(root: CliCommand): CliCommand {
+  if ((root.commands ?? []).some((c) => c.key === "completion")) {
+    return root;
+  }
+  if ("handler" in root && root.handler) {
+    return {
+      key: root.key,
+      description: root.description,
+      options: root.options,
+      commands: presentationBuiltins(root),
+    } as CliCommand;
+  }
+  return {
+    ...root,
+    commands: [...(root.commands ?? []), ...presentationBuiltins(root)],
+  } as CliCommand;
+}

package/src/builtins/scopes.ts

@@ -0,0 +1,45 @@
+/*
+Shared completion scope walk used by bash, zsh, and fish emitters.
+*/
+
+import { CliCommand } from "../types.ts";
+
+/** One tab-completion scope: child commands, options, and path key for the schema walk. */
+export interface ScopeRec {
+  kids: CliCommand[];
+  opts: import("../types.ts").CliOption[];
+  path: string;
+  wantsFiles: boolean;
+}
+
+function hasPositionalArguments(cmd: CliCommand): boolean {
+  return (cmd.positionals ?? []).length > 0;
+}
+
+function walkScopes(cmdPath: string, cmd: CliCommand, acc: ScopeRec[]): void {
+  acc.push({
+    kids: cmd.commands ?? [],
+    opts: cmd.options ?? [],
+    path: cmdPath,
+    wantsFiles: hasPositionalArguments(cmd),
+  });
+  for (const ch of cmd.commands ?? []) {
+    const nextPath = cmdPath === "" ? ch.key : cmdPath + "/" + ch.key;
+    walkScopes(nextPath, ch, acc);
+  }
+}
+
+/** Flattens the schema into a list of completion scopes (root + every command path). */
+export function collectScopes(schema: CliCommand): ScopeRec[] {
+  const acc: ScopeRec[] = [];
+  acc.push({
+    kids: schema.commands ?? [],
+    opts: schema.options ?? [],
+    path: "",
+    wantsFiles: false,
+  });
+  for (const c of schema.commands ?? []) {
+    walkScopes(c.key, c, acc);
+  }
+  return acc;
+}

package/src/builtins/shell-helpers.ts

@@ -0,0 +1,24 @@
+/** Produces a shell-safe identifier from the app or command name (alnum → `_`). */
+export function identToken(s: string): string {
+  return s.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** Escapes a string for use inside single quotes in generated shell scripts. */
+export function escShellSingleQuoted(s: string): string {
+  return s.replace(/'/g, "'\\''");
+}
+
+/** Escapes a string for use inside fish single-quoted strings. */
+export function escFishSingleQuoted(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
+/** Sanitizes the app key for generated shell function names (non-alnum removed). */
+export function mainName(schemaName: string): string {
+  return schemaName.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+export const kHelpLong = "--help";
+export const kHelpShort = "-h";
+export const kSchemaLong = "--schema";
+export const kSchemaDesc = "Print the full command tree as JSON.";