argsbarg 4.1.1 → 5.0.1

package/src/mcp.integration.test.ts

@@ -35,7 +35,7 @@ test("collectMcpTools lists user leaf commands only", () => {
   expect(names).toContain("stat_owner_lookup");
   expect(names).toContain("read");
   expect(names).not.toContain("hidden");
-  expect(names).not.toContain("install");
+  expect(names).not.toContain("configure");
   expect(names).not.toContain("mcp");
   expect(names).not.toContain("completion");
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -242,19 +242,19 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
-test("reserved command name install is rejected", () => {
+test("reserved command name configure is rejected", () => {
   const root = testProgram({
     key: "app",
     description: "",
     commands: [
       {
-        key: "install",
+        key: "configure",
         description: "bad",
         handler: () => {},
       },
     ],
   });
-  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: install/);
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: configure/);
 });
 
 test("top-level command name mcp is allowed without mcpServer", () => {

package/src/parse.test.ts

@@ -526,10 +526,8 @@ test("docs schema exports JSON for leaf roots", async () => {
   expect(schema.positionals[0].name).toBe("name");
   expect(schema.options[0].name).toBe("verbose");
   expect(schema.commands.map((c: { key: string }) => c.key)).toEqual([
-    "completion",
     "version",
-    "install",
-    "uninstall",
+    "configure",
     "docs",
   ]);
 });
@@ -540,11 +538,11 @@ test("version builtin prints program version", async () => {
   expect(stdout.toString().trim()).toMatch(/^\d+\.\d+\.\d+/);
 });
 
-test("leaf root help lists completion built-in", async () => {
+test("leaf root help omits hidden completion built-in", async () => {
   const { stdout, exitCode } = await $`bun run examples/minimal.ts -h`.nothrow().quiet();
   expect(exitCode).toBe(0);
-  expect(stdout.toString()).toContain("completion");
-  expect(stdout.toString()).toContain("Generate the autocompletion script for shells.");
+  expect(stdout.toString()).not.toContain("completion");
+  expect(stdout.toString()).toContain("configure");
 });
 
 test("root --schema is no longer a flag", () => {
@@ -1108,7 +1106,7 @@ test("mcpToolCallToArgv empty array varargs errors when required", () => {
 
 // ── Skills ────────────────────────────────────────────────────────────────────
 
-test("install config on non-root node is rejected", () => {
+test("configure config on non-root node is rejected", () => {
   const root = {
     key: "app",
     version: "0.0.0",
@@ -1117,23 +1115,23 @@ test("install config on non-root node is rejected", () => {
       {
         key: "x",
         description: "",
-        install: { enabled: false },
+        configure: { enabled: false },
         handler: () => {},
       },
     ],
   } as unknown as CliProgram;
-  expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
+  expect(() => cliValidateProgram(root)).toThrow(/configure is only supported on the program root/);
 });
 
-test("install.prefix is rejected", () => {
+test("configure.prefix is rejected", () => {
   const root = {
     key: "app",
     version: "0.0.0",
     description: "",
-    install: { prefix: "/opt/bin" },
+    configure: { prefix: "/opt/bin" },
     handler: () => {},
   } as unknown as CliProgram;
-  expect(() => cliValidateProgram(root)).toThrow(/install\.prefix removed/);
+  expect(() => cliValidateProgram(root)).toThrow(/configure\.prefix removed/);
 });
 
 test("generateSkillBundle includes frontmatter and compact command index", () => {
@@ -1184,7 +1182,7 @@ test("cliSkillInstall writes project Cursor skill files", () => {
     expect(readFileSync(join(skillDir, "reference.md"), "utf8")).toContain("CLI API reference");
     const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
     expect(skillText.startsWith("---\n")).toBe(true);
-    const hint = "<!-- Generated by nested.ts install --skill; do not edit. -->";
+    const hint = "<!-- Generated by nested.ts configure; do not edit. -->";
     expect(skillText.indexOf(hint)).toBeGreaterThan(skillText.indexOf("---\n", 4));
     const refText = readFileSync(join(skillDir, "reference.md"), "utf8");
     expect(refText.startsWith(hint)).toBe(true);

package/src/schema.ts

@@ -13,15 +13,7 @@ import {
   leafOutputSchema,
 } from "./types.ts";
 
-const RESERVED = new Set([
-  "completion",
-  "install",
-  "uninstall",
-  "docs",
-  "mcp",
-  "version",
-  "config",
-]);
+const RESERVED = new Set(["completion", "configure", "docs", "mcp", "version", "config"]);
 
 function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
   if (cmd.hidden) {

package/src/skill/hint.ts

@@ -23,9 +23,9 @@ export function insertGeneratedHint(
   return `${hint}${content}`;
 }
 
-/** Hint for `install --skill` output files. */
+/** Hint for `configure` skill output files. */
 export function skillInstallHint(program: CliProgram): string {
-  return generatedFileHtmlComment(`${program.key} install --skill`);
+  return generatedFileHtmlComment(`${program.key} configure`);
 }
 
 /** Applies install hints to SKILL.md (after frontmatter) and reference.md. */

package/src/types.ts

@@ -261,18 +261,24 @@ export interface CliAppConfig {
   entries: Record<string, CliAppConfigEntry>;
 }
 
-export interface CliInstallConfig {
-  /** When `false`, hide/disable `install` (default: enabled). */
+/** Opt-out for the `completion` built-in (default: enabled). */
+export interface CliCompletionConfig {
+  /** When `false`, hide/disable `completion` (default: enabled). */
+  enabled?: boolean;
+}
+
+export interface CliConfigureConfig {
+  /** When `false`, hide/disable `configure` (default: enabled). */
   enabled?: boolean;
   /**
-   * Default agent integration for full install (`install --all`).
-   * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in `--all`; paired skills excluded.
-   * - `'skill'` when MCP is off (default): skill targets in `--all`; paired MCP excluded.
-   * - `'both'`: install MCP and skill for the same host when both are available.
+   * Default agent integration for sync (`configure --sync`).
+   * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in sync; paired skills excluded.
+   * - `'skill'` when MCP is off (default): skill targets in sync; paired MCP excluded.
+   * - `'both'`: sync MCP and skill for the same host when both are available.
    */
   agentIntegration?: InstallAgentIntegration;
-  /** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
-  targets?: CliInstallTargets;
+  /** Per-artifact gates for configure sync and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
+  targets?: CliConfigureTargets;
 }
 
 /** Agent integration mode for install — MCP vs shell skill per host. */
@@ -284,7 +290,7 @@ export type InstallTargetSpec =
   | {
       /** When false, artifact is never installed (even with scoped CLI flags). Default true. */
       enabled?: boolean;
-      /** When true, included in bare `install` / `install --all`. Default varies by key. */
+      /** When true, included in `configure --sync`. Default varies by key. */
       includedInAll?: boolean;
     };
 
@@ -293,8 +299,8 @@ export interface ResolvedInstallTarget {
   includedInAll: boolean;
 }
 
-/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
-export interface CliInstallTargets {
+/** Per-artifact gates for configure. See {@link resolveEffectiveInstallTargets}. */
+export interface CliConfigureTargets {
   /** App binary status only (Homebrew PATH); no self-install. */
   app?: InstallTargetSpec;
   /** ChatGPT desktop MCP. Default false. */
@@ -309,7 +315,7 @@ export interface CliInstallTargets {
   codexMcp?: InstallTargetSpec;
   /** Codex skill. Default false. */
   codexSkill?: InstallTargetSpec;
-  /** App config: wizard via install --configure only. Default not in --all. */
+  /** App config: interactive wizard step in `configure`. Default not in sync. */
   configure?: InstallTargetSpec;
   /** Cursor MCP. Default false. */
   cursorMcp?: InstallTargetSpec;
@@ -414,8 +420,10 @@ export type CliProgram = CliNode & {
   appConfig?: CliAppConfig;
   /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
-  /** Opt-out and defaults for `install`. */
-  install?: CliInstallConfig;
+  /** Opt-out and defaults for `configure`. */
+  configure?: CliConfigureConfig;
+  /** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
+  completion?: CliCompletionConfig;
   /** When set with `enabled: true`, enables the `docs` built-in command group. */
   docs?: CliDocsConfig;
 };

package/src/validate.ts

@@ -127,28 +127,28 @@ function installTargetExplicitTruthy(spec: InstallTargetSpec | undefined): boole
   return spec.enabled !== false;
 }
 
-/** Validates `program.install` targets and agentIntegration. */
-function validateInstallConfig(program: CliProgram): void {
-  const install = program.install;
-  if (!install) return;
+/** Validates `program.configure` targets and agentIntegration. */
+function validateConfigureConfig(program: CliProgram): void {
+  const configure = program.configure;
+  if (!configure) return;
 
-  if ("prefix" in install) {
+  if ("prefix" in configure) {
     throw new CliSchemaValidationError(
-      "install.prefix removed; app installs to ~/.local/bin/<key>",
+      "configure.prefix removed; app binary installs via Homebrew",
     );
   }
 
-  if (!install.targets) return;
+  if (!configure.targets) return;
 
-  const targets = install.targets;
+  const targets = configure.targets;
   if ("allSkills" in targets || "allMcps" in targets) {
     throw new CliSchemaValidationError(
-      "install.targets.allSkills/allMcps removed; use agentIntegration and per-key targets",
+      "configure.targets.allSkills/allMcps removed; use agentIntegration and per-key targets",
     );
   }
 
   const integration: InstallAgentIntegration =
-    install.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
+    configure.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
 
   for (const [mcpKey, skillKey] of AGENT_PAIRS) {
     const mcpSpec = targets[mcpKey];
@@ -159,18 +159,18 @@ function validateInstallConfig(program: CliProgram): void {
 
     if (mcpOn && skillOn && integration !== "both") {
       throw new CliSchemaValidationError(
-        `install.targets: ${host} has both MCP and skill configured; set agentIntegration: 'both' or disable one side`,
+        `configure.targets: ${host} has both MCP and skill configured; set agentIntegration: 'both' or disable one side`,
       );
     }
 
     if (integration === "skill" && mcpOn) {
       throw new CliSchemaValidationError(
-        `install.targets.${mcpKey} requires agentIntegration: 'both' when agentIntegration is 'skill'`,
+        `configure.targets.${mcpKey} requires agentIntegration: 'both' when agentIntegration is 'skill'`,
       );
     }
     if (integration === "mcp" && skillOn) {
       throw new CliSchemaValidationError(
-        `install.targets.${skillKey} requires agentIntegration: 'both' when agentIntegration is 'mcp'`,
+        `configure.targets.${skillKey} requires agentIntegration: 'both' when agentIntegration is 'mcp'`,
       );
     }
   }
@@ -202,8 +202,8 @@ export function cliValidateProgram(program: CliProgram): void {
     validateConfigBlock(program.appConfig);
   }
 
-  if (program.install !== undefined) {
-    validateInstallConfig(program);
+  if (program.configure !== undefined) {
+    validateConfigureConfig(program);
   }
 
   const caps = resolveCapabilities(program);
@@ -228,9 +228,9 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
         `mcpServer is only supported on the program root (not on ${node.key})`,
       );
     }
-    if (rogue.install !== undefined) {
+    if (rogue.configure !== undefined) {
       throw new CliSchemaValidationError(
-        `install is only supported on the program root (not on ${node.key})`,
+        `configure is only supported on the program root (not on ${node.key})`,
       );
     }
     if (rogue.docs !== undefined) {

package/docs/install.md

@@ -1,206 +0,0 @@
-# Install command
-
-The `install` built-in manages **agent artifacts** (skills, MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
-
-Opt out with `install: { enabled: false }` on the program root.
-
-## End-user install (Homebrew)
-
-```bash
-brew tap <org>/<repo>
-brew install <tap>/<key>
-<key> install --configure    # when app config is required (interactive)
-```
-
-Upgrade with `brew upgrade <key>`. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
-
-**Uninstall the binary:** `brew uninstall <key>`. Remove agent artifacts first (while the CLI is still on PATH):
-
-```bash
-<key> uninstall --yes
-brew uninstall <tap>/<key>
-```
-
-## Developer install
-
-```bash
-just build
-just install-local    # same formula as production; gen-dev-formula uses file:// URL (`just install` is an alias)
-```
-
-Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> install --reinstall --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Use `just install-artifacts` to refresh agent artifacts without touching the binary.
-
-## Quick reference
-
-```bash
-# Refresh skills/MCP after upgrade (Homebrew post_install runs this automatically)
-<key> install --reinstall --yes
-
-# See what is installed
-<key> install --status
-
-# Configure app settings (interactive wizard — not part of --all or post_install)
-<key> install --configure
-
-# Remove agent artifacts (default: --all)
-<key> uninstall --yes
-```
-
-Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--reinstall`**) — see [Confirmation](#confirmation).
-
-## What gets installed
-
-| Target | Flag | Mechanism |
-| --- | --- | --- |
-| Binary | Homebrew formula | `bin.install` in Formula |
-| Shell completions | Homebrew formula | `generate_completions_from_executable` |
-| Cursor skill | `--skill` / `--all` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
-| Claude skill | `--skill` / `--all` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
-| Codex / OpenCode / OpenClaw skills | `--skill` / `--all` | Agent-specific dirs when available |
-| MCP config | `--mcp` / `--all` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
-| App config | `--configure` | Interactive wizard writes `~/.local/lib/<key>/config.json` |
-
-### Externally managed binary (Homebrew)
-
-When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
-
-- **`install --status`** shows `app: system (PATH)`
-- **`--all`** / **`--reinstall`** refresh skills and MCP only — not the binary or completions
-
-MCP config uses the command name on **`PATH`**, not a Cellar path.
-
-### Default `--all` behavior
-
-Bare **`install`** and **`install --all`** install targets with **`includedInAll: true`**. Core defaults:
-
-- **Agent integration** (`install.agentIntegration`, default from `mcpServer.enabled`):
-  - **`skill`** (default when MCP off): all `*Skill` keys in `--all`; paired `*Mcp` keys excluded
-  - **`mcp`** (default when `mcpServer.enabled`): all `*Mcp` keys in `--all`; paired skills excluded
-  - **`both`**: MCP and skill for the same host when available
-- **`configure`** is **opt-in** (`includedInAll: false`) — run **`install --configure`** separately
-
-Desktop-only MCP hosts (`claudeDesktopMcp`, `chatgptMcp`) follow the MCP side only — no skill pair.
-
-Scoped flags (`--skill`, `--mcp`, `--configure`) run that artifact category. Honor `enabled: false` as a hard off.
-
-Use **`install --status --json`** to preview effective targets before installing.
-
-### Asymmetric uninstall
-
-The top-level **`uninstall`** command removes agent artifacts. Bare **`uninstall`** is equivalent to **`uninstall --all`**.
-
-- **`uninstall --all`** removes **every detected artifact type**, ignoring `install.targets`.
-- Scoped uninstall (`--skill`, `--mcp`, `--configure`, …) removes only that category.
-
-Missing targets are skipped silently.
-
-## `install.targets`
-
-Configure which artifacts participate in `--all`, `--reinstall`:
-
-```typescript
-install: {
-  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
-  targets: {
-    chatgptMcp: false,
-    cursorSkill: { includedInAll: true },
-  },
-},
-```
-
-`InstallTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`.
-
-Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
-
-## App config (`program.appConfig`)
-
-When `program.appConfig` is set, ArgsBarg manages a flat JSON config file at `~/.local/lib/<sanitized-key>/config.json`.
-
-| Flag | Description |
-| --- | --- |
-| `--configure` | Interactive prompt; writes or updates the config file. **Not** included in `--all`. |
-| `--status` | Shows config path and which required keys are set or missing |
-
-Use **`uninstall --configure`** to remove the config directory.
-
-Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
-
-## `uninstall` command
-
-Sibling of `install` for removing agent artifacts:
-
-```bash
-<key> uninstall --yes              # all artifacts (default)
-<key> uninstall --configure --yes  # config only
-<key> uninstall --skill --yes      # skills only
-```
-
-Same behavior flags as install: `--yes`, `--dry`, `--json`. Does not support `--status` or `--reinstall`.
-
-## Flags (`install`)
-
-### Target flags
-
-| Flag | Description |
-| --- | --- |
-| `--all` | Install the default agent artifact set for this app |
-| `--skill` | Install agent skills |
-| `--mcp` | Add MCP server configuration |
-| `--configure` | Run the interactive configuration wizard |
-
-### Operation flags (`install`)
-
-| Flag | Description |
-| --- | --- |
-| `--status` | Read-only inventory |
-| `--reinstall` | Refresh installed agent artifacts (Homebrew `post_install`; greenfield → full `--all` plan) |
-| `--from <path>` | App executable reference for status detection (rare; default: running executable) |
-
-### Behavior flags
-
-| Flag | Description |
-| --- | --- |
-| `--yes`, `-y` | Skip confirmation |
-| `--dry` | Preview changes |
-| `--json` | Machine-readable output (implies `--yes`) |
-
-## Confirmation
-
-Install and uninstall (except `--yes`, `--json`, `--dry`, `--reinstall`) print a **`{app} Setup`** banner and numbered plan. Reply **`y`** for all, **`n`** or Enter to abort, or numbers for a subset.
-
-## MCP merge behavior
-
-When `--mcp` runs, entries are merged into host config with:
-
-```json
-{ "command": "<root.key>", "args": ["mcp"] }
-```
-
-If an existing entry differs, the command exits with an error unless `--yes` is passed.
-
-## Formula `post_install`
-
-Release formulae should run:
-
-```ruby
-def post_install
-  system bin/"myapp", "install", "--reinstall", "--yes"
-end
-```
-
-This refreshes skills/MCP without running the configure wizard (configure is opt-in).
-
-## Bootstrapping a new CLI
-
-```bash
-bunx argsbarg create my-cli --key my-cli --class-name MyCli --tap org/repo --yes
-bunx argsbarg create --check .
-```
-
-See [distribution-homebrew.md](distribution-homebrew.md) and [../examples/full-example/README.md](../examples/full-example/README.md).
-
-## Opt out
-
-```typescript
-install: { enabled: false },
-```

package/src/builtins/install.ts

@@ -1,106 +0,0 @@
-import { resolveCapabilities } from "../capabilities.ts";
-import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram } 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 agent skills and MCP config (default artifact set for this app).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "skill",
-      description:
-        "Install agent skills for Cursor, Claude, and other supported AI tools on this machine.",
-      kind: CliOptionKind.Presence,
-    },
-  ];
-
-  if (resolveCapabilities(root).mcp) {
-    opts.push({
-      name: "mcp",
-      description:
-        "Add MCP server configuration for Cursor, Claude Code, and other supported agents.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  if (root.appConfig) {
-    opts.push({
-      name: "configure",
-      description: "Run the interactive configuration wizard.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  opts.push(
-    {
-      name: "status",
-      description: "Print what is currently installed (read-only).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "reinstall",
-      description:
-        "Refresh installed agent artifacts (skills, MCP). Used by Homebrew post_install.",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "yes",
-      description: "Skip the confirmation prompt.",
-      kind: CliOptionKind.Presence,
-      shortName: "y",
-    },
-    {
-      name: "dry",
-      description: "Show what would change without writing files.",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "json",
-      description: "Print changed paths (install/reinstall) or status JSON on stdout.",
-      kind: CliOptionKind.Presence,
-    },
-  );
-
-  return opts;
-}
-
-/** Builds the `install` built-in command. */
-export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
-  const app = root.key;
-  const notesLines = [
-    "Install the binary via Homebrew (tap-from-repo), then refresh agent artifacts:",
-    `  brew tap <org>/<repo>`,
-    `  brew install <tap>/${app}`,
-    "",
-    "Homebrew post_install runs:",
-    `  ${app} install --reinstall --yes`,
-    "",
-    "Configure separately (interactive):",
-    `  ${app} install --configure`,
-    "",
-    "Upgrade:",
-    `  brew upgrade ${app}`,
-    "",
-    "Shell completions are installed by Homebrew during brew install.",
-    "See: https://docs.brew.sh/Shell-Completion",
-    "",
-    "See what is installed:",
-    `  ${app} install --status`,
-    "",
-    "Remove agent artifacts:",
-    `  ${app} uninstall --yes`,
-    "",
-    "Use --dry to preview changes without writing files.",
-    "Use --json for machine-readable output.",
-  ];
-  return {
-    key: "install",
-    description: "Install agent skills and MCP config for this app (binary via Homebrew).",
-    options: installBuiltinOptions(root),
-    notes: notesLines.join("\n"),
-    handler: () => {},
-  };
-}