argsbarg 6.2.2 → 6.3.0

package/examples/full-example-json/.cursor/hooks/run-tests-on-stop.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+/* Cursor stop hook: run `just test` on agent completion; follow up if it fails. */
+
+try {
+  const empty = () => {
+    console.log("{}");
+    process.exit(0);
+  };
+
+  const input = JSON.parse(await Bun.stdin.text()) as {
+    status?: string;
+    loop_count?: number;
+    workspace_roots?: string[];
+  };
+
+  if (input.status !== "completed") empty();
+
+  const cwd = input.workspace_roots?.[0] ?? process.cwd();
+  if (!(await Bun.file(`${cwd}/justfile`).exists())) empty();
+
+  const diff = Bun.spawnSync(["git", "diff", "--name-only", "HEAD"], { cwd, stdout: "pipe" });
+  const CODE_FILE = /\.(t|j)sx?$/i;
+  const SKIP_PREFIX = /^(node_modules|dist|\.cursor)\//;
+  const changed = new TextDecoder()
+    .decode(diff.stdout)
+    .split("\n")
+    .some(
+      (path) =>
+        path &&
+        (path === "justfile" || (CODE_FILE.test(path) && !SKIP_PREFIX.test(path))),
+    );
+  if (!changed) empty();
+
+  const proc = Bun.spawnSync(["just", "test"], {
+    cwd,
+    env: { ...process.env, FORCE_COLOR: "0" },
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const output =
+    new TextDecoder().decode(proc.stdout) + new TextDecoder().decode(proc.stderr);
+
+  if (proc.exitCode === 0) empty();
+
+  const lines = output.trimEnd().split("\n");
+  const tail = lines.length > 80 ? lines.slice(-80).join("\n") : output.trimEnd();
+  const n = (input.loop_count ?? 0) + 1;
+
+  console.log(
+    JSON.stringify({
+      followup_message: `Tests failed (auto-retry ${n}/20). Fix and ensure \`just test\` passes.\n\n\`\`\`\n${tail}\n\`\`\``,
+    }),
+  );
+} catch {
+  console.log("{}");
+}

package/examples/full-example-json/.cursor/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "stop": [
+      {
+        "command": "bun .cursor/hooks/run-tests-on-stop.ts",
+        "loop_limit": 20,
+        "timeout": 180
+      }
+    ]
+  }
+}

package/examples/full-example-json/Formula/full-example-json.rb

@@ -11,7 +11,7 @@ class FullExampleJson < Formula
   end
 
   def post_install
-    system bin/"full-example-json", "configure", "--sync", "--yes"
+    system bin/"full-example-json", "configure", "--refresh", "--yes"
   end
 
   def uninstall

package/examples/full-example-json/docs/cli-schema.json

@@ -21,10 +21,10 @@
         {
           "key": "configure",
           "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
           "options": [
             {
-              "name": "sync",
+              "name": "refresh",
               "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
               "kind": "presence"
             },
@@ -40,7 +40,7 @@
             },
             {
               "name": "yes",
-              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
               "kind": "presence",
               "shortName": "y"
             },
@@ -254,10 +254,10 @@
         {
           "key": "configure",
           "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
           "options": [
             {
-              "name": "sync",
+              "name": "refresh",
               "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
               "kind": "presence"
             },
@@ -273,7 +273,7 @@
             },
             {
               "name": "yes",
-              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
               "kind": "presence",
               "shortName": "y"
             },
@@ -509,10 +509,10 @@
         {
           "key": "configure",
           "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
           "options": [
             {
-              "name": "sync",
+              "name": "refresh",
               "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
               "kind": "presence"
             },
@@ -528,7 +528,7 @@
             },
             {
               "name": "yes",
-              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
               "kind": "presence",
               "shortName": "y"
             },
@@ -746,10 +746,10 @@
             {
               "key": "configure",
               "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-              "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+              "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
               "options": [
                 {
-                  "name": "sync",
+                  "name": "refresh",
                   "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
                   "kind": "presence"
                 },
@@ -765,7 +765,7 @@
                 },
                 {
                   "name": "yes",
-                  "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+                  "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
                   "kind": "presence",
                   "shortName": "y"
                 },
@@ -979,10 +979,10 @@
             {
               "key": "configure",
               "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-              "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+              "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
               "options": [
                 {
-                  "name": "sync",
+                  "name": "refresh",
                   "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
                   "kind": "presence"
                 },
@@ -998,7 +998,7 @@
                 },
                 {
                   "name": "yes",
-                  "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+                  "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
                   "kind": "presence",
                   "shortName": "y"
                 },
@@ -1216,10 +1216,10 @@
                 {
                   "key": "configure",
                   "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
                   "options": [
                     {
-                      "name": "sync",
+                      "name": "refresh",
                       "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
                       "kind": "presence"
                     },
@@ -1235,7 +1235,7 @@
                     },
                     {
                       "name": "yes",
-                      "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+                      "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
                       "kind": "presence",
                       "shortName": "y"
                     },
@@ -1449,10 +1449,10 @@
                 {
                   "key": "configure",
                   "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
                   "options": [
                     {
-                      "name": "sync",
+                      "name": "refresh",
                       "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
                       "kind": "presence"
                     },
@@ -1468,7 +1468,7 @@
                     },
                     {
                       "name": "yes",
-                      "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+                      "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
                       "kind": "presence",
                       "shortName": "y"
                     },
@@ -1682,10 +1682,10 @@
                 {
                   "key": "configure",
                   "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
                   "options": [
                     {
-                      "name": "sync",
+                      "name": "refresh",
                       "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
                       "kind": "presence"
                     },
@@ -1701,7 +1701,7 @@
                     },
                     {
                       "name": "yes",
-                      "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+                      "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
                       "kind": "presence",
                       "shortName": "y"
                     },
@@ -1915,10 +1915,10 @@
                 {
                   "key": "configure",
                   "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --sync --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+                  "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example-json configure --refresh --yes\n\nInteractive setup (per target):\n  full-example-json configure\n\nUpgrade:\n  brew upgrade full-example-json\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example-json configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example-json\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
                   "options": [
                     {
-                      "name": "sync",
+                      "name": "refresh",
                       "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
                       "kind": "presence"
                     },
@@ -1934,7 +1934,7 @@
                     },
                     {
                       "name": "yes",
-                      "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+                      "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
                       "kind": "presence",
                       "shortName": "y"
                     },

package/examples/full-example-json/docs/cli.md

@@ -46,7 +46,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -74,10 +74,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -259,7 +259,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -287,10 +287,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -500,7 +500,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -528,10 +528,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -723,7 +723,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -751,10 +751,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -936,7 +936,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -964,10 +964,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -1160,7 +1160,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -1188,10 +1188,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -1373,7 +1373,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -1401,10 +1401,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -1586,7 +1586,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -1614,10 +1614,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -1799,7 +1799,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example-json configure --sync --yes
+>   full-example-json configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example-json configure
@@ -1827,10 +1827,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 

package/examples/full-example-json/docs/mcp.md

@@ -8,12 +8,12 @@ full-example-json exposes an MCP server with features similar to the CLI.
 
 ### `.agents` auto-install
 
-When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the https://dotagentsprotocol.com.
+When `mcpServer.enabled` is set, `configure --refresh` merges this server into `~/.agents/mcp.json` per the https://dotagentsprotocol.com.
 
 Install the CLI first so `full-example-json` is on your PATH (e.g. `brew install full-example-json`).
 
 ```bash
-full-example-json configure --sync --yes
+full-example-json configure --refresh --yes
 ```
 
 Writes or updates `~/.agents/mcp.json` with a `mcpServers` entry for this app.

package/examples/full-example-json/docs/skill.md

@@ -43,7 +43,7 @@ For full detail, open `reference.md` in this skill directory (same as `full-exam
 
 Install follows the https://dotagentsprotocol.com:
 
-- Auto-install: `full-example-json configure --sync --yes` when `skill.enabled` → `~/.agents/skills/full-example-json/`
+- Auto-install: `full-example-json configure --refresh --yes` when `skill.enabled` → `~/.agents/skills/full-example-json/`
 - Cursor and most coding agents read `~/.agents/skills/` natively
 
 **Claude Code (manual):** symlink or copy into Claude's skill directory:

package/examples/full-example-json/justfile

@@ -77,16 +77,16 @@ http:
 install: install-local
 
 # Refresh skills and MCP without reinstalling the formula
-sync-artifacts:
-    just run configure --sync --yes
+refresh-artifacts:
+    just run configure --refresh --yes
 
 # Dev install: build, stage dev formula, brew install, restore release formula
 install-local: build
-    @brew untap {{tap}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
     bun scripts/dev-formula.ts install
-    brew install --formula {{tap}}/{{cli_key}}
+    brew install --force --formula {{tap}}/{{cli_key}}
     bun scripts/dev-formula.ts reset
     @echo ""
     @echo "Next: {{cli_key}} configure"
@@ -133,10 +133,10 @@ release *ARGS:
 
 # Install release formula from tap and run formula test
 test-release:
-    brew untap {{tap}} 2>/dev/null || true
+    NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
     brew install --formula {{tap}}/{{cli_key}}
     brew test {{cli_key}}
 
@@ -157,15 +157,15 @@ uninstall-config:
 
 # Remove formula and untap
 uninstall-formula:
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
-    @brew untap {{tap}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
+    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
 
 # Remove release formula (does not untap)
 uninstall-release:
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
 
 # Remove release formula and untap
 uninstall-release-tap:
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @brew untap {{tap}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true

package/examples/full-example-json/scripts/formula-shared.ts

@@ -20,7 +20,7 @@ export const formulaInstallRuby = `def install
   end`;
 
 export const formulaPostInstallRuby = `def post_install
-    system bin/"${key}", "configure", "--sync", "--yes"
+    system bin/"${key}", "configure", "--refresh", "--yes"
   end`;
 
 export const formulaUninstallRuby = `def uninstall

package/index.d.ts

@@ -535,21 +535,37 @@ export interface CliCompletionConfig {
 }
 /** Opt-in agent skill install to `~/.agents/skills/<key>/` (default: disabled). */
 export interface CliSkillConfig {
-	/** When `true`, install and sync the agent skill via `configure --sync`. Default false when omitted. */
+	/** When `true`, install and refresh the agent skill via `configure --refresh`. Default false when omitted. */
 	enabled?: boolean;
 }
+/** Context for {@link CliConfigureConfig} lifecycle hooks. */
+export interface ConfigureHookContext {
+	program: CliProgram;
+	/** When true, the configure run is `--dry` (hook should not write files). */
+	dry: boolean;
+	paths: {
+		agentsSkillDir: string;
+		agentsMcpPath: string;
+		mcpName: string;
+		skillDirName: string;
+	};
+}
 /** @experimental */
 export interface CliConfigureConfig {
 	/** When `false`, hide/disable `configure` (default: enabled). */
 	enabled?: boolean;
-	/** Per-artifact gates for configure sync and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
+	/** Per-artifact gates for configure refresh and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
 	targets?: CliConfigureTargets;
+	/** Runs after framework artifacts are installed/refreshed (`configure --refresh`). */
+	afterRefresh?: (ctx: ConfigureHookContext) => void | Promise<void>;
+	/** Runs before framework artifacts are removed (`configure --remove-all`). */
+	beforeRemoveAll?: (ctx: ConfigureHookContext) => void | Promise<void>;
 }
 /** Boolean or structured gate for one install artifact. */
 export type InstallTargetSpec = boolean | {
 	/** When false, artifact is never installed (even with scoped CLI flags). Default true. */
 	enabled?: boolean;
-	/** When true, included in `configure --sync`. Default varies by key. */
+	/** When true, included in `configure --refresh`. Default varies by key. */
 	includedInAll?: boolean;
 };
 export interface ResolvedInstallTarget {
@@ -560,7 +576,7 @@ export interface ResolvedInstallTarget {
 export interface CliConfigureTargets {
 	/** App binary status only (Homebrew PATH); no self-install. */
 	app?: InstallTargetSpec;
-	/** App config: interactive wizard step in `configure`. Default not in sync. */
+	/** App config: interactive wizard step in `configure`. Default not in refresh. */
 	configure?: InstallTargetSpec;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.2.2",
+  "version": "6.3.0",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {