argsbarg 4.0.4 → 4.1.1

package/src/config.integration.test.ts

@@ -3,16 +3,17 @@ App config bootstrap and MCP config enforcement regressions.
 */
 
 import { expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { bootstrapAppConfig } from "./config/bootstrap.ts";
+import { resolveAppConfigPath } from "./config/file.ts";
 import { mcpRequest, testProgram } from "./test-fixtures.ts";
 
 test("bootstrapAppConfig prefers host env over config file", () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-env-"));
-  const configFile = join(dir, "config");
-  writeFileSync(configFile, `${JSON.stringify({ foo: "fromfile", bar: "bar" })}\n`, "utf8");
+  const prevHome = process.env.HOME;
+  process.env.HOME = dir;
   process.env.FOO = "original";
   try {
     const p = testProgram({
@@ -20,7 +21,6 @@ test("bootstrapAppConfig prefers host env over config file", () => {
       version: "0",
       description: "",
       appConfig: {
-        path: configFile,
         entries: {
           foo: { description: "x", env: "FOO" },
           bar: { description: "y", env: "BAR" },
@@ -28,10 +28,15 @@ test("bootstrapAppConfig prefers host env over config file", () => {
       },
       handler: () => {},
     });
+    const configFile = resolveAppConfigPath(p);
+    mkdirSync(dirname(configFile), { recursive: true });
+    writeFileSync(configFile, `${JSON.stringify({ foo: "fromfile", bar: "bar" })}\n`, "utf8");
     bootstrapAppConfig(p, { validateFile: true });
     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;
     delete process.env.FOO;
     delete process.env.BAR;
     rmSync(dir, { recursive: true, force: true });
@@ -74,7 +79,8 @@ test("MCP program.appConfig succeeds when env present", async () => {
 
 test("MCP config file loads and exports vars for tool handlers", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-mcp-"));
-  const configFile = join(dir, "config");
+  const configFile = join(dir, ".local", "lib", "mcp_test", "config");
+  mkdirSync(dirname(configFile), { recursive: true });
   writeFileSync(
     configFile,
     `${JSON.stringify({ argsTestSecret: "file-value" }, null, 2)}\n`,
@@ -91,17 +97,19 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
     ],
     {
       script: "examples/mcp-test.ts",
-      env: { ARGS_TEST_CONFIG_FILE: configFile, ARGS_TEST_SECRET: "present" },
+      env: { HOME: dir, ARGS_TEST_SECRET: "present" },
     },
   );
   const res = responses.get(15) as { result: { isError: boolean; content: { text: string }[] } };
   expect(res.result.isError).toBe(false);
   expect(res.result.content[0]?.text.trim()).toBe("present");
+  rmSync(dir, { recursive: true, force: true });
 });
 
 test("Cli.run docs api skips required appConfig exit", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-docs-skip-"));
-  const configFile = join(dir, "config");
+  const configFile = join(dir, ".local", "lib", "docs_skip_test", "config");
+  mkdirSync(dirname(configFile), { recursive: true });
   writeFileSync(configFile, "{}\n");
   const entry = join(import.meta.dir, "index.ts");
   const mainPath = join(dir, "run-docs.ts");
@@ -114,7 +122,6 @@ const program = {
   description: "test",
   docs: { enabled: true, topics: { readme: { text: "# readme\\n" } } },
   appConfig: {
-    path: ${JSON.stringify(configFile)},
     entries: { token: { description: "Token.", env: "DOCS_SKIP_RUN_TOKEN" } },
   },
   handler: () => {},
@@ -122,7 +129,7 @@ const program = {
 await new Cli(program).run(process.argv.slice(2));
 `,
   );
-  const env = { ...process.env };
+  const env = { ...process.env, HOME: dir } as Record<string, string | undefined>;
   delete env.DOCS_SKIP_RUN_TOKEN;
   try {
     const proc = Bun.spawn(["bun", "run", mainPath, "docs", "api"], {

package/src/docs/api-guide.test.ts

@@ -71,21 +71,20 @@ test("generateApiGuide resolves program key in install notes", () => {
   };
   const md = generateApiGuide(fixture);
   expect(md).not.toContain("{argsbarg:program}");
-  expect(md).toContain("myapp install --all --yes");
+  expect(md).toContain("brew install");
   expect(md).not.toContain("Upgrade to latest release");
 });
 
-test("generateApiGuide includes upgrade section when updateGetLatest is set", () => {
+test("generateApiGuide mentions Homebrew upgrade", () => {
   const fixture: CliProgram = {
     key: "myapp",
     version: "1.0.0",
     description: "Demo app.",
-    install: { updateGetLatest: async () => ({ path: process.execPath }) },
     commands: [{ key: "run", description: "Run.", handler: () => {} }],
   };
   const md = generateApiGuide(fixture);
-  expect(md).toContain("Upgrade to latest release");
-  expect(md).toContain("myapp install --update");
+  expect(md).toContain("brew upgrade");
+  expect(md).not.toContain("install --update");
 });
 
 test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {

package/src/docs/docs.test.ts

@@ -217,7 +217,8 @@ test("generateMcpGuide includes schema URI and install targets", () => {
   expect(guide).toContain("claude_desktop_config.json");
   expect(guide).toContain("## Installation");
   expect(guide).toContain("## Running directly");
-  expect(guide).toContain("install --bin");
+  expect(guide).toContain("install --mcp");
+  expect(guide).toContain("brew install myapp");
   expect(guide).toContain("OpenAI Codex");
   expect(guide).toContain("ChatGPT");
 });

package/src/docs/mcp-guide.ts

@@ -111,7 +111,7 @@ export function generateMcpGuide(root: CliProgram): string {
 
   if (caps.install) {
     lines.push(
-      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`${root.key} install --bin --yes\` or \`install --all --yes\`). Host configs reference the binary by name.`,
+      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`brew install ${root.key}\`). Host configs reference the app by name.`,
       "",
     );
   } else {
@@ -167,13 +167,12 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
   );
 
-  if (mcp.shellEnv) {
-    lines.push("## Environment", "");
-    lines.push(
-      "- **`shellEnv`** — captures login-shell environment at MCP startup (PATH, toolchain shims, exports).",
-    );
-    lines.push("");
-  }
+  lines.push(
+    "## Environment",
+    "",
+    "- **`shellEnv`** — on by default; captures login-shell environment at MCP startup (PATH, toolchain shims, exports). Opt out with `shellEnv: false`.",
+    "",
+  );
 
   if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {
     lines.push("## Configuration", "");

package/src/hidden-mcpb.test.ts

@@ -19,7 +19,7 @@ const hiddenFixture: CliProgram = {
   key: "myapp",
   version: "1.0.0",
   description: "Hidden demo.",
-  mcpServer: { enabled: true },
+  mcpServer: { enabled: true, mcpd: true, claudePlugin: true },
   commands: [
     {
       key: "public",
@@ -187,4 +187,44 @@ describe("mcp bundle", () => {
       rmSync(work, { recursive: true, force: true });
     }
   });
+
+  test("runMcpBundle with claudePlugin only prints plugin path", () => {
+    const work = mkdtempSync(join(tmpdir(), "mcpb-run-"));
+    const stdout: string[] = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdout.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      return true;
+    }) as typeof process.stdout.write;
+    const fixture: CliProgram = {
+      ...hiddenFixture,
+      mcpServer: { enabled: true, claudePlugin: true },
+    };
+    try {
+      const dist = join(work, "dist");
+      mkdirSync(dist, { recursive: true });
+      writeFileSync(join(dist, "myapp"), "#!/bin/sh\n", { mode: 0o755 });
+      const prevCwd = process.cwd();
+      process.chdir(work);
+      try {
+        runMcpBundle(fixture);
+      } finally {
+        process.chdir(prevCwd);
+      }
+      const lines = stdout.join("").trim().split("\n");
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain("claude-plugin");
+    } finally {
+      process.stdout.write = orig;
+      rmSync(work, { recursive: true, force: true });
+    }
+  });
+
+  test("runMcpBundle errors when no bundle flags enabled", () => {
+    const fixture: CliProgram = {
+      ...hiddenFixture,
+      mcpServer: { enabled: true },
+    };
+    expect(() => runMcpBundle(fixture)).toThrow(/mcpd/);
+  });
 });

package/src/index.ts

@@ -9,6 +9,7 @@ module layout.
 
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./cli.ts";
 export { cliErrWithHelp } from "./cli-errors.ts";
+export { displayAppConfigPath, resolveAppConfigPath } from "./config/file.ts";
 export type { CliLeafInputs } from "./context.ts";
 export { CliContext } from "./context.ts";
 export {
@@ -26,23 +27,18 @@ export {
   shouldRunHeadlessWithYes,
   wantsExplicitJson,
 } from "./headless.ts";
-export type { GhReleaseUpdateConfig, GhVersionCheckConfig } from "./install/gh-release-update.ts";
-export {
-  createGhFetchLatest,
-  createGhVersionCheck,
-  ghReleaseUpdateGetLatest,
-  isAlreadyCurrent,
-  parseReleaseTag,
-} from "./install/gh-release-update.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export type {
   CliAppConfig,
   CliAppConfigEntry,
+  CliAppConfigResolveContext,
+  CliAppConfigResolveFn,
   CliDocsConfig,
   CliDocsTopic,
   CliHandler,
   CliInstallConfig,
+  CliInstallTargets,
   CliInvocation,
   CliMcpBundleConfig,
   CliMcpResource,
@@ -51,8 +47,9 @@ export type {
   CliOption,
   CliPositional,
   CliProgram,
-  CliUpdateArtifact,
-  CliUpdateGetLatest,
+  InstallAgentIntegration,
+  InstallTargetSpec,
+  ResolvedInstallTarget,
 } from "./types.ts";
 export {
   CliFallbackMode,

package/src/install/binary-placement.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CliProgram } from "../types.ts";
+import {
+  isAppInstalled,
+  isExternallyManagedBinary,
+  resolvePathCommand,
+} from "./binary-placement.ts";
+
+const program: CliProgram = {
+  key: "placementapp",
+  version: "1.0.0",
+  description: "x",
+  handler: () => {},
+};
+
+let tmp: string;
+let prevPath: string | undefined;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "argsbarg-placement-"));
+  prevPath = process.env.PATH;
+});
+
+afterEach(() => {
+  if (prevPath === undefined) delete process.env.PATH;
+  else process.env.PATH = prevPath;
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("isExternallyManagedBinary", () => {
+  test("false when command is not on PATH", () => {
+    process.env.PATH = tmp;
+    expect(isExternallyManagedBinary("placementapp-not-on-path")).toBe(false);
+  });
+
+  test("true when PATH resolves to execPath", () => {
+    const bin = join(tmp, "placementapp");
+    writeFileSync(bin, "#!/bin/sh\n", "utf8");
+    chmodSync(bin, 0o755);
+    process.env.PATH = tmp;
+    expect(isExternallyManagedBinary("placementapp", bin)).toBe(true);
+  });
+
+  test("true when PATH entry is a symlink to execPath", () => {
+    const bin = join(tmp, "placementapp");
+    const target = join(tmp, "real-binary");
+    writeFileSync(target, "fake", "utf8");
+    symlinkSync(target, bin);
+    process.env.PATH = tmp;
+    expect(isExternallyManagedBinary("placementapp", target)).toBe(true);
+  });
+
+  test("false when PATH points at a different binary", () => {
+    const bin = join(tmp, "placementapp");
+    const other = join(tmp, "other");
+    writeFileSync(bin, "a", "utf8");
+    writeFileSync(other, "b", "utf8");
+    process.env.PATH = tmp;
+    expect(isExternallyManagedBinary("placementapp", other)).toBe(false);
+  });
+});
+
+describe("isAppInstalled", () => {
+  test("true when externally managed", () => {
+    const bin = join(tmp, program.key);
+    const prevExec = process.execPath;
+    writeFileSync(bin, "x", "utf8");
+    chmodSync(bin, 0o755);
+    process.env.PATH = tmp;
+    process.execPath = bin;
+    try {
+      expect(isAppInstalled(program)).toBe(true);
+    } finally {
+      process.execPath = prevExec;
+    }
+  });
+
+  test("false when not on PATH and no local copy", () => {
+    const home = mkdtempSync(join(tmpdir(), "argsbarg-placement-home-"));
+    const prevHome = process.env.HOME;
+    process.env.HOME = home;
+    process.env.PATH = tmp;
+    try {
+      expect(isAppInstalled(program)).toBe(false);
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("resolvePathCommand", () => {
+  test("returns undefined when missing", () => {
+    process.env.PATH = tmp;
+    expect(resolvePathCommand("missing-cmd")).toBeUndefined();
+  });
+});

package/src/install/binary-placement.ts

@@ -0,0 +1,47 @@
+import { accessSync, constants, realpathSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import type { CliProgram } from "../types.ts";
+
+/** Resolves a command name on PATH to its real path, if present. */
+export function resolvePathCommand(key: string): string | undefined {
+  const pathEnv = process.env.PATH ?? "";
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, key);
+    try {
+      accessSync(candidate, constants.F_OK);
+      return realpathSync(candidate);
+    } catch {}
+  }
+
+  const found = Bun.which(key);
+  if (found === null) return undefined;
+  try {
+    return realpathSync(found);
+  } catch {
+    return found;
+  }
+}
+
+function realpathOrSelf(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/** True when PATH resolves to the running executable (e.g. Homebrew Cellar). */
+export function isExternallyManagedBinary(
+  key: string,
+  execPath: string = process.execPath,
+): boolean {
+  const resolved = resolvePathCommand(key);
+  if (!resolved) return false;
+  return resolved === realpathOrSelf(execPath);
+}
+
+/** True when the app binary is available on PATH (e.g. Homebrew). */
+export function isAppInstalled(program: CliProgram): boolean {
+  return isExternallyManagedBinary(program.key);
+}

package/src/install/detect-installed.ts

@@ -1,97 +1,2 @@
-import { existsSync, readFileSync } from "node:fs";
-import { codexMcpHasServer } from "./mcp-codex.ts";
-import { detectOpenCodeMcpConfigPath } from "./mcp-opencode.ts";
-import { type InstallPaths, userHome } from "./paths.ts";
-
-export interface InstalledArtifacts {
-  binary: boolean;
-  bashCompletion: boolean;
-  zshCompletion: boolean;
-  fishCompletion: boolean;
-  cursorSkill: boolean;
-  claudeSkill: boolean;
-  cursorMcp: boolean;
-  claudeMcp: boolean;
-  claudeDesktopMcp: boolean;
-  opencodeMcp: boolean;
-  codexMcp: boolean;
-  chatGptMcp: boolean;
-  bashRcPath: boolean;
-  zshRcFpath: boolean;
-}
-
-function mcpConfigHasServer(path: string, name: string): boolean {
-  if (!existsSync(path)) return false;
-  try {
-    const data = JSON.parse(readFileSync(path, "utf8")) as { mcpServers?: Record<string, unknown> };
-    return data.mcpServers?.[name] !== undefined;
-  } catch {
-    return false;
-  }
-}
-
-/** Detects which install artifacts are currently present. */
-export function detectInstalledArtifacts(paths: InstallPaths): InstalledArtifacts {
-  return {
-    binary: existsSync(paths.binaryPath),
-    bashCompletion: existsSync(paths.bashCompletion),
-    zshCompletion: existsSync(paths.zshCompletion),
-    fishCompletion: existsSync(paths.fishCompletion),
-    cursorSkill: existsSync(paths.cursorSkillDir),
-    claudeSkill: existsSync(paths.claudeSkillDir),
-    cursorMcp: mcpConfigHasServer(paths.cursorMcpPath, paths.mcpName),
-    claudeMcp: mcpConfigHasServer(paths.claudeMcpPath, paths.mcpName),
-    claudeDesktopMcp: mcpConfigHasServer(paths.claudeDesktopMcpPath, paths.mcpName),
-    opencodeMcp: detectOpenCodeMcpConfigPath(userHome(), paths.mcpName) !== undefined,
-    codexMcp: codexMcpHasServer(userHome(), paths.mcpName),
-    chatGptMcp: mcpConfigHasServer(paths.chatGptMcpPath, paths.mcpName),
-    bashRcPath: false,
-    zshRcFpath: false,
-  };
-}
-
-export interface InstallStatus {
-  binary?: string;
-  bashCompletion?: string;
-  zshCompletion?: string;
-  fishCompletion?: string;
-  cursorSkill?: string;
-  claudeSkill?: string;
-  cursorMcp?: string;
-  claudeMcp?: string;
-  claudeDesktopMcp?: string;
-  opencodeMcp?: string;
-  codexMcp?: string;
-  chatGptMcp?: string;
-}
-
-/** Builds a status inventory from detected artifacts. */
-export function buildInstallStatus(
-  paths: InstallPaths,
-  detected: InstalledArtifacts,
-): InstallStatus {
-  const status: InstallStatus = {};
-  if (detected.binary) status.binary = paths.binaryPath;
-  if (detected.bashCompletion) status.bashCompletion = paths.bashCompletion;
-  if (detected.zshCompletion) status.zshCompletion = paths.zshCompletion;
-  if (detected.fishCompletion) status.fishCompletion = paths.fishCompletion;
-  if (detected.cursorSkill) status.cursorSkill = `${paths.cursorSkillDir}/`;
-  if (detected.claudeSkill) status.claudeSkill = `${paths.claudeSkillDir}/`;
-  if (detected.cursorMcp) status.cursorMcp = `${paths.cursorMcpPath} (server "${paths.mcpName}")`;
-  if (detected.claudeMcp) status.claudeMcp = `${paths.claudeMcpPath} (server "${paths.mcpName}")`;
-  if (detected.claudeDesktopMcp) {
-    status.claudeDesktopMcp = `${paths.claudeDesktopMcpPath} (server "${paths.mcpName}")`;
-  }
-  if (detected.opencodeMcp) {
-    const openCodePath =
-      detectOpenCodeMcpConfigPath(userHome(), paths.mcpName) ?? paths.opencodeMcpPath;
-    status.opencodeMcp = `${openCodePath} (server "${paths.mcpName}")`;
-  }
-  if (detected.codexMcp) {
-    status.codexMcp = `${paths.codexConfigPath} (server "${paths.mcpName}")`;
-  }
-  if (detected.chatGptMcp) {
-    status.chatGptMcp = `${paths.chatGptMcpPath} (server "${paths.mcpName}")`;
-  }
-  return status;
-}
+export { buildInstallStatus, detectInstalledArtifacts } from "./target-detect.ts";
+export type { InstalledArtifacts, InstallStatus } from "./target-types.ts";