argsbarg 6.2.2 → 6.3.1

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/parse.test.ts

@@ -1212,20 +1212,20 @@ test("cliSkillInstall writes project agent skill files", () => {
   }
 });
 
-/** CliSkillInstall global uses HOME agents skills directory. */
-test("cliSkillInstall global uses HOME agents skills directory", () => {
+/** CliSkillInstall global uses TEST_USER_HOME agents skills directory. */
+test("cliSkillInstall global uses TEST_USER_HOME agents skills directory", () => {
   const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
-  const prevHome = process.env.HOME;
-  process.env.HOME = home;
+  const prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = home;
   try {
     const files = cliSkillInstall(nestedMcpFixture, { global: true, rimraf: true });
     expect(files.some((f) => f.includes(join(home, ".agents", "skills", "nested.ts")))).toBe(true);
     expect(existsSync(join(home, ".agents", "skills", "nested.ts", "SKILL.md"))).toBe(true);
   } finally {
-    if (prevHome === undefined) {
-      delete process.env.HOME;
+    if (prevTestHome === undefined) {
+      delete process.env.TEST_USER_HOME;
     } else {
-      process.env.HOME = prevHome;
+      process.env.TEST_USER_HOME = prevTestHome;
     }
     rmSync(home, { recursive: true, force: true });
   }

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 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,
@@ -83,6 +84,7 @@ export type { EcsLogEvent, LogEnrichContext } from "./log/ecs.ts";
 export { ECS_VERSION, formatEcsLine } from "./log/ecs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+export { userHome } from "./paths/host.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./runtime/cli.ts";
 export { cliErrWithHelp } from "./runtime/cli-errors.ts";
 export { isInteractiveTty } from "./utils.ts";

package/src/paths/host.test.ts

@@ -0,0 +1,58 @@
+/*
+Tests for paths/host module behavior.
+*/
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { join } from "node:path";
+import { userHome } from "./host.ts";
+
+describe("userHome", () => {
+  let prevTestHome: string | undefined;
+
+  afterEach(() => {
+    if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+    else process.env.TEST_USER_HOME = prevTestHome;
+  });
+
+  test("uses TEST_USER_HOME when set", () => {
+    const home = mkdtempSync(join(tmpdir(), "argsbarg-test-home-"));
+    prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = home;
+    try {
+      expect(userHome()).toBe(home);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("ignores sandboxed HOME (Homebrew post_install)", () => {
+    prevTestHome = process.env.TEST_USER_HOME;
+    delete process.env.TEST_USER_HOME;
+    const prevHome = process.env.HOME;
+    process.env.HOME = "/private/tmp/sqsp-workspaces-postinstall-20260807-fake";
+    try {
+      const resolved = userHome();
+      expect(resolved).not.toBe(process.env.HOME);
+      if (process.platform === "darwin" && process.env.USER) {
+        expect(resolved).toBe(`/Users/${process.env.USER}`);
+        expect(existsSync(resolved)).toBe(true);
+      } else {
+        expect(resolved).toBe(userInfo().homedir);
+      }
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+    }
+  });
+
+  test("resolves macOS default home when TEST_USER_HOME unset", () => {
+    prevTestHome = process.env.TEST_USER_HOME;
+    delete process.env.TEST_USER_HOME;
+    if (process.platform !== "darwin" || !process.env.USER) return;
+    const expected = `/Users/${process.env.USER}`;
+    if (!existsSync(expected)) return;
+    expect(userHome()).toBe(expected);
+  });
+});

package/src/paths/host.ts

@@ -2,12 +2,21 @@
 Shared host path primitives for install, config, and skill modules.
 */
 
-import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { userInfo } from "node:os";
 import { join } from "node:path";
 
-/** Resolves the user home directory (`$HOME` when set). */
+/**
+ * Resolves the user home directory without depending on `$HOME`.
+ * This is helpful for when homebrew post-install hooks run with a temporary `$HOME`.
+ */
 export function userHome(): string {
-  return process.env.HOME ?? homedir();
+  const user = process.env.USER ?? process.env.LOGNAME;
+  return (
+    [process.env.TEST_USER_HOME, user && `/Users/${user}`, user && `/home/${user}`, process.env.USERPROFILE].find(
+      (p) => p && existsSync(p),
+    ) ?? userInfo().homedir
+  );
 }
 
 /** Expands a leading `~` or `~/` in a path using {@link userHome}. */

package/src/skill/generate.ts

@@ -154,7 +154,7 @@ function buildSkillMd(root: CliProgram, dirName: string): string {
     "",
     "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:",

package/src/test/integration/config.test.ts

@@ -13,8 +13,8 @@ import { mcpRequest, testProgram } from "../fixtures.ts";
 /** Tests that bootstrapAppConfig prefers host env over config file. */
 test("bootstrapAppConfig prefers host env over config file", () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-env-"));
-  const prevHome = process.env.HOME;
-  process.env.HOME = dir;
+  const prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = dir;
   process.env.FOO = "original";
   try {
     const p = testProgram({
@@ -36,8 +36,8 @@ test("bootstrapAppConfig prefers host env over config file", () => {
     expect(process.env.FOO).toBe("original");
     expect(process.env.BAR).toBe("bar");
   } finally {
-    if (prevHome === undefined) delete process.env.HOME;
-    else process.env.HOME = prevHome;
+    if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+    else process.env.TEST_USER_HOME = prevTestHome;
     delete process.env.FOO;
     delete process.env.BAR;
     rmSync(dir, { recursive: true, force: true });
@@ -106,7 +106,7 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
     ],
     {
       script: "src/test/mcp-integration-fixture.ts",
-      env: { HOME: dir, ARGS_TEST_SECRET: "present" },
+      env: { TEST_USER_HOME: dir, ARGS_TEST_SECRET: "present" },
     },
   );
   const res = responses.get(15) as {
@@ -148,7 +148,7 @@ const program = {
 await new Cli(program).run(process.argv.slice(2));
 `,
   );
-  const env = { ...process.env, HOME: dir } as Record<string, string | undefined>;
+  const env = { ...process.env, TEST_USER_HOME: dir } as Record<string, string | undefined>;
   delete env.DOCS_SKIP_RUN_TOKEN;
   try {
     const proc = Bun.spawn(["bun", "run", mainPath, "docs", "cli"], {