argsbarg 4.1.0 → 4.1.1

package/src/builtins/builtins.test.ts

@@ -6,6 +6,7 @@ import { completionBashScript, completionFishScript, completionZshScript } from
 import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliParseRoot, cliPresentationRoot } from "./presentation.ts";
+import { cliBuiltinUninstallCommand, uninstallBuiltinOptions } from "./uninstall.ts";
 
 const fixture: CliProgram = {
   key: "myapp",
@@ -22,22 +23,32 @@ const fixture: CliProgram = {
 };
 
 describe("builtins help copy", () => {
-  test("install command includes description and option text", () => {
+  test("install command includes Homebrew-oriented description", () => {
     const install = cliBuiltinInstallCommand(fixture);
-    expect(install.description).toContain("shell completions");
-    expect(install.notes).toContain("install --all");
+    expect(install.description).toContain("agent skills");
+    expect(install.notes).toContain("brew install");
     const names = installBuiltinOptions(fixture).map((o) => o.name);
     expect(names).toContain("all");
     expect(names).toContain("mcp");
+    expect(names).not.toContain("app");
+    expect(names).not.toContain("completions");
+    expect(names).not.toContain("update");
     expect(names.indexOf("all")).toBeLessThan(names.indexOf("mcp"));
     expect(names.indexOf("mcp")).toBeLessThan(names.indexOf("status"));
-    expect(names.indexOf("status")).toBeLessThan(names.indexOf("uninstall"));
-    expect(names.indexOf("uninstall")).toBeLessThan(names.indexOf("from"));
-    expect(names.indexOf("from")).toBeLessThan(names.indexOf("yes"));
+    expect(names).not.toContain("uninstall");
     const yesOpt = installBuiltinOptions(fixture).find((o) => o.name === "yes");
     expect(yesOpt?.shortName).toBe("y");
   });
 
+  test("uninstall command includes removal guidance", () => {
+    const uninstall = cliBuiltinUninstallCommand(fixture);
+    expect(uninstall.notes).toContain("brew uninstall");
+    const names = uninstallBuiltinOptions(fixture).map((o) => o.name);
+    expect(names).toContain("all");
+    expect(names).not.toContain("status");
+    expect(names).not.toContain("reinstall");
+  });
+
   test("install -y parses as --yes", () => {
     const root = cliParseRoot(fixture);
     const pr = postParseValidate(root, parse(root, ["install", "-y"]));
@@ -53,23 +64,10 @@ describe("builtins help copy", () => {
     expect(names).not.toContain("mcp");
   });
 
-  test("install omits --update when updateGetLatest unset", () => {
+  test("install notes mention brew upgrade", () => {
     const install = cliBuiltinInstallCommand(fixture);
-    expect(installBuiltinOptions(fixture).map((o) => o.name)).not.toContain("update");
-    expect(install.notes).not.toContain("Upgrade to latest release");
-    expect(install.notes).toContain("Refresh after upgrading");
-  });
-
-  test("install notes include upgrade section when updateGetLatest is set", () => {
-    const withUpdate: CliProgram = {
-      ...fixture,
-      install: { updateGetLatest: async () => ({ path: process.execPath }) },
-    };
-    const install = cliBuiltinInstallCommand(withUpdate);
-    const notes = install.notes ?? "";
-    expect(installBuiltinOptions(withUpdate).map((o) => o.name)).toContain("update");
-    expect(notes).toContain("Upgrade to latest release");
-    expect(notes.indexOf("install --reinstall")).toBeLessThan(notes.indexOf("install --update"));
+    expect(install.notes).toContain("brew upgrade");
+    expect(install.notes).toContain("install --configure");
   });
 
   test("mcp builtin description is user-facing", () => {
@@ -90,6 +88,7 @@ describe("presentation root", () => {
     const keys = root.commands?.map((c) => c.key) ?? [];
     expect(keys).toContain("mcp");
     expect(keys).toContain("install");
+    expect(keys).toContain("uninstall");
   });
 
   test("omits install when install.enabled is false", () => {
@@ -159,6 +158,6 @@ describe("schema export builtins", () => {
   test("exportPresentationBuiltins includes install options", () => {
     const builtins = exportPresentationBuiltins(fixture);
     const install = builtins.find((b) => b.key === "install");
-    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("app");
+    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("agent");
   });
 });

package/src/builtins/completion-group.ts

@@ -1,13 +1,12 @@
 import { resolveCapabilities } from "../capabilities.ts";
-import type { CliProgram, CliRouter } from "../types.ts";
+import type { CliProgram } from "../types.ts";
 
 /**
  * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).
  */
-export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
+export function cliBuiltinCompletionGroup(program: CliProgram): import("../types.ts").CliRouter {
   const appName = program.key;
-  const caps = resolveCapabilities(program);
-  const router: CliRouter = {
+  const router: import("../types.ts").CliRouter = {
     key: "completion",
     description: "Generate the autocompletion script for shells.",
     commands: [
@@ -15,9 +14,9 @@ export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
         key: "bash",
         description: "Print a bash tab-completion script.",
         notes:
-          "Manual install:\n\n" +
-          `  ${appName} completion bash > ~/.bash_completion.d/${appName}\n` +
-          `  echo 'source ~/.bash_completion.d/${appName}' >> ~/.bashrc\n\n` +
+          "Homebrew installs completions during `brew install` via generate_completions_from_executable.\n\n" +
+          "Ensure your shell loads Homebrew completions:\n" +
+          "  https://docs.brew.sh/Shell-Completion\n\n" +
           "Try this session only:\n\n" +
           `  source <(${appName} completion bash)`,
         handler: () => {},
@@ -26,9 +25,9 @@ export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
         key: "zsh",
         description: "Print a zsh tab-completion script.",
         notes:
-          "Manual install:\n\n" +
-          `  ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
-          "Ensure ~/.zsh/completions is on your fpath, then restart zsh.\n\n" +
+          "Homebrew installs completions to $(brew --prefix)/share/zsh/site-functions.\n\n" +
+          "Ensure brew shellenv + compinit are configured:\n" +
+          "  https://docs.brew.sh/Shell-Completion\n\n" +
           "Try this session only:\n\n" +
           `  eval "$(${appName} completion zsh)"`,
         handler: () => {},
@@ -37,15 +36,18 @@ export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
         key: "fish",
         description: "Print a fish tab-completion script.",
         notes:
-          "Manual install:\n\n" +
-          `  ${appName} completion fish > ~/.config/fish/completions/${appName}.fish\n\n` +
-          "Fish loads completions from that directory automatically.",
+          "Homebrew installs completions to $(brew --prefix)/share/fish/vendor_completions.d.\n\n" +
+          "See: https://docs.brew.sh/Shell-Completion\n\n" +
+          "Try this session only:\n\n" +
+          `  ${appName} completion fish | source`,
         handler: () => {},
       },
     ],
   };
-  if (caps.install) {
-    router.notes = `Install for all shells:\n\n  ${appName} install --completions --yes`;
+  if (resolveCapabilities(program).install) {
+    router.notes =
+      "Completions are installed by Homebrew during formula install.\n\n" +
+      "See: https://docs.brew.sh/Shell-Completion";
   }
   return router;
 }

package/src/builtins/dispatch.ts

@@ -1,7 +1,7 @@
 import { capabilityDeniedMessage, resolveCapabilities } from "../capabilities.ts";
 import { Cli } from "../cli.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
-import { cliInstall } from "../install/index.ts";
+import { cliInstall, cliUninstall } from "../install/index.ts";
 import { runMcpBundle } from "../mcp/bundle.ts";
 import type { ParseResult } from "../parse.ts";
 import { ParseKind } from "../parse.ts";
@@ -15,6 +15,7 @@ import { cliBuiltinConfigGroupIfEnabled } from "./config.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
+import { cliBuiltinUninstallCommand } from "./uninstall.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 
 export interface DispatchBuiltinOpts {
@@ -103,6 +104,18 @@ export async function dispatchBuiltin(
     }
     await cliInstall(program, pr.opts);
   }
+
+  if (pr.path[0] === "uninstall") {
+    if (!caps.install) {
+      process.stderr.write(capabilityDeniedMessage("install"));
+      process.exit(1);
+    }
+    if (pr.path.length !== 1) {
+      process.stderr.write(`Unknown subcommand: uninstall ${pr.path.slice(1).join(" ")}\n`);
+      process.exit(1);
+    }
+    await cliUninstall(program, pr.opts);
+  }
 }
 
 /** Built-in intercept roots for leaf programs. */
@@ -139,6 +152,17 @@ export function builtinInterceptRoot(
     };
   }
 
+  if (first === "uninstall" && caps.install) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinUninstallCommand(program)],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
   if (first === "mcp" && caps.mcp) {
     return {
       parseRoot: {

package/src/builtins/install.ts

@@ -6,19 +6,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
   const opts: CliOption[] = [
     {
       name: "all",
-      description:
-        "Install the default set (app, shell completions, and configuration when supported).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "app",
-      description: "Copy this app 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).",
+      description: "Install agent skills and MCP config (default artifact set for this app).",
       kind: CliOptionKind.Presence,
     },
     {
@@ -41,8 +29,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
   if (root.appConfig) {
     opts.push({
       name: "configure",
-      description:
-        "Run the configuration wizard (install), or remove the config file (--uninstall).",
+      description: "Run the interactive configuration wizard.",
       kind: CliOptionKind.Presence,
     });
   }
@@ -55,31 +42,10 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "reinstall",
-      description: "Refresh everything already installed for this app.",
-      kind: CliOptionKind.Presence,
-    },
-  );
-
-  if (resolveCapabilities(root).update) {
-    opts.push({
-      name: "update",
-      description: "Download the latest release and refresh installed files.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  opts.push(
-    {
-      name: "uninstall",
       description:
-        "Remove installed files (--all removes everything; use individual flags to remove one category).",
+        "Refresh installed agent artifacts (skills, MCP). Used by Homebrew post_install.",
       kind: CliOptionKind.Presence,
     },
-    {
-      name: "from",
-      description: "App executable to copy (default: running executable). Used with --reinstall.",
-      kind: CliOptionKind.String,
-    },
     {
       name: "yes",
       description: "Skip the confirmation prompt.",
@@ -93,7 +59,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "json",
-      description: "Print changed paths (install/update/uninstall) or status JSON on stdout.",
+      description: "Print changed paths (install/reinstall) or status JSON on stdout.",
       kind: CliOptionKind.Presence,
     },
   );
@@ -105,30 +71,34 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
 export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
   const app = root.key;
   const notesLines = [
-    "First-time setup:",
-    `  ${app} install --yes`,
+    "Install the binary via Homebrew (tap-from-repo), then refresh agent artifacts:",
+    `  brew tap <org>/<repo>`,
+    `  brew install <tap>/${app}`,
     "",
-    "Refresh after upgrading:",
-    `  ${app} install --reinstall`,
-  ];
-  if (resolveCapabilities(root).update) {
-    notesLines.push("", "Upgrade to latest release:", `  ${app} install --update`);
-  }
-  notesLines.push(
+    "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 everything installed with --all:",
-    `  ${app} install --uninstall --all --yes`,
+    "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 this app, shell completions, agent skills, and MCP config on your machine.",
+    description: "Install agent skills and MCP config for this app (binary via Homebrew).",
     options: installBuiltinOptions(root),
     notes: notesLines.join("\n"),
     handler: () => {},

package/src/builtins/registry.ts

@@ -5,6 +5,7 @@ import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinConfigGroupIfEnabled } from "./config.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinUninstallCommand } from "./uninstall.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 
 type BuiltinFactory = (program: CliProgram) => CliNode | null;
@@ -30,6 +31,7 @@ export function resolveBuiltins(program: CliProgram, caps: CliCapabilities): Cli
   pushBuiltin(builtins, program, () => cliBuiltinVersionCommand());
   if (caps.install) {
     pushBuiltin(builtins, program, (p) => cliBuiltinInstallCommand(p));
+    pushBuiltin(builtins, program, (p) => cliBuiltinUninstallCommand(p));
   }
   pushBuiltin(builtins, program, (p) => cliBuiltinDocsGroupIfEnabled(p) ?? null);
   if (caps.mcp) {

package/src/builtins/uninstall.ts

@@ -0,0 +1,80 @@
+import { resolveCapabilities } from "../capabilities.ts";
+import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram } from "../types.ts";
+
+/** Uninstall command options (dynamic: `--mcp` only when MCP is enabled). */
+export function uninstallBuiltinOptions(root: CliProgram): CliOption[] {
+  const opts: CliOption[] = [
+    {
+      name: "all",
+      description: "Remove all detected agent artifacts (default when no scope flags are given).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "skill",
+      description: "Remove agent skills only.",
+      kind: CliOptionKind.Presence,
+    },
+  ];
+
+  if (resolveCapabilities(root).mcp) {
+    opts.push({
+      name: "mcp",
+      description: "Remove MCP server configuration only.",
+      kind: CliOptionKind.Presence,
+    });
+  }
+
+  if (root.appConfig) {
+    opts.push({
+      name: "configure",
+      description: "Remove the app config file only.",
+      kind: CliOptionKind.Presence,
+    });
+  }
+
+  opts.push(
+    {
+      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 on stdout.",
+      kind: CliOptionKind.Presence,
+    },
+  );
+
+  return opts;
+}
+
+/** Builds the `uninstall` built-in command. */
+export function cliBuiltinUninstallCommand(root: CliProgram): CliLeaf {
+  const app = root.key;
+  const notesLines = [
+    "Remove agent artifacts installed by this app (skills, MCP, config).",
+    "Run before `brew uninstall` while the CLI is still on PATH:",
+    "",
+    `  ${app} uninstall --yes`,
+    `  brew uninstall <tap>/${app}`,
+    "",
+    "Remove app config only:",
+    `  ${app} uninstall --configure --yes`,
+    "",
+    "Use --dry to preview changes without writing files.",
+    "Use --json for machine-readable output.",
+  ];
+  return {
+    key: "uninstall",
+    description: "Remove agent skills, MCP config, and app config for this app.",
+    options: uninstallBuiltinOptions(root),
+    notes: notesLines.join("\n"),
+    handler: () => {},
+  };
+}

package/src/capabilities.ts

@@ -12,7 +12,6 @@ export interface CliCapabilities {
   mcp: boolean;
   install: boolean;
   docs: boolean;
-  update: boolean;
   configCommands: boolean;
 }
 
@@ -24,7 +23,6 @@ export function resolveCapabilities(program: CliProgram): CliCapabilities {
     mcp: program.mcpServer?.enabled === true,
     install,
     docs: program.docs?.enabled === true,
-    update: install && typeof program.install?.updateGetLatest === "function",
     configCommands: configCommandsEnabled(program),
   };
 }
@@ -33,7 +31,7 @@ export function resolveCapabilities(program: CliProgram): CliCapabilities {
 export function reservedCommandNames(caps: CliCapabilities): string[] {
   const names = ["completion", "version"];
   if (caps.install) {
-    names.push("install");
+    names.push("install", "uninstall");
   }
   if (caps.docs) {
     names.push("docs");

package/src/cli-tool/cli-smoke.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+const main = join(import.meta.dir, "main.ts");
+
+describe("argsbarg cli-tool", () => {
+  test("version subcommand prints version", () => {
+    const proc = spawnSync("bun", [main, "version"], { encoding: "utf8" });
+    expect(proc.status).toBe(0);
+    expect(proc.stdout.trim().length).toBeGreaterThan(0);
+  });
+
+  test("completion subcommand emits bash script", () => {
+    const proc = spawnSync("bun", [main, "completion", "bash"], { encoding: "utf8" });
+    expect(proc.status).toBe(0);
+    expect(proc.stdout).toContain("complete");
+  });
+});

package/src/cli-tool/create.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  applyCreate,
+  classNameFromKey,
+  diffCreate,
+  diffCreateDetails,
+  renderCreateTree,
+  substituteTemplateContent,
+} from "./create.ts";
+
+describe("argsbarg create", () => {
+  test("substitutes {key} tokens", () => {
+    const out = substituteTemplateContent(
+      "key={key} class={className} env={envPrefix}_API_TOKEN tap={tap} org={tapOrg}",
+      {
+        key: "my-cli",
+        className: "MyCli",
+        tap: "org/my-cli",
+        homepage: "https://github.com/org/my-cli",
+        releaseRepo: "org/my-cli",
+        desc: "My CLI",
+        force: false,
+        dryRun: false,
+        check: false,
+        diff: false,
+        yes: false,
+        devTemplate: false,
+      },
+    );
+    expect(out).toContain("my-cli");
+    expect(out).toContain("MyCli");
+    expect(out).toContain("MY_CLI_API_TOKEN");
+    expect(out).toContain("org/my-cli");
+    expect(out).not.toContain("{key}");
+  });
+
+  test("classNameFromKey", () => {
+    expect(classNameFromKey("sqsp-i18n")).toBe("SqspI18n");
+  });
+
+  test("renderCreateTree includes justfile and create-identity", () => {
+    const tree = renderCreateTree({
+      key: "testapp",
+      className: "Testapp",
+      tap: "local/testapp",
+      homepage: "https://example.com",
+      releaseRepo: "example/testapp",
+      desc: "Test",
+      force: false,
+      dryRun: false,
+      check: false,
+      diff: false,
+      yes: false,
+      devTemplate: false,
+    });
+    expect(tree.has("justfile")).toBe(true);
+    expect(tree.has("biome.json")).toBe(true);
+    expect(tree.has(".cursor/rules/code.mdc")).toBe(true);
+    expect(tree.has("scripts/create-identity.ts")).toBe(true);
+    const identity = tree.get("scripts/create-identity.ts");
+    expect(identity).toContain('key: "testapp"');
+    const formula = tree.get("scripts/formula-shared.ts");
+    expect(formula).toContain("create-identity.ts");
+  });
+
+  test("--check detects drift", () => {
+    const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
+    try {
+      applyCreate(dir, {
+        key: "testapp",
+        className: "Testapp",
+        tap: "local/testapp",
+        homepage: "https://example.com",
+        releaseRepo: "example/testapp",
+        desc: "Test",
+        force: true,
+        dryRun: false,
+        check: false,
+        diff: false,
+        yes: false,
+        devTemplate: false,
+      });
+      expect(diffCreate(dir, { key: "testapp", className: "Testapp" })).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("--check infers options from create-identity.ts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
+    try {
+      applyCreate(dir, {
+        key: "testapp",
+        className: "Testapp",
+        tap: "local/testapp",
+        homepage: "https://example.com",
+        releaseRepo: "example/testapp",
+        desc: "Test",
+        force: true,
+        dryRun: false,
+        check: false,
+        diff: false,
+        yes: false,
+        devTemplate: false,
+      });
+      expect(diffCreate(dir, { check: true })).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("--diff captures drift details", () => {
+    const drifts = diffCreateDetails("/nonexistent", { key: "x" });
+    expect(drifts.length).toBeGreaterThan(0);
+  });
+});