argsbarg 4.1.1 → 5.0.2

package/src/install/target-scope.ts

@@ -1,6 +1,6 @@
 import { resolveCapabilities } from "../capabilities.ts";
 import { appConfigInstalled } from "../config/file.ts";
-import type { CliInstallTargets, CliProgram } from "../types.ts";
+import type { CliConfigureTargets, CliProgram } from "../types.ts";
 import type { InstallPaths } from "./paths.ts";
 import {
   type InstallPlanMode,
@@ -78,7 +78,7 @@ export function buildDetectedSnapshot(root: CliProgram, paths: InstallPaths): De
 }
 
 function targetExplicitlyConfigured(
-  user: CliInstallTargets | undefined,
+  user: CliConfigureTargets | undefined,
   key: CliInstallArtifactKey,
 ): boolean {
   return user?.[key] !== undefined;
@@ -89,7 +89,7 @@ function agentCategoryInScope(
   categoryKeys: readonly CliInstallArtifactKey[],
   category: "skill" | "mcp",
   effective: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>,
-  targets: CliInstallTargets | undefined,
+  targets: CliConfigureTargets | undefined,
   root: CliProgram,
 ): boolean {
   if (!categoryKeys.includes(key)) return false;
@@ -105,7 +105,7 @@ export function isArtifactInScope(
   effective: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>,
   mode: InstallPlanMode,
   root: CliProgram,
-  targets?: CliInstallTargets,
+  targets?: CliConfigureTargets,
 ): boolean {
   if (mode === "uninstall-all") {
     return true;
@@ -150,7 +150,7 @@ export function shouldIncludeArtifact(
   detected?: Partial<Record<CliInstallArtifactKey, boolean>>,
 ): boolean {
   const target = installTargetForKey(key);
-  const targets = root.install?.targets;
+  const targets = root.configure?.targets;
 
   if (key !== "configure" && target && !target.isAvailable(root, paths)) {
     return false;
@@ -196,7 +196,7 @@ export function buildTargetPlanContext(
   opts: InstallOpts,
   detected: DetectedSnapshot,
 ): TargetPlanContext {
-  const effective = resolveEffectiveInstallTargets(root.install, root);
+  const effective = resolveEffectiveInstallTargets(root.configure, root);
   const mode = resolveInstallPlanMode(opts);
   const scope = resolveInstallScope(opts);
   const detPartial = Object.fromEntries(
@@ -236,8 +236,11 @@ export function resolveInstallTargetPreview(
   program: CliProgram,
   paths: InstallPaths,
 ): InstallTargetPreview {
-  const effective = resolveEffectiveInstallTargets(program.install, program);
-  const integration = resolveAgentIntegration(program.install, program.mcpServer?.enabled === true);
+  const effective = resolveEffectiveInstallTargets(program.configure, program);
+  const integration = resolveAgentIntegration(
+    program.configure,
+    program.mcpServer?.enabled === true,
+  );
 
   const keysForScope = (scope: InstallScope, mode: InstallPlanMode): CliInstallArtifactKey[] =>
     INSTALL_ARTIFACT_KEYS.filter((key) =>

package/src/install/targets/configure.ts

@@ -11,7 +11,7 @@ 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;

package/src/install/targets.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/targets module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import { normalizeInstallRawOpts } from "./normalize.ts";
@@ -5,11 +9,14 @@ import { normalizeUninstallRawOpts } from "./normalize-uninstall.ts";
 import { resolveAgentIntegration, resolveEffectiveInstallTargets } from "./target-effective.ts";
 import { isArtifactInScope } from "./target-scope.ts";
 
+/** Tests for normalizeInstallRawOpts. */
 describe("normalizeInstallRawOpts", () => {
+  /** Bare install sets all. */
   test("bare install sets all", () => {
     expect(normalizeInstallRawOpts({})).toEqual({ all: "1" });
   });
 
+  /** Bare uninstall sets all. */
   test("bare uninstall sets all", () => {
     expect(normalizeUninstallRawOpts({})).toEqual({
       uninstall: "1",
@@ -17,28 +24,35 @@ describe("normalizeInstallRawOpts", () => {
     });
   });
 
+  /** Configure-only install unchanged. */
   test("configure-only install unchanged", () => {
     expect(normalizeInstallRawOpts({ configure: "1" })).toEqual({ configure: "1" });
   });
 });
 
+/** Tests for resolveAgentIntegration. */
 describe("resolveAgentIntegration", () => {
+  /** Defaults to skill without MCP. */
   test("defaults to skill without MCP", () => {
     expect(resolveAgentIntegration(undefined, false)).toBe("skill");
   });
 
+  /** Defaults to mcp when MCP enabled. */
   test("defaults to mcp when MCP enabled", () => {
     expect(resolveAgentIntegration(undefined, true)).toBe("mcp");
   });
 });
 
+/** Tests for resolveEffectiveInstallTargets. */
 describe("resolveEffectiveInstallTargets", () => {
+  /** Defaults app and configure not in --all. */
   test("defaults app and configure not in --all", () => {
     const t = resolveEffectiveInstallTargets(undefined);
     expect(t.app.includedInAll).toBe(false);
     expect(t.configure.includedInAll).toBe(false);
   });
 
+  /** Skill mode includes skills in --all not MCP pairs. */
   test("skill mode includes skills in --all not MCP pairs", () => {
     const program: Pick<CliProgram, "mcpServer"> = {};
     const t = resolveEffectiveInstallTargets(undefined, program);
@@ -46,6 +60,7 @@ describe("resolveEffectiveInstallTargets", () => {
     expect(t.cursorMcp.includedInAll).toBe(false);
   });
 
+  /** Mcp mode includes MCP in --all not paired skills. */
   test("mcp mode includes MCP in --all not paired skills", () => {
     const program: Pick<CliProgram, "mcpServer"> = { mcpServer: { enabled: true } };
     const t = resolveEffectiveInstallTargets(undefined, program);
@@ -54,6 +69,7 @@ describe("resolveEffectiveInstallTargets", () => {
     expect(t.claudeDesktopMcp.includedInAll).toBe(true);
   });
 
+  /** Tests that both mode includes MCP and skills. */
   test("both mode includes MCP and skills", () => {
     const program: Pick<CliProgram, "mcpServer"> = { mcpServer: { enabled: true } };
     const t = resolveEffectiveInstallTargets({ agentIntegration: "both" }, program);
@@ -61,6 +77,7 @@ describe("resolveEffectiveInstallTargets", () => {
     expect(t.cursorSkill.includedInAll).toBe(true);
   });
 
+  /** Tests that per-key override disables one skill. */
   test("per-key override disables one skill", () => {
     const t = resolveEffectiveInstallTargets({
       targets: { cursorSkill: false },
@@ -69,16 +86,17 @@ describe("resolveEffectiveInstallTargets", () => {
     expect(t.cursorSkill.enabled).toBe(false);
   });
 
+  /** Scoped --mcp uses effective targets not all MCP hosts. */
   test("scoped --mcp uses effective targets not all MCP hosts", () => {
     const program: CliProgram = {
       key: "app",
       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(
@@ -95,16 +113,17 @@ describe("resolveEffectiveInstallTargets", () => {
     ).toBe(true);
   });
 
+  /** Scoped --mcp --skill --configure includes skill and mcp not only configure. */
   test("scoped --mcp --skill --configure includes skill and mcp not only configure", () => {
     const program: CliProgram = {
       key: "app",
       version: "1",
       description: "x",
       mcpServer: { enabled: true },
-      install: { agentIntegration: "both" },
+      configure: { agentIntegration: "both" },
       handler: () => {},
     };
-    const effective = resolveEffectiveInstallTargets(program.install, program);
+    const effective = resolveEffectiveInstallTargets(program.configure, program);
     const scope = { mcp: true, skill: true, configure: true };
     expect(isArtifactInScope("cursorSkill", scope, effective, "install-scoped", program)).toBe(
       true,

package/src/invoke.test.ts

@@ -12,6 +12,7 @@ import type { CliLeaf } from "./types.ts";
 import { isCliRouter } from "./types.ts";
 import { cliValidateProgram } from "./validate.ts";
 
+/** Tests that ctx.invocation is cli via Cli.run. */
 test("ctx.invocation is cli via Cli.run", async () => {
   const indexPath = join(import.meta.dir, "index.ts");
   const { stdout } = await $`bun -e ${`
@@ -20,7 +21,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([]);
@@ -28,6 +29,7 @@ await new Cli(program).run([]);
   expect(stdout.toString().trim()).toBe("cli");
 });
 
+/** Tests that ctx.invocation is mcp via Cli.invoke. */
 test("ctx.invocation is mcp via Cli.invoke", async () => {
   let seen = "";
   const root = testProgram({
@@ -43,6 +45,7 @@ test("ctx.invocation is mcp via Cli.invoke", async () => {
   expect(seen).toBe("mcp");
 });
 
+/** Cli.invoke rejects invalid Enum value. */
 test("Cli.invoke rejects invalid Enum value", async () => {
   const root = testProgram({
     key: "app",
@@ -64,6 +67,7 @@ test("Cli.invoke rejects invalid Enum value", async () => {
   expect(result.errorMsg).toContain("not one of");
 });
 
+/** Cli.invoke accepts valid Enum value. */
 test("Cli.invoke accepts valid Enum value", async () => {
   const root = testProgram({
     key: "app",
@@ -87,6 +91,7 @@ test("Cli.invoke accepts valid Enum value", async () => {
   expect(result.stdout.trim()).toBe("dev");
 });
 
+/** Varargs trailing option after positionals via Cli.invoke. */
 test("varargs trailing option after positionals via Cli.invoke", async () => {
   const root = varargsReadFixture();
   cliValidateProgram(root);
@@ -96,6 +101,7 @@ test("varargs trailing option after positionals via Cli.invoke", async () => {
   expect(pr.opts.json).toBe("1");
 });
 
+/** Varargs option before positionals. */
 test("varargs option before positionals", () => {
   const root = varargsReadFixture();
   cliValidateProgram(root);
@@ -105,6 +111,7 @@ test("varargs option before positionals", () => {
   expect(pr.opts.json).toBe("1");
 });
 
+/** Varargs multiple files then trailing option. */
 test("varargs multiple files then trailing option", () => {
   const root = varargsReadFixture();
   cliValidateProgram(root);
@@ -114,6 +121,7 @@ test("varargs multiple files then trailing option", () => {
   expect(pr.opts.json).toBe("1");
 });
 
+/** Varargs double dash forces positional. */
 test("varargs double dash forces positional", () => {
   const root = varargsReadFixture();
   cliValidateProgram(root);
@@ -123,6 +131,7 @@ test("varargs double dash forces positional", () => {
   expect(pr.opts.json).toBeUndefined();
 });
 
+/** Varargs unknown flag errors. */
 test("varargs unknown flag errors", async () => {
   const root = varargsReadFixture();
   cliValidateProgram(root);
@@ -131,6 +140,7 @@ test("varargs unknown flag errors", async () => {
   expect(result.stderr).toContain("--unknown");
 });
 
+/** Varargs scoped help in tail. */
 test("varargs scoped help in tail", () => {
   const root = varargsReadFixture();
   cliValidateProgram(root);
@@ -140,6 +150,7 @@ test("varargs scoped help in tail", () => {
   expect(pr.helpExplicit).toBe(true);
 });
 
+/** Tests that ctx.positional returns single slot value. */
 test("ctx.positional returns single slot value", async () => {
   const root = testProgram({
     key: "app",
@@ -161,6 +172,7 @@ test("ctx.positional returns single slot value", async () => {
   expect(captured).toBe("./file");
 });
 
+/** Tests that ctx.positional returns varargs array. */
 test("ctx.positional returns varargs array", async () => {
   const root = varargsReadFixture();
   let captured: string | string[] | undefined;
@@ -174,6 +186,7 @@ test("ctx.positional returns varargs array", async () => {
   expect(captured).toEqual(["a.txt", "b.txt"]);
 });
 
+/** Tests that ctx.positional returns undefined for absent optional slot. */
 test("ctx.positional returns undefined for absent optional slot", async () => {
   const root = testProgram({
     key: "app",
@@ -197,6 +210,7 @@ test("ctx.positional returns undefined for absent optional slot", async () => {
   expect(captured).toBeUndefined();
 });
 
+/** Tests that ctx.positional varargs matches ctx.args. */
 test("ctx.positional varargs matches ctx.args", async () => {
   const root = varargsReadFixture();
   let positional: string | string[] | undefined;

package/src/mcp/claude.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for mcp/claude module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { execSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -29,11 +33,14 @@ const configFixture: CliProgram = {
   commands: [{ key: "run", description: "Run.", handler: () => {} }],
 };
 
+/** Tests for claude plugin. */
 describe("claude plugin", () => {
+  /** PluginName is kebab-case. */
   test("pluginName is kebab-case", () => {
     expect(pluginName({ ...configFixture, key: "MyApp" })).toBe("my-app");
   });
 
+  /** Tests that generatePluginManifest includes userConfig from program.appConfig. */
   test("generatePluginManifest includes userConfig from program.appConfig", () => {
     const manifest = generatePluginManifest(configFixture, "myapp");
     expect(manifest.name).toBe("myapp");
@@ -43,6 +50,7 @@ describe("claude plugin", () => {
     expect(userConfig.api_token?.sensitive).toBe(true);
   });
 
+  /** Tests that generatePluginMcpJson uses CLAUDE_PLUGIN_ROOT and env mapping. */
   test("generatePluginMcpJson uses CLAUDE_PLUGIN_ROOT and env mapping", () => {
     const json = generatePluginMcpJson(configFixture, "myapp");
     const entry = json.myapp as { command: string; args: string[]; env: Record<string, string> };
@@ -51,12 +59,14 @@ describe("claude plugin", () => {
     expect(entry.env.API_TOKEN).toBe("${user_config.api_token}");
   });
 
+  /** DefaultClaudePluginPaths. */
   test("defaultClaudePluginPaths", () => {
     const cwd = "/tmp/work";
     const paths = defaultClaudePluginPaths(configFixture, cwd);
     expect(paths.pluginZipPath).toBe(join(cwd, "dist", "claude-plugin", "myapp.zip"));
   });
 
+  /** Tests that packClaudePlugin writes zip with MCP pointer skill only. */
   test("packClaudePlugin writes zip with MCP pointer skill only", () => {
     const work = mkdtempSync(join(tmpdir(), "claude-plugin-test-"));
     try {

package/src/mcp/env.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for mcp/env module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { chmodSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -6,7 +10,9 @@ import { applyShellEnv, bootstrapMcpEnv } from "./env.ts";
 
 const TEST_VAR = "ARGS_BARG_SHELL_ENV_TEST";
 
+/** Tests for mcp/env. */
 describe("mcp/env", () => {
+  /** ApplyShellEnv merges PATH and fills missing vars. */
   test("applyShellEnv merges PATH and fills missing vars", () => {
     const prevPath = process.env.PATH;
     const prevTest = process.env[TEST_VAR];
@@ -27,6 +33,7 @@ describe("mcp/env", () => {
     }
   });
 
+  /** ApplyShellEnv does not overwrite host vars except PATH merge. */
   test("applyShellEnv does not overwrite host vars except PATH merge", () => {
     const prev = process.env.HOME;
     process.env.HOME = "/host/home";
@@ -40,6 +47,7 @@ describe("mcp/env", () => {
   });
 });
 
+/** Tests for bootstrapMcpEnv. */
 describe("bootstrapMcpEnv", () => {
   let fakeShell: string;
   let prevShell: string | undefined;
@@ -70,21 +78,25 @@ fi
     else process.env[TEST_VAR] = prevTest;
   });
 
+  /** Defaults on when shellEnv is undefined. */
   test("defaults on when shellEnv is undefined", () => {
     bootstrapMcpEnv({});
     expect(process.env[TEST_VAR]).toBe("from_fake_shell");
   });
 
+  /** Runs when shellEnv is true. */
   test("runs when shellEnv is true", () => {
     bootstrapMcpEnv({ shellEnv: true });
     expect(process.env[TEST_VAR]).toBe("from_fake_shell");
   });
 
+  /** Tests that uses explicit shell path when shellEnv is a string. */
   test("uses explicit shell path when shellEnv is a string", () => {
     bootstrapMcpEnv({ shellEnv: fakeShell });
     expect(process.env[TEST_VAR]).toBe("from_fake_shell");
   });
 
+  /** Tests that skips capture when shellEnv is false. */
   test("skips capture when shellEnv is false", () => {
     bootstrapMcpEnv({ shellEnv: false });
     expect(process.env[TEST_VAR]).toBeUndefined();

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

@@ -1,3 +1,7 @@
+/*
+Tests for mcp/zip module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { execSync } from "node:child_process";
 import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -5,6 +9,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { zipStore } from "./zip.ts";
 
+/** ZipStore preserves unix executable mode on extract. */
 test("zipStore preserves unix executable mode on extract", () => {
   const work = mkdtempSync(join(tmpdir(), "zip-exec-"));
   const data = Buffer.from("#!/bin/sh\necho hi\n");