argsbarg 6.2.0 → 6.3.0

package/src/builtins/configure.ts

@@ -12,7 +12,7 @@ import { configureConfigSubcommands } from "./config.ts";
 import {
   configureCommandDescription,
   configureCommandNotes,
-  configureSyncOptionDescription,
+  configureRefreshOptionDescription,
 } from "./configure-copy.ts";
 
 /** Hidden fallback leaf for bare `configure` (interactive / flag modes). */
@@ -23,8 +23,8 @@ export function configureBuiltinOptions(root: CliProgram): CliOption[] {
   const caps = resolveCapabilities(root);
   const opts: CliOption[] = [
     {
-      name: "sync",
-      description: configureSyncOptionDescription(root, caps),
+      name: "refresh",
+      description: configureRefreshOptionDescription(root, caps),
       kind: CliOptionKind.Presence,
     },
     {
@@ -50,7 +50,7 @@ export function configureBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "yes",
-      description: "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+      description: "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
       kind: CliOptionKind.Presence,
       shortName: "y",
     },

package/src/configure/configure.test.ts

@@ -55,12 +55,12 @@ afterEach(() => {
 /** Tests for configure opts. */
 describe("configure opts", () => {
   test("validate rejects multiple modes", () => {
-    const opts = parseConfigureOpts({ sync: "1", status: "1" });
+    const opts = parseConfigureOpts({ refresh: "1", status: "1" });
     expect(validateConfigureOpts(opts)).toContain("only one");
   });
 
-  test("sync requires --yes", () => {
-    const opts = parseConfigureOpts({ sync: "1" });
+  test("refresh requires --yes", () => {
+    const opts = parseConfigureOpts({ refresh: "1" });
     expect(validateConfigureOpts(opts)).toContain("--yes");
   });
 
@@ -92,12 +92,12 @@ describe("configure mutation summary", () => {
     expect(msg).toBe("Installed 1 artifact.");
   });
 
-  test("sync mode uses synced verb and artifact count", () => {
+  test("refresh mode uses refreshed verb and artifact count", () => {
     const msg = formatConfigureMutationSummary(
       { paths: ["a", "b", "c"], installed: 3, removed: 0, configured: 0 },
-      { sync: true },
+      { refresh: true },
     );
-    expect(msg).toBe("Synced 3 artifacts.");
+    expect(msg).toBe("Refreshed 3 artifacts.");
   });
 
   test("remove-all uses removed verb", () => {
@@ -147,8 +147,8 @@ describe("detect installed", () => {
   });
 });
 
-/** Tests for sync plan. */
-describe("sync plan", () => {
+/** Tests for refresh plan. */
+describe("refresh plan", () => {
   test("buildUpdatePlan greenfield includes skill when enabled", () => {
     const paths = resolveInstallPaths(fixture);
     const plan = buildUpdatePlan(fixture, paths, parseInstallOpts({ reinstall: "1", yes: "1" }));
@@ -229,19 +229,92 @@ describe("app config wizard", () => {
   });
 });
 
-describe("configure --sync bootstrap", () => {
+describe("configure --refresh bootstrap", () => {
   test("creates config.json for apps without appConfig", async () => {
     const program: CliProgram = {
-      key: "syncboot",
+      key: "refreshboot",
       version: "0.0.0",
-      description: "Sync bootstrap test.",
+      description: "Refresh bootstrap test.",
       skill: { enabled: true },
       handler: () => {},
       configure: { enabled: true },
     };
     expect(appConfigFileExists(program)).toBe(false);
-    const result = await new Cli(program).invoke(["configure", "--sync", "--yes"]);
+    const result = await new Cli(program).invoke(["configure", "--refresh", "--yes"]);
     expect(result.exitCode).toBe(0);
     expect(appConfigFileExists(program)).toBe(true);
   });
 });
+
+describe("configure lifecycle hooks", () => {
+  test("afterRefresh runs after --refresh plan", async () => {
+    const calls: string[] = [];
+    const program: CliProgram = {
+      ...fixture,
+      key: "hookrefresh",
+      configure: {
+        afterRefresh: async (ctx) => {
+          calls.push(`after:${ctx.paths.mcpName}:dry=${ctx.dry}`);
+        },
+      },
+    };
+    const result = await new Cli(program).invoke(["configure", "--refresh", "--yes"]);
+    expect(result.exitCode).toBe(0);
+    expect(calls).toEqual([`after:hookrefresh:dry=false`]);
+  });
+
+  test("beforeRemoveAll runs before --remove-all plan", async () => {
+    const paths = resolveInstallPaths({ ...fixture, key: "hookremove" });
+    mkdirSync(paths.agentsSkillDir, { recursive: true });
+    writeFileSync(join(paths.agentsSkillDir, "SKILL.md"), "# test\n", "utf8");
+
+    const calls: string[] = [];
+    const program: CliProgram = {
+      ...fixture,
+      key: "hookremove",
+      configure: {
+        beforeRemoveAll: async (ctx) => {
+          calls.push(`before:${ctx.paths.skillDirName}`);
+          expect(existsSync(ctx.paths.agentsSkillDir)).toBe(true);
+        },
+      },
+    };
+    const result = await new Cli(program).invoke(["configure", "--remove-all", "--yes"]);
+    expect(result.exitCode).toBe(0);
+    expect(calls).toEqual(["before:hookremove"]);
+    expect(existsSync(paths.agentsSkillDir)).toBe(false);
+  });
+
+  test("hooks receive dry from --dry", async () => {
+    const calls: string[] = [];
+    const program: CliProgram = {
+      ...fixture,
+      key: "hookdry",
+      configure: {
+        afterRefresh: (ctx) => {
+          calls.push(`dry=${ctx.dry}`);
+        },
+      },
+    };
+    const result = await new Cli(program).invoke(["configure", "--refresh", "--yes", "--dry"]);
+    expect(result.exitCode).toBe(0);
+    expect(calls).toEqual(["dry=true"]);
+  });
+
+  test("beforeRemoveAll is not called for --remove-config", async () => {
+    let called = false;
+    const program: CliProgram = {
+      ...fixture,
+      key: "hookcfg",
+      appConfig: { entries: { token: { description: "Token." } } },
+      configure: {
+        beforeRemoveAll: () => {
+          called = true;
+        },
+      },
+    };
+    const result = await new Cli(program).invoke(["configure", "--remove-config", "--yes"]);
+    expect(result.exitCode).toBe(0);
+    expect(called).toBe(false);
+  });
+});

package/src/configure/index.ts

@@ -4,10 +4,10 @@ Interactive and automated `configure` command orchestration (agent artifacts and
 
 import { displayAppConfigPath, runConfigure } from "../config/bootstrap.ts";
 import { ensureAppConfigFile } from "../config/file.ts";
-import type { CliProgram } from "../core/types.ts";
+import type { CliProgram, ConfigureHookContext } from "../core/types.ts";
 import { resolveCapabilities } from "../runtime/capabilities.ts";
 import { cliSkillInstall, isAgentSkillActionKind } from "../skill/install.ts";
-import { displayInstallPath, resolveInstallPaths } from "./artifacts/paths.ts";
+import { displayInstallPath, type InstallPaths, resolveInstallPaths } from "./artifacts/paths.ts";
 import { buildInstallPlan, buildUpdatePlan } from "./artifacts/plan.ts";
 import {
   installErr,
@@ -38,7 +38,7 @@ export function appConfigHasEntries(program: CliProgram): boolean {
 
 /** Parsed flags for the top-level `configure` built-in. */
 export interface ConfigureOpts {
-  sync?: boolean;
+  refresh?: boolean;
   removeAll?: boolean;
   removeConfig?: boolean;
   status?: boolean;
@@ -51,7 +51,7 @@ export interface ConfigureOpts {
 export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
   const flag = (name: string) => raw[name] === "1";
   return {
-    sync: flag("sync"),
+    refresh: flag("refresh"),
     removeAll: flag("remove-all"),
     removeConfig: flag("remove-config"),
     status: flag("status"),
@@ -63,15 +63,15 @@ export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
 
 /** Returns an error message when configure flags are inconsistent; otherwise null. */
 export function validateConfigureOpts(opts: ConfigureOpts): string | null {
-  const flags = [opts.sync, opts.removeAll, opts.removeConfig, opts.status].filter(Boolean);
+  const flags = [opts.refresh, opts.removeAll, opts.removeConfig, opts.status].filter(Boolean);
   if (flags.length > 1) {
-    return "Use only one of --sync, --remove-all, --remove-config, or --status.";
+    return "Use only one of --refresh, --remove-all, --remove-config, or --status.";
   }
   if (opts.json) {
     opts.yes = true;
   }
-  if ((opts.sync || opts.removeAll || opts.removeConfig) && !opts.yes) {
-    return "--yes is required with --sync, --remove-all, or --remove-config.";
+  if ((opts.refresh || opts.removeAll || opts.removeConfig) && !opts.yes) {
+    return "--yes is required with --refresh, --remove-all, or --remove-config.";
   }
   return null;
 }
@@ -81,7 +81,7 @@ function configureToInstallOpts(opts: ConfigureOpts): InstallOpts {
   if (opts.status) {
     return { status: true, yes: opts.yes, dry: opts.dry, json: opts.json };
   }
-  if (opts.sync) {
+  if (opts.refresh) {
     return { reinstall: true, yes: true, dry: opts.dry, json: opts.json };
   }
   if (opts.removeAll) {
@@ -141,10 +141,10 @@ export function formatConfigureMutationSummary(summary: ConfigureMutationSummary
     return n === 1 ? "Removed 1 artifact." : `Removed ${n} artifacts.`;
   }
 
-  if (opts.sync) {
+  if (opts.refresh) {
     const n = summary.installed;
     if (n === 0) return null;
-    return n === 1 ? "Synced 1 artifact." : `Synced ${n} artifacts.`;
+    return n === 1 ? "Refreshed 1 artifact." : `Refreshed ${n} artifacts.`;
   }
 
   const parts: string[] = [];
@@ -184,6 +184,29 @@ function runPlanAction(
   return action.run();
 }
 
+function configureHookContext(root: CliProgram, paths: InstallPaths, dry: boolean): ConfigureHookContext {
+  return {
+    program: root,
+    dry,
+    paths: {
+      agentsSkillDir: paths.agentsSkillDir,
+      agentsMcpPath: paths.agentsMcpPath,
+      mcpName: paths.mcpName,
+      skillDirName: paths.skillDirName,
+    },
+  };
+}
+
+async function runConfigureLifecycleHook(
+  hook: ((ctx: ConfigureHookContext) => void | Promise<void>) | undefined,
+  root: CliProgram,
+  paths: InstallPaths,
+  dry: boolean,
+): Promise<void> {
+  if (!hook) return;
+  await hook(configureHookContext(root, paths, dry));
+}
+
 /** Runs install or uninstall actions and collects changed paths. */
 function executePlan(
   root: CliProgram,
@@ -253,7 +276,7 @@ function actionsForTarget(
 /** Walks enabled targets with per-target prompts (TTY required). */
 async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): Promise<ConfigureMutationSummary> {
   if (!process.stdin.isTTY) {
-    throw new Error("Interactive configure requires a TTY. Use flags such as --sync --yes.");
+    throw new Error("Interactive configure requires a TTY. Use flags such as --refresh --yes.");
   }
 
   writeInteractiveInstallIntro(root);
@@ -319,6 +342,10 @@ async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Pro
 
   const summary = emptyMutationSummary();
 
+  if (opts.removeAll) {
+    await runConfigureLifecycleHook(root.configure?.beforeRemoveAll, root, paths, !!installOpts.dry);
+  }
+
   if (installOpts.reinstall && !installOpts.uninstall) {
     const bootstrapped = ensureAppConfigFile(root, !!installOpts.dry);
     if (bootstrapped) {
@@ -345,6 +372,11 @@ async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Pro
   }
 
   mergeMutationSummary(summary, executePlan(root, actions, installOpts, true));
+
+  if (opts.refresh) {
+    await runConfigureLifecycleHook(root.configure?.afterRefresh, root, paths, !!installOpts.dry);
+  }
+
   return summary;
 }
 
@@ -357,7 +389,7 @@ export async function cliConfigure(root: CliProgram, rawOpts: Record<string, str
     process.exit(1);
   }
 
-  const isInteractive = !opts.sync && !opts.removeAll && !opts.removeConfig && !opts.status;
+  const isInteractive = !opts.refresh && !opts.removeAll && !opts.removeConfig && !opts.status;
 
   let summary = emptyMutationSummary();
   try {

package/src/core/types.ts

@@ -406,16 +406,33 @@ 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. */
@@ -424,7 +441,7 @@ export type InstallTargetSpec =
   | {
       /** 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;
     };
 
@@ -437,7 +454,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/src/docs/docs.test.ts

@@ -153,7 +153,7 @@ test("docs mcp when MCP enabled", async () => {
   expect(result.stdout).toContain("MCP server (myapp)");
   expect(result.stdout).toContain("myapp mcp");
   expect(result.stdout).toContain("claude_desktop_config.json");
-  expect(result.stdout).toContain("configure --sync --yes");
+  expect(result.stdout).toContain("configure --refresh --yes");
 });
 
 test("docs rejects unknown subcommand", async () => {
@@ -304,7 +304,7 @@ test("generateMcpGuide includes schema URI and .agents install", () => {
   expect(guide).toContain("claude_desktop_config.json");
   expect(guide).toContain("## Installation");
   expect(guide).toContain("## Running directly");
-  expect(guide).toContain("configure --sync");
+  expect(guide).toContain("configure --refresh");
   expect(guide).toContain("dotagentsprotocol.com");
   expect(guide).not.toContain("OpenAI Codex");
 });

package/src/docs/mcp-guide.ts

@@ -81,7 +81,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
     "### `.agents` auto-install",
     "",
-    "When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/).",
+    "When `mcpServer.enabled` is set, `configure --refresh` merges this server into `~/.agents/mcp.json` per the https://dotagentsprotocol.com.",
     "",
   ];
 
@@ -93,7 +93,7 @@ export function generateMcpGuide(root: CliProgram): string {
 
   lines.push(
     "```bash",
-    `${root.key} configure --sync --yes`,
+    `${root.key} configure --refresh --yes`,
     "```",
     "",
     "Writes or updates `~/.agents/mcp.json` with a `mcpServers` entry for this app.",

package/src/index.ts

@@ -53,6 +53,7 @@ export type {
   CliRespondBody,
   CliRespondOptions,
   CliSkillConfig,
+  ConfigureHookContext,
   ErrorHookContext,
   InstallTargetSpec,
   InvokeFailureKind,

package/src/skill/generate.ts

@@ -152,9 +152,9 @@ function buildSkillMd(root: CliProgram, dirName: string): string {
     "",
     "## Install location",
     "",
-    "Install follows the [.agents protocol](https://dotagentsprotocol.com/):",
+    "Install follows the https://dotagentsprotocol.com:",
     "",
-    `- Auto-install: \`${root.key} configure --sync --yes\` when \`skill.enabled\` → \`~/.agents/skills/${dirName}/\``,
+    `- Auto-install: \`${root.key} configure --refresh --yes\` when \`skill.enabled\` → \`~/.agents/skills/${dirName}/\``,
     `- Cursor and most coding agents read \`~/.agents/skills/\` natively`,
     "",
     "**Claude Code (manual):** symlink or copy into Claude's skill directory:",