argsbarg 1.4.3 → 2.0.0

package/src/builtins/completion-fish.ts

@@ -0,0 +1,73 @@
+import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
+import { collectScopes } from "./scopes.ts";
+import {
+  escFishSingleQuoted,
+  identToken,
+  kHelpLong,
+  kHelpShort,
+  kSchemaDesc,
+  kSchemaLong,
+} from "./shell-helpers.ts";
+
+function scopeCondition(ident: string, scopeIndex: number, path: string): string {
+  const fn = `__${ident}_scope_${scopeIndex}`;
+  let body = `function ${fn}\n`;
+  body += `    set -l tokens (commandline -opc)\n`;
+  if (path === "") {
+    body += `    test (count $tokens) -eq 0\n`;
+  } else {
+    const parts = path.split("/");
+    body += `    test (count $tokens) -eq ${parts.length}\n`;
+    for (let i = 0; i < parts.length; i++) {
+      body += `    and test $tokens[${i + 1}] = ${parts[i]}\n`;
+    }
+  }
+  body += `end\n\n`;
+  return body;
+}
+
+/** Returns a self-contained fish completion script for the given program schema. */
+export function completionFishScript(schema: CliRouter): string {
+  const ident = identToken(schema.key);
+  const app = schema.key;
+  const scopes = collectScopes(schema);
+
+  let out = "# Fish completion for " + app + "\n\n";
+
+  for (const [i, sc] of scopes.entries()) {
+    out += scopeCondition(ident, i, sc.path);
+    const cond = `__${ident}_scope_${i}`;
+
+    for (const ch of sc.kids) {
+      out += `complete -c ${app} -n '${cond}' -a '${escFishSingleQuoted(ch.key)}' -d '${escFishSingleQuoted(ch.description)}'\n`;
+    }
+
+    out += `complete -c ${app} -n '${cond}' -s h -l help -d '${escFishSingleQuoted("Show help for this command.")}'\n`;
+    if (sc.path === "") {
+      out += `complete -c ${app} -n '${cond}' -l schema -d '${escFishSingleQuoted(kSchemaDesc)}'\n`;
+    }
+
+    for (const op of sc.opts) {
+      if (op.kind === CliOptionKind.Presence) {
+        const shortPart = op.shortName ? `-s ${op.shortName} ` : "";
+        out += `complete -c ${app} -n '${cond}' ${shortPart}-l ${op.name} -d '${escFishSingleQuoted(op.description)}'\n`;
+      } else if (op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0) {
+        const shortPart = op.shortName ? `-s ${op.shortName} ` : "";
+        out += `complete -c ${app} -n '${cond}' ${shortPart}-l ${op.name} -d '${escFishSingleQuoted(op.description)}'\n`;
+        const enumCond = `${cond}; and __fish_seen_argument -l ${op.name}`;
+        for (const choice of op.choices ?? []) {
+          out += `complete -c ${app} -n '${enumCond}' -a '${escFishSingleQuoted(choice)}'\n`;
+        }
+      } else {
+        const shortPart = op.shortName ? `-s ${op.shortName} ` : "";
+        out += `complete -c ${app} -n '${cond}' ${shortPart}-l ${op.name} -d '${escFishSingleQuoted(op.description)}' -r\n`;
+      }
+    }
+
+    if (sc.wantsFiles && sc.kids.length === 0) {
+      out += `complete -c ${app} -n '${cond}' -F\n`;
+    }
+  }
+
+  return out;
+}

package/src/builtins/completion-group.ts

@@ -0,0 +1,50 @@
+import { type CliLeaf, type CliNode, type CliRouter } from "../types.ts";
+
+/**
+ * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).
+ */
+export function cliBuiltinCompletionGroup(appName: string): CliRouter {
+  return {
+    key: "completion",
+    description: "Generate the autocompletion script for shells.",
+    commands: [
+      {
+        key: "bash",
+        description: "Print a bash tab-completion script.",
+        notes:
+          "Output is the whole script.\n" +
+          "Pipe it to a file, or feed it straight into your shell.\n\n" +
+          "To keep it across restarts, save it and source that file from ~/.bashrc.\n\n" +
+          "For example:\n\n" +
+          `echo 'eval \"$(${appName} completion bash)\"' >> ~/.bashrc\n` +
+          `\nor\n` +
+          `  ${appName} completion bash > ~/.bash_completion.d/${appName}\n` +
+          `  echo 'source ~/.bash_completion.d/${appName}' >> ~/.bashrc\n\n` +
+          "To try it only in this session (nothing written to disk):\n" +
+          `  source <(${appName} completion bash)`,
+        handler: () => {},
+      },
+      {
+        key: "zsh",
+        description: "Print a zsh tab-completion script.",
+        notes:
+          "Output is the whole script.\n\n" +
+          `fpath setup: ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
+          `source setup: echo 'eval \"$(${appName} completion zsh)\"' >> ~/.zshrc\n\n` +
+          "To try it only in this session (nothing written to disk):\n" +
+          `  eval \"$(${appName} completion zsh)\"`,
+        handler: () => {},
+      },
+      {
+        key: "fish",
+        description: "Print a fish tab-completion script.",
+        notes:
+          "Output is the whole script.\n\n" +
+          "Install:\n" +
+          `  ${appName} completion fish > ~/.config/fish/completions/${appName}.fish\n\n` +
+          "Fish loads completions from that directory automatically.",
+        handler: () => {},
+      },
+    ],
+  };
+}

package/src/builtins/completion-zsh.ts

@@ -0,0 +1,244 @@
+import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
+import { collectScopes, type ScopeRec } from "./scopes.ts";
+import {
+  escShellSingleQuoted,
+  identToken,
+  kHelpLong,
+  kHelpShort,
+  kSchemaDesc,
+  kSchemaLong,
+  mainName,
+} from "./shell-helpers.ts";
+
+function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
+  let out = "";
+  for (const [i, sc] of scopes.entries()) {
+    out += "typeset -g A_" + ident + "_" + i + "_opts\n";
+    out += "A_" + ident + "_" + i + "_opts=(";
+    out += "'" + escShellSingleQuoted(kHelpLong) + ":" + escShellSingleQuoted("Show help for this command.") + "' '" + escShellSingleQuoted(kHelpShort) + ":" + escShellSingleQuoted("Show help for this command.") + "'";
+    if (sc.path === "") {
+      out += " '" + escShellSingleQuoted(kSchemaLong) + ":" + escShellSingleQuoted(kSchemaDesc) + "'";
+    }
+    for (const o of sc.opts) {
+      out += " '" + escShellSingleQuoted("--" + o.name) + ":" + escShellSingleQuoted(o.description) + "'";
+      if (o.shortName) {
+        out += " '" + escShellSingleQuoted("-" + o.shortName) + ":" + escShellSingleQuoted(o.description) + "'";
+      }
+    }
+    out += ")\n";
+    out += "typeset -g A_" + ident + "_" + i + "_leaf=" + (sc.kids.length === 0 ? "1" : "0") + "\n";
+    out += "typeset -g A_" + ident + "_" + i + "_pos=" + (sc.wantsFiles ? "1" : "0") + "\n";
+    if (sc.kids.length > 0) {
+      out += "typeset -g A_" + ident + "_" + i + "_cmds=(";
+      for (const ch of sc.kids) {
+        out += " '" + escShellSingleQuoted(ch.key) + ":" + escShellSingleQuoted(ch.description) + "'";
+      }
+      out += ")\n";
+    }
+  }
+  return out;
+}
+
+function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" w=\"$2\" nw=\"$3\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    o += "    " + i + ")\n";
+    o += "      case $w in\n";
+    o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
+    if (sc.path === "") {
+      o += "        " + kSchemaLong + ") echo 1 ;;\n";
+    }
+    for (const op of sc.opts) {
+      const base = "--" + op.name;
+      if (op.kind === "presence") {
+        o += "        " + base + "|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base);
+      } else {
+        o += "        " + base + "=*) echo 1 ;;\n";
+        o += "        " + base + ") echo 2 ;;\n";
+      }
+    }
+    o += "        *) echo 0 ;;\n";
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "    *) echo 0 ;;\n";
+  o += "  esac\n";
+  o += "}\n";
+  return o;
+}
+
+function emitConsumeShortZsh(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" w=\"$2\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    o += "    " + i + ")\n";
+    o += "      local rest=${w#-}\n";
+    o += "      local ch\n";
+    o += "      local saw=0\n";
+    o += "      while [[ -n $rest ]]; do\n";
+    o += "        ch=${rest[1,1]}\n";
+    o += "        rest=${rest[2,-1]}\n";
+    o += "        case $ch in\n";
+    let boolChars = "";
+    for (const op of sc.opts) {
+      if (!op.shortName) continue;
+      if (op.kind === "presence") {
+        boolChars += op.shortName + "|";
+      } else {
+        o += "          " + op.shortName + ")\n";
+        o += "            if [[ $saw -ne 0 || -n $rest ]]; then echo 0; return; fi\n";
+        o += "            echo 2; return ;;\n";
+      }
+    }
+    if (boolChars.length > 0) {
+      boolChars = boolChars.slice(0, -1);
+      o += "          " + boolChars + ") ;;\n";
+    }
+    o += "          *) echo 0; return ;;\n";
+    o += "        esac\n";
+    o += "        saw=1\n";
+    o += "      done\n";
+    o += "      echo 1\n";
+    o += "      ;;\n";
+  }
+  o += "    *) echo 0 ;;\n";
+  o += "  esac\n";
+  o += "}\n";
+  return o;
+}
+
+function emitMatchChildZsh(ident: string, scopes: ScopeRec[], pathIndex: Record<string, number>): string {
+  let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" w=\"$2\"\n";
+  o += "  case $sid in\n";
+  for (const [sid, sc] of scopes.entries()) {
+    if (sc.kids.length === 0) continue;
+    o += "    " + sid + ")\n";
+    o += "      case $w in\n";
+    for (const ch of sc.kids) {
+      const childPath = sc.path === "" ? ch.key : sc.path + "/" + ch.key;
+      const cid = pathIndex[childPath] ?? 0;
+      o += "        " + ch.key + ") echo " + cid + "; return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
+function emitSimulateZsh(ident: string): string {
+  let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
+  o += "  local i=2 sid=0 w steps next\n";
+  o += "  while (( i < CURRENT )); do\n";
+  o += "    w=$words[i]\n";
+  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " || $w == " + kSchemaLong + " ]]; then\n";
+  o += "      ((i++)); continue\n";
+  o += "    fi\n";
+  o += "    if [[ $w == --* ]]; then\n";
+  o += "      steps=$(_${ident}_nac_consume_long \"$sid\" \"$w\" \"${words[i+1]}\")\n".replace("${ident}", ident);
+  o += "      case $steps in\n";
+  o += "        0) break ;;\n";
+  o += "        1) ((i++)) ;;\n";
+  o += "        2) ((i+=2)) ;;\n";
+  o += "        *) break ;;\n";
+  o += "      esac\n";
+  o += "      continue\n";
+  o += "    fi\n";
+  o += "    if [[ $w == -* ]]; then\n";
+  o += "      steps=$(_${ident}_nac_consume_short \"$sid\" \"$w\")\n".replace("${ident}", ident);
+  o += "      case $steps in\n";
+  o += "        0) break ;;\n";
+  o += "        1) ((i++)) ;;\n";
+  o += "        2) ((i++)); break ;;\n";
+  o += "        *) break ;;\n";
+  o += "      esac\n";
+  o += "      continue\n";
+  o += "    fi\n";
+  o += "    next=$(_${ident}_nac_match_child \"$sid\" \"$w\") || break\n".replace("${ident}", ident);
+  o += "    sid=$next\n";
+  o += "    ((i++))\n";
+  o += "  done\n";
+  o += "  REPLY_SID=$sid\n";
+  o += "}\n";
+  return o;
+}
+
+function emitEnumReplyZsh(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
+  o += "  local sid=$1 prev=$2\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    if (enumOpts.length === 0) continue;
+    o += "    " + i + ")\n";
+    o += "      case $prev in\n";
+    for (const op of enumOpts) {
+      const vals = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
+      o += "        --" + op.name + ") _values " + vals + "; return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
+function emitMainBodyZsh(schema: CliRouter, ident: string): string {
+  const main = mainName(schema.key);
+  let o = "_${main}() {\n".replace("${main}", main);
+  o += "  local curcontext=\"$curcontext\" ret=1\n";
+  o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
+  o += "  local sid=$REPLY_SID\n";
+  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$words[CURRENT-1]\"; then return 0; fi\n".replace("${ident}", ident);
+  o += "  if [[ $PREFIX == -* ]]; then\n";
+  o += "    local -a optsarr\n";
+  o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
+  o += "    optsarr=(${(@P)oname})\n";
+  o += "    _describe -t options 'option' optsarr && ret=0\n";
+  o += "  else\n";
+  o += "    local lname=\"A_${ident}_${sid}_leaf\"\n".replace("${ident}", ident);
+  o += "    if [[ ${(P)lname} -eq 0 ]]; then\n";
+  o += "      local -a cmdsarr\n";
+  o += "      local cname=\"A_${ident}_${sid}_cmds\"\n".replace("${ident}", ident);
+  o += "      cmdsarr=(${(@P)cname})\n";
+  o += "      _describe -t commands 'command' cmdsarr && ret=0\n";
+  o += "    else\n";
+  o += "      local pname=\"A_${ident}_${sid}_pos\"\n".replace("${ident}", ident);
+  o += "      if [[ ${(P)pname} -eq 1 ]]; then\n";
+  o += "        _files && ret=0\n";
+  o += "      fi\n";
+  o += "    fi\n";
+  o += "  fi\n";
+  o += "  return ret\n";
+  o += "}\n\n";
+  o += "compdef _${main} ${schema.key}\n".replace("${main}", main).replace("${schema.key}", schema.key);
+  return o;
+}
+
+/** Returns a self-contained zsh completion script for the given program schema. */
+export function completionZshScript(schema: CliRouter): string {
+  const ident = identToken(schema.key);
+  const scopes = collectScopes(schema);
+  const pathIndex: Record<string, number> = {};
+  for (const [i, s] of scopes.entries()) {
+    pathIndex[s.path] = i;
+  }
+
+  let out = "#compdef " + schema.key + "\n\n";
+  out += emitScopeArraysZsh(ident, scopes);
+  out += emitConsumeLongZsh(ident, scopes);
+  out += emitConsumeShortZsh(ident, scopes);
+  out += emitMatchChildZsh(ident, scopes, pathIndex);
+  out += emitSimulateZsh(ident);
+  out += emitEnumReplyZsh(ident, scopes);
+  out += emitMainBodyZsh(schema, ident);
+  return out;
+}

package/src/builtins/dispatch.ts

@@ -0,0 +1,138 @@
+import { resolveCapabilities } from "../capabilities.ts";
+import type { CliNode, CliProgram, CliRouter } from "../types.ts";
+import { isCliLeaf, isCliRouter } 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 { cliPresentationRoot } from "./presentation.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: CliRouter;
+}
+
+function completionSchema(program: CliProgram, opts: DispatchBuiltinOpts): CliRouter {
+  if (opts.isLeafCompletionIntercept) {
+    return cliPresentationRoot(program);
+  }
+  return opts.parseRoot;
+}
+
+/**
+ * Handles built-in commands after parse.
+ */
+export async function dispatchBuiltin(
+  program: CliProgram,
+  pr: ParseResult,
+  opts: DispatchBuiltinOpts,
+): Promise<void> {
+  if (pr.kind !== ParseKind.Ok) {
+    return;
+  }
+
+  const caps = resolveCapabilities(program);
+
+  if (pr.path[0] === "completion") {
+    const schemaForCompletion = completionSchema(program, opts);
+    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 (!caps.mcp) {
+      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(program);
+    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 (!caps.install) {
+      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(program, pr.opts);
+  }
+}
+
+/** Built-in intercept roots for leaf programs. */
+export function builtinInterceptRoot(
+  program: CliProgram,
+  argv: string[],
+): { parseRoot: CliNode; isLeafCompletionIntercept: boolean } {
+  if (!isCliLeaf(program) || argv.length < 1) {
+    return { parseRoot: program, isLeafCompletionIntercept: false };
+  }
+
+  const caps = resolveCapabilities(program);
+  const first = argv[0];
+
+  if (first === "completion") {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [completionGroup(program.key)],
+      },
+      isLeafCompletionIntercept: true,
+    };
+  }
+
+  if (first === "install" && caps.install) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinInstallCommand(program)],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
+  if (first === "mcp" && caps.mcp) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinMcpCommand()],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
+  return { parseRoot: program, isLeafCompletionIntercept: false };
+}

package/src/builtins/export.ts

@@ -0,0 +1,53 @@
+import { type CliCapabilities, resolveCapabilities } from "../capabilities.ts";
+import type { CliFallbackMode, CliOption, CliPositional, CliProgram } from "../types.ts";
+import { cliBuiltinCompletionGroup } from "./completion-group.ts";
+import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.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: {
+  key: string;
+  description: string;
+  notes?: string;
+  options?: CliOption[];
+  commands?: CliSchemaExport[];
+}): 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(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
+  const resolved = caps ?? resolveCapabilities(program);
+  const builtins: CliSchemaExport[] = [exportBuiltinNode(cliBuiltinCompletionGroup(program.key))];
+  if (resolved.install) {
+    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
+  }
+  if (resolved.mcp) {
+    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 { CliProgram, CliOption, CliOptionKind, type CliLeaf } from "../types.ts";
+
+/** Install command options (dynamic: `--mcp` only when MCP is enabled). */
+export function installBuiltinOptions(root: CliProgram): 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: CliProgram): CliLeaf {
+  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 { type CliLeaf } from "../types.ts";
+
+/** Presence options for the top-level `mcp` built-in (leaf). */
+export function cliBuiltinMcpCommand(): CliLeaf {
+  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: () => {},
+  };
+}