argsbarg 4.1.0 → 5.0.1

package/src/install/target-types.ts

@@ -12,8 +12,6 @@ export type InstallPlanMode =
 
 export interface InstallScope {
   all?: boolean;
-  app?: boolean;
-  completions?: boolean;
   skill?: boolean;
   mcp?: boolean;
   configure?: boolean;
@@ -29,7 +27,6 @@ export type CliInstallArtifactKey =
   | "claudeSkill"
   | "codexMcp"
   | "codexSkill"
-  | "completions"
   | "configure"
   | "cursorMcp"
   | "cursorSkill"
@@ -40,7 +37,6 @@ export type CliInstallArtifactKey =
 
 export type InstallActionKind =
   | "app"
-  | "completions"
   | "cursor-skill"
   | "claude-skill"
   | "codex-skill"
@@ -73,9 +69,6 @@ export interface UninstallAction {
 
 export interface InstalledArtifacts {
   app: boolean;
-  bashCompletion: boolean;
-  zshCompletion: boolean;
-  fishCompletion: boolean;
   cursorSkill: boolean;
   claudeSkill: boolean;
   codexSkill: boolean;
@@ -88,15 +81,10 @@ export interface InstalledArtifacts {
   codexMcp: boolean;
   openclawMcp: boolean;
   chatGptMcp: boolean;
-  bashRcPath: boolean;
-  zshRcFpath: boolean;
 }
 
 export interface InstallStatus {
   app?: string;
-  bashCompletion?: string;
-  zshCompletion?: string;
-  fishCompletion?: string;
   cursorSkill?: string;
   claudeSkill?: string;
   codexSkill?: string;
@@ -117,13 +105,9 @@ export interface DetectedSnapshot extends InstalledArtifacts {
 
 export interface InstallOpts {
   all?: boolean;
-  app?: boolean;
-  completions?: boolean;
   skill?: boolean;
   mcp?: boolean;
   reinstall?: boolean;
-  update?: boolean;
-  from?: string;
   status?: boolean;
   uninstall?: boolean;
   configure?: boolean;

package/src/install/targets/app.ts

@@ -1,6 +1,5 @@
-import { existsSync } from "node:fs";
 import type { CliProgram } from "../../types.ts";
-import { installApp, uninstallApp } from "../app.ts";
+import { isExternallyManagedBinary } from "../binary-placement.ts";
 import { displayInstallPath, type InstallPaths } from "../paths.ts";
 import { InstallTarget } from "../target-base.ts";
 import type {
@@ -12,57 +11,49 @@ import type {
   UninstallAction,
 } from "../target-types.ts";
 
-/** Installs the compiled app to ~/.local/bin/<key>. */
+/** Reports app install location (Homebrew PATH or legacy ~/.local/bin). No self-install actions. */
 class AppInstallTarget extends InstallTarget {
   readonly key = "app" as const;
   readonly actionKind = "app" as const;
   readonly category = "core" as const;
 
+  defaultIncludedInAll(): boolean {
+    return false;
+  }
+
   isAvailable(_root: CliProgram, _paths: InstallPaths): boolean {
     return true;
   }
 
-  isDetected(paths: InstallPaths, _root: CliProgram): boolean {
-    return existsSync(paths.appPath);
+  isDetected(paths: InstallPaths, root: CliProgram): boolean {
+    return isExternallyManagedBinary(root.key) || false;
   }
 
-  applyDetected(paths: InstallPaths, root: CliProgram, out: InstalledArtifacts): void {
-    out.app = this.isDetected(paths, root);
+  applyDetected(_paths: InstallPaths, root: CliProgram, out: InstalledArtifacts): void {
+    out.app = isExternallyManagedBinary(root.key);
   }
 
   protected isDetectedFromSnapshot(detected: DetectedSnapshot): boolean {
     return detected.app;
   }
 
-  protected formatStatusLine(paths: InstallPaths, _root: CliProgram): string {
-    return displayInstallPath(paths.appPath);
+  protected formatStatusLine(_paths: InstallPaths, root: CliProgram): string {
+    if (isExternallyManagedBinary(root.key)) {
+      return "system (PATH)";
+    }
+    return "not installed (use Homebrew)";
   }
 
   protected assignStatusLine(status: InstallStatus, line: string): void {
     status.app = line;
   }
 
-  protected buildInstallActions(ctx: TargetPlanContext): InstallAction[] {
-    const sourcePath = ctx.opts.from ?? process.execPath;
-    return [
-      {
-        kind: this.actionKind,
-        summary: `app: ${displayInstallPath(ctx.paths.appPath)}`,
-        message: `Installing app to ${displayInstallPath(ctx.paths.appPath)}`,
-        run: () => installApp(ctx.root, ctx.paths, ctx.dry, sourcePath).changedFiles,
-      },
-    ];
+  protected buildInstallActions(_ctx: TargetPlanContext): InstallAction[] {
+    return [];
   }
 
-  protected buildUninstallActions(ctx: TargetPlanContext): UninstallAction[] {
-    return [
-      {
-        kind: this.actionKind,
-        summary: `app: ${displayInstallPath(ctx.paths.appPath)}`,
-        message: `Removing app ${displayInstallPath(ctx.paths.appPath)}`,
-        run: () => uninstallApp(ctx.root, ctx.paths, ctx.dry),
-      },
-    ];
+  protected buildUninstallActions(_ctx: TargetPlanContext): UninstallAction[] {
+    return [];
   }
 }
 

package/src/install/targets/configure.ts

@@ -1,5 +1,5 @@
 import { appConfigInstalled, displayAppConfigPath, uninstallAppConfig } from "../../config/file.ts";
-import type { CliProgram } from "../../types.ts";
+import type { CliProgram, InstallAgentIntegration } from "../../types.ts";
 import type { InstallPaths } from "../paths.ts";
 import { InstallTarget } from "../target-base.ts";
 import type {
@@ -11,12 +11,16 @@ import type {
   UninstallAction,
 } from "../target-types.ts";
 
-/** App config file (install --configure / wizard). */
+/** App config file (interactive configure / wizard). */
 class ConfigureInstallTarget extends InstallTarget {
   readonly key = "configure" as const;
   readonly actionKind = "configure" as const;
   readonly category = "core" as const;
 
+  defaultIncludedInAll(_integration: InstallAgentIntegration): boolean {
+    return false;
+  }
+
   isAvailable(root: CliProgram, _paths: InstallPaths): boolean {
     return root.appConfig !== undefined;
   }

package/src/install/targets/index.ts

@@ -6,7 +6,6 @@ import { claudeDesktopMcpTarget } from "./claude-desktop-mcp.ts";
 import { claudeSkillTarget } from "./claude-skill.ts";
 import { codexMcpTarget } from "./codex-mcp.ts";
 import { codexSkillTarget } from "./codex-skill.ts";
-import { completionsTarget } from "./completions.ts";
 import { configureTarget } from "./configure.ts";
 import { cursorMcpTarget } from "./cursor-mcp.ts";
 import { cursorSkillTarget } from "./cursor-skill.ts";
@@ -18,7 +17,6 @@ import { opencodeSkillTarget } from "./opencode-skill.ts";
 /** Ordered install targets (plan iteration order). */
 export const INSTALL_TARGETS: InstallTarget[] = [
   appTarget,
-  completionsTarget,
   cursorSkillTarget,
   claudeSkillTarget,
   codexSkillTarget,
@@ -42,7 +40,6 @@ export {
   claudeSkillTarget,
   codexMcpTarget,
   codexSkillTarget,
-  completionsTarget,
   configureTarget,
   cursorMcpTarget,
   cursorSkillTarget,

package/src/install/targets.test.ts

@@ -1,11 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import type { CliProgram } from "../types.ts";
-import { maybeBootstrapInstallArgv } from "./bootstrap.ts";
 import { normalizeInstallRawOpts } from "./normalize.ts";
-import { resolveInstallPaths } from "./paths.ts";
+import { normalizeUninstallRawOpts } from "./normalize-uninstall.ts";
 import { resolveAgentIntegration, resolveEffectiveInstallTargets } from "./target-effective.ts";
 import { isArtifactInScope } from "./target-scope.ts";
 
@@ -15,7 +11,7 @@ describe("normalizeInstallRawOpts", () => {
   });
 
   test("bare uninstall sets all", () => {
-    expect(normalizeInstallRawOpts({ uninstall: "1" })).toEqual({
+    expect(normalizeUninstallRawOpts({})).toEqual({
       uninstall: "1",
       all: "1",
     });
@@ -37,11 +33,10 @@ describe("resolveAgentIntegration", () => {
 });
 
 describe("resolveEffectiveInstallTargets", () => {
-  test("defaults app completions configure includedInAll", () => {
+  test("defaults app and configure not in --all", () => {
     const t = resolveEffectiveInstallTargets(undefined);
-    expect(t.app.includedInAll).toBe(true);
-    expect(t.completions.includedInAll).toBe(true);
-    expect(t.configure.includedInAll).toBe(true);
+    expect(t.app.includedInAll).toBe(false);
+    expect(t.configure.includedInAll).toBe(false);
   });
 
   test("skill mode includes skills in --all not MCP pairs", () => {
@@ -80,10 +75,10 @@ describe("resolveEffectiveInstallTargets", () => {
       version: "1",
       description: "x",
       mcpServer: { enabled: true },
-      install: { agentIntegration: "skill" },
+      configure: { agentIntegration: "skill" },
       handler: () => {},
     };
-    const effective = resolveEffectiveInstallTargets(program.install, program);
+    const effective = resolveEffectiveInstallTargets(program.configure, program);
     const scope = { mcp: true };
     expect(isArtifactInScope("cursorMcp", scope, effective, "install-scoped", program)).toBe(false);
     expect(
@@ -99,38 +94,25 @@ describe("resolveEffectiveInstallTargets", () => {
       ),
     ).toBe(true);
   });
-});
-
-describe("maybeBootstrapInstallArgv", () => {
-  const program: CliProgram = {
-    key: "bootapp",
-    version: "1.0.0",
-    description: "Boot",
-    handler: () => {},
-  };
-
-  test("rewrites empty argv when app missing and TTY", () => {
-    const prev = process.stdin.isTTY;
-    Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
-    try {
-      expect(maybeBootstrapInstallArgv([], program)).toEqual(["install"]);
-    } finally {
-      Object.defineProperty(process.stdin, "isTTY", { value: prev, configurable: true });
-    }
-  });
 
-  test("does not rewrite when app exists", () => {
-    const home = mkdtempSync(join(tmpdir(), "boot-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = home;
-    const paths = resolveInstallPaths(program);
-    try {
-      mkdirSync(paths.appDir, { recursive: true });
-      writeFileSync(paths.appPath, "x", "utf8");
-      expect(maybeBootstrapInstallArgv([], program)).toEqual([]);
-    } finally {
-      process.env.HOME = prevHome;
-      rmSync(home, { recursive: true, force: true });
-    }
+  test("scoped --mcp --skill --configure includes skill and mcp not only configure", () => {
+    const program: CliProgram = {
+      key: "app",
+      version: "1",
+      description: "x",
+      mcpServer: { enabled: true },
+      configure: { agentIntegration: "both" },
+      handler: () => {},
+    };
+    const effective = resolveEffectiveInstallTargets(program.configure, program);
+    const scope = { mcp: true, skill: true, configure: true };
+    expect(isArtifactInScope("cursorSkill", scope, effective, "install-scoped", program)).toBe(
+      true,
+    );
+    expect(isArtifactInScope("cursorMcp", scope, effective, "install-scoped", program)).toBe(true);
+    expect(isArtifactInScope("configure", scope, effective, "install-scoped", program)).toBe(true);
+    expect(isArtifactInScope("claudeSkill", scope, effective, "install-scoped", program)).toBe(
+      true,
+    );
   });
 });

package/src/invoke.test.ts

@@ -20,7 +20,7 @@ const program = {
   key: "t",
   description: "d",
   version: "0.0.0",
-  install: { enabled: false },
+  configure: { enabled: false },
   handler: (ctx) => console.log(ctx.invocation),
 };
 await new Cli(program).run([]);

package/src/mcp/env.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyShellEnv, bootstrapMcpEnv } from "./env.ts";
+
+const TEST_VAR = "ARGS_BARG_SHELL_ENV_TEST";
+
+describe("mcp/env", () => {
+  test("applyShellEnv merges PATH and fills missing vars", () => {
+    const prevPath = process.env.PATH;
+    const prevTest = process.env[TEST_VAR];
+    delete process.env[TEST_VAR];
+    try {
+      process.env.PATH = "/host/bin";
+      applyShellEnv({
+        PATH: "/shell/bin:/host/bin",
+        [TEST_VAR]: "from-shell",
+      });
+      expect(process.env.PATH).toBe("/shell/bin:/host/bin");
+      expect(process.env[TEST_VAR]).toBe("from-shell");
+    } finally {
+      if (prevPath === undefined) delete process.env.PATH;
+      else process.env.PATH = prevPath;
+      if (prevTest === undefined) delete process.env[TEST_VAR];
+      else process.env[TEST_VAR] = prevTest;
+    }
+  });
+
+  test("applyShellEnv does not overwrite host vars except PATH merge", () => {
+    const prev = process.env.HOME;
+    process.env.HOME = "/host/home";
+    try {
+      applyShellEnv({ HOME: "/shell/home" });
+      expect(process.env.HOME).toBe("/host/home");
+    } finally {
+      if (prev === undefined) delete process.env.HOME;
+      else process.env.HOME = prev;
+    }
+  });
+});
+
+describe("bootstrapMcpEnv", () => {
+  let fakeShell: string;
+  let prevShell: string | undefined;
+  let prevTest: string | undefined;
+
+  beforeEach(() => {
+    const dir = mkdtempSync(join(tmpdir(), "argsbarg-shell-env-"));
+    fakeShell = join(dir, "fake-shell.sh");
+    writeFileSync(
+      fakeShell,
+      `#!/bin/sh
+if [ "$1" = "-l" ] && [ "$2" = "-c" ] && [ "$3" = "env" ]; then
+  echo "${TEST_VAR}=from_fake_shell"
+fi
+`,
+    );
+    chmodSync(fakeShell, 0o755);
+    prevShell = process.env.SHELL;
+    prevTest = process.env[TEST_VAR];
+    delete process.env[TEST_VAR];
+    process.env.SHELL = fakeShell;
+  });
+
+  afterEach(() => {
+    if (prevShell === undefined) delete process.env.SHELL;
+    else process.env.SHELL = prevShell;
+    if (prevTest === undefined) delete process.env[TEST_VAR];
+    else process.env[TEST_VAR] = prevTest;
+  });
+
+  test("defaults on when shellEnv is undefined", () => {
+    bootstrapMcpEnv({});
+    expect(process.env[TEST_VAR]).toBe("from_fake_shell");
+  });
+
+  test("runs when shellEnv is true", () => {
+    bootstrapMcpEnv({ shellEnv: true });
+    expect(process.env[TEST_VAR]).toBe("from_fake_shell");
+  });
+
+  test("uses explicit shell path when shellEnv is a string", () => {
+    bootstrapMcpEnv({ shellEnv: fakeShell });
+    expect(process.env[TEST_VAR]).toBe("from_fake_shell");
+  });
+
+  test("skips capture when shellEnv is false", () => {
+    bootstrapMcpEnv({ shellEnv: false });
+    expect(process.env[TEST_VAR]).toBeUndefined();
+  });
+});

package/src/mcp/env.ts

@@ -39,21 +39,22 @@ export function applyShellEnv(env: Record<string, string>): void {
   }
 }
 
-/** Applies mcpServer shellEnv bootstrap. */
+/** Applies mcpServer shellEnv bootstrap (default on; opt out with `shellEnv: false`). */
 export function bootstrapMcpEnv(config: { shellEnv?: boolean | string }): void {
+  if (config.shellEnv === false) {
+    return;
+  }
   const shellEnvCfg = config.shellEnv;
-  if (shellEnvCfg) {
-    const shell =
-      typeof shellEnvCfg === "string"
-        ? shellEnvCfg
-        : (process.env.SHELL ?? (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash"));
-    const captured = captureShellEnv(shell);
-    if (Object.keys(captured).length === 0) {
-      process.stderr.write(
-        `[argsbarg] shellEnv: failed to capture shell environment from ${shell}\n`,
-      );
-    } else {
-      applyShellEnv(captured);
-    }
+  const shell =
+    typeof shellEnvCfg === "string"
+      ? shellEnvCfg
+      : (process.env.SHELL ?? (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash"));
+  const captured = captureShellEnv(shell);
+  if (Object.keys(captured).length === 0) {
+    process.stderr.write(
+      `[argsbarg] shellEnv: failed to capture shell environment from ${shell}\n`,
+    );
+  } else {
+    applyShellEnv(captured);
   }
 }

package/src/mcp/tools.ts

@@ -224,7 +224,7 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
     if (isCliLeaf(cmd)) {
       if (
         cmd.key === "completion" ||
-        cmd.key === "install" ||
+        cmd.key === "configure" ||
         cmd.key === "mcp" ||
         cmd.key === "version"
       ) {

package/src/mcp.integration.test.ts

@@ -35,7 +35,7 @@ test("collectMcpTools lists user leaf commands only", () => {
   expect(names).toContain("stat_owner_lookup");
   expect(names).toContain("read");
   expect(names).not.toContain("hidden");
-  expect(names).not.toContain("install");
+  expect(names).not.toContain("configure");
   expect(names).not.toContain("mcp");
   expect(names).not.toContain("completion");
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -242,19 +242,19 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
-test("reserved command name install is rejected", () => {
+test("reserved command name configure is rejected", () => {
   const root = testProgram({
     key: "app",
     description: "",
     commands: [
       {
-        key: "install",
+        key: "configure",
         description: "bad",
         handler: () => {},
       },
     ],
   });
-  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: install/);
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: configure/);
 });
 
 test("top-level command name mcp is allowed without mcpServer", () => {

package/src/parse.test.ts

@@ -495,7 +495,7 @@ test("leaf completion help prints correctly", async () => {
   const out = stdout.toString();
   expect(exitCode).toBe(0);
   expect(out).toContain("Show help for this command.");
-  expect(out).toContain("Manual install:");
+  expect(out).toContain("Homebrew");
   expect(stderr.toString()).toBe("");
 });
 
@@ -526,9 +526,8 @@ test("docs schema exports JSON for leaf roots", async () => {
   expect(schema.positionals[0].name).toBe("name");
   expect(schema.options[0].name).toBe("verbose");
   expect(schema.commands.map((c: { key: string }) => c.key)).toEqual([
-    "completion",
     "version",
-    "install",
+    "configure",
     "docs",
   ]);
 });
@@ -539,11 +538,11 @@ test("version builtin prints program version", async () => {
   expect(stdout.toString().trim()).toMatch(/^\d+\.\d+\.\d+/);
 });
 
-test("leaf root help lists completion built-in", async () => {
+test("leaf root help omits hidden completion built-in", async () => {
   const { stdout, exitCode } = await $`bun run examples/minimal.ts -h`.nothrow().quiet();
   expect(exitCode).toBe(0);
-  expect(stdout.toString()).toContain("completion");
-  expect(stdout.toString()).toContain("Generate the autocompletion script for shells.");
+  expect(stdout.toString()).not.toContain("completion");
+  expect(stdout.toString()).toContain("configure");
 });
 
 test("root --schema is no longer a flag", () => {
@@ -614,7 +613,7 @@ test("cliSchemaExport resolves program key in install notes", () => {
 
   const json = cliSchemaJson(root);
   expect(json).not.toContain("{argsbarg:program}");
-  expect(json).toContain("myapp install --yes");
+  expect(json).toContain("brew install");
 });
 
 test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
@@ -1107,7 +1106,7 @@ test("mcpToolCallToArgv empty array varargs errors when required", () => {
 
 // ── Skills ────────────────────────────────────────────────────────────────────
 
-test("install config on non-root node is rejected", () => {
+test("configure config on non-root node is rejected", () => {
   const root = {
     key: "app",
     version: "0.0.0",
@@ -1116,23 +1115,23 @@ test("install config on non-root node is rejected", () => {
       {
         key: "x",
         description: "",
-        install: { enabled: false },
+        configure: { enabled: false },
         handler: () => {},
       },
     ],
   } as unknown as CliProgram;
-  expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
+  expect(() => cliValidateProgram(root)).toThrow(/configure is only supported on the program root/);
 });
 
-test("install.prefix is rejected", () => {
+test("configure.prefix is rejected", () => {
   const root = {
     key: "app",
     version: "0.0.0",
     description: "",
-    install: { prefix: "/opt/bin" },
+    configure: { prefix: "/opt/bin" },
     handler: () => {},
   } as unknown as CliProgram;
-  expect(() => cliValidateProgram(root)).toThrow(/install\.prefix removed/);
+  expect(() => cliValidateProgram(root)).toThrow(/configure\.prefix removed/);
 });
 
 test("generateSkillBundle includes frontmatter and compact command index", () => {
@@ -1183,7 +1182,7 @@ test("cliSkillInstall writes project Cursor skill files", () => {
     expect(readFileSync(join(skillDir, "reference.md"), "utf8")).toContain("CLI API reference");
     const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
     expect(skillText.startsWith("---\n")).toBe(true);
-    const hint = "<!-- Generated by nested.ts install --skill; do not edit. -->";
+    const hint = "<!-- Generated by nested.ts configure; do not edit. -->";
     expect(skillText.indexOf(hint)).toBeGreaterThan(skillText.indexOf("---\n", 4));
     const refText = readFileSync(join(skillDir, "reference.md"), "utf8");
     expect(refText.startsWith(hint)).toBe(true);

package/src/prompt.ts

@@ -0,0 +1,10 @@
+/** Shared terminal prompt helpers. */
+
+import { readSync } from "node:fs";
+
+/** Read one line from stdin (no masking). */
+export function readPromptLine(): string {
+  const buf = Buffer.alloc(4096);
+  const n = readSync(0, buf, { length: 4096 });
+  return buf.toString("utf8", 0, n).replace(/\r?\n$/, "");
+}

package/src/schema.ts

@@ -13,7 +13,7 @@ import {
   leafOutputSchema,
 } from "./types.ts";
 
-const RESERVED = new Set(["completion", "install", "docs", "mcp", "version", "config"]);
+const RESERVED = new Set(["completion", "configure", "docs", "mcp", "version", "config"]);
 
 function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
   if (cmd.hidden) {

package/src/skill/hint.ts

@@ -23,9 +23,9 @@ export function insertGeneratedHint(
   return `${hint}${content}`;
 }
 
-/** Hint for `install --skill` output files. */
+/** Hint for `configure` skill output files. */
 export function skillInstallHint(program: CliProgram): string {
-  return generatedFileHtmlComment(`${program.key} install --skill`);
+  return generatedFileHtmlComment(`${program.key} configure`);
 }
 
 /** Applies install hints to SKILL.md (after frontmatter) and reference.md. */