argsbarg 5.0.1 → 5.0.3

package/src/formats.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for formats module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import {
   parseCommaList,

package/src/headless.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for headless module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import {
   formatDryRunMessage,
@@ -30,6 +34,7 @@ test("shouldRunHeadlessWithPositionals requires positionals in non-tty", () => {
   );
 });
 
+/** Tests that shouldRunHeadlessWithYes requires yes in non-tty. */
 test("shouldRunHeadlessWithYes requires yes in non-tty", () => {
   expect(
     shouldRunHeadlessWithYes({ invocation: "cli" }, { yes: true, hasRequiredArgs: true }, false),
@@ -51,6 +56,7 @@ test("formatDryRunMessage prefixes dry-run output", () => {
   expect(formatDryRunMessage("hello", true)).toBe("[DRY RUN] hello");
 });
 
+/** Tests that requireYesInNonTty exits without yes in non-tty. */
 test("requireYesInNonTty exits without yes in non-tty", () => {
   const originalExit = process.exit;
   let code: number | undefined;

package/src/headless.ts

@@ -57,14 +57,15 @@ export function shouldRunHeadlessWithYes(
   return opts.yes && opts.hasRequiredArgs;
 }
 
-/**
- * Exits when non-interactive mode is used without `--yes`.
- * @param hint - Command-specific guidance appended to the error
- */
+/** Exits when non-interactive mode is used without `--yes`. */
 export function requireYesInNonTty(
+  /** True when `--yes` was passed on the command line. */
   yes: boolean,
+  /** Command-specific guidance appended to the error message. */
   hint: string,
+  /** When true, skip the check (dry-run preview). */
   dryRun = false,
+  /** Injectable TTY probe for tests. */
   interactive: boolean = isInteractiveTty,
 ): void {
   if (dryRun) return;

package/src/hidden-mcpb.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for hidden-mcpb module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -53,6 +57,7 @@ const hiddenFixture: CliProgram = {
   ],
 };
 
+/** Tests for hidden commands and options. */
 describe("hidden commands and options", () => {
   test("parse root includes hidden commands", () => {
     const parse = cliParseRoot(hiddenFixture);
@@ -98,6 +103,7 @@ describe("hidden commands and options", () => {
   });
 });
 
+/** Tests for mcp router. */
 describe("mcp router", () => {
   test("presentation exposes mcp bundle but not hidden serve", () => {
     const builtins = exportPresentationBuiltins(hiddenFixture);
@@ -114,6 +120,7 @@ describe("mcp router", () => {
   });
 });
 
+/** Tests for mcp bundle. */
 describe("mcp bundle", () => {
   test("generateMcpManifest uses mcpServerId and binary entry", () => {
     const manifest = generateMcpManifest(hiddenFixture, "myapp");
@@ -135,6 +142,7 @@ describe("mcp bundle", () => {
     expect(paths.outPath).toBe(join(cwd, "dist", "myapp.mcpb"));
   });
 
+  /** Tests that packMcpBundle writes zip with manifest and binary. */
   test("packMcpBundle writes zip with manifest and binary", () => {
     const work = mkdtempSync(join(tmpdir(), "mcpb-test-"));
     try {
@@ -155,6 +163,7 @@ describe("mcp bundle", () => {
     }
   });
 
+  /** RunMcpBundle prints mcpb and plugin paths. */
   test("runMcpBundle prints mcpb and plugin paths", () => {
     const work = mkdtempSync(join(tmpdir(), "mcpb-run-"));
     const stdout: string[] = [];
@@ -188,6 +197,7 @@ describe("mcp bundle", () => {
     }
   });
 
+  /** RunMcpBundle with claudePlugin only prints plugin path. */
   test("runMcpBundle with claudePlugin only prints plugin path", () => {
     const work = mkdtempSync(join(tmpdir(), "mcpb-run-"));
     const stdout: string[] = [];

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

@@ -1,3 +1,7 @@
+/*
+Tests for install/binary-placement module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -30,6 +34,7 @@ afterEach(() => {
   rmSync(tmp, { recursive: true, force: true });
 });
 
+/** Tests for isExternallyManagedBinary. */
 describe("isExternallyManagedBinary", () => {
   test("false when command is not on PATH", () => {
     process.env.PATH = tmp;
@@ -63,7 +68,9 @@ describe("isExternallyManagedBinary", () => {
   });
 });
 
+/** Tests for isAppInstalled. */
 describe("isAppInstalled", () => {
+  /** Tests that true when externally managed. */
   test("true when externally managed", () => {
     const bin = join(tmp, program.key);
     const prevExec = process.execPath;
@@ -78,6 +85,7 @@ describe("isAppInstalled", () => {
     }
   });
 
+  /** Tests that false when not on PATH and no local copy. */
   test("false when not on PATH and no local copy", () => {
     const home = mkdtempSync(join(tmpdir(), "argsbarg-placement-home-"));
     const prevHome = process.env.HOME;
@@ -93,6 +101,7 @@ describe("isAppInstalled", () => {
   });
 });
 
+/** Tests for resolvePathCommand. */
 describe("resolvePathCommand", () => {
   test("returns undefined when missing", () => {
     process.env.PATH = tmp;

package/src/install/gh-release-update.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/gh-release-update module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { isAlreadyCurrent, parseReleaseTag } from "./gh-release-update.ts";
 

package/src/install/install-validate.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/install-validate module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import { CliSchemaValidationError } from "../types.ts";
@@ -10,6 +14,7 @@ const base: CliProgram = {
   handler: () => {},
 };
 
+/** Tests for validateConfigureConfig. */
 describe("validateConfigureConfig", () => {
   test("accepts empty install config", () => {
     expect(() => cliValidateProgram(base)).not.toThrow();

package/src/install/mcp-codex.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/mcp-codex module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -19,7 +23,9 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for codex mcp config. */
 describe("codex mcp config", () => {
+  /** ReadCodexMcpEntry parses simple command/args. */
   test("readCodexMcpEntry parses simple command/args", () => {
     const path = resolveCodexConfigPath(home);
     mkdirSync(join(home, ".codex"), { recursive: true });
@@ -38,6 +44,7 @@ args = ["mcp"]
     expect(codexMcpHasServer(home, "testapp")).toBe(true);
   });
 
+  /** ReadCodexMcpEntry parses transport stdio block. */
   test("readCodexMcpEntry parses transport stdio block", () => {
     const path = resolveCodexConfigPath(home);
     mkdirSync(join(home, ".codex"), { recursive: true });

package/src/install/mcp-openclaw.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/mcp-openclaw module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -19,7 +23,9 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for openclaw mcp config. */
 describe("openclaw mcp config", () => {
+  /** OpenclawMcpHasServer detects configured server. */
   test("openclawMcpHasServer detects configured server", () => {
     const path = resolveOpenclawConfigPath(home);
     mkdirSync(join(home, ".openclaw"), { recursive: true });

package/src/install/mcp-opencode.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/mcp-opencode module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -41,6 +45,7 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for opencode mcp config. */
 describe("opencode mcp config", () => {
   test("resolveOpenCodeConfigPathForInstall prefers existing file", () => {
     const dir = opencodeConfigDir(home);
@@ -70,6 +75,7 @@ describe("opencode mcp config", () => {
     expect(data.mcp.testapp).toEqual(entry);
   });
 
+  /** DetectOpenCodeMcpConfigPath finds entry across filenames. */
   test("detectOpenCodeMcpConfigPath finds entry across filenames", () => {
     const dir = opencodeConfigDir(home);
     mkdirSync(dir, { recursive: true });

package/src/install/status.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for install/status module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -22,7 +26,9 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for resolveInstallTargetPreview. */
 describe("resolveInstallTargetPreview", () => {
+  /** Mcp app previews MCP keys for all and mcp scopes. */
   test("mcp app previews MCP keys for all and mcp scopes", () => {
     const program: CliProgram = {
       key: "mcpapp",
@@ -39,6 +45,7 @@ describe("resolveInstallTargetPreview", () => {
     expect(preview.all.every((k) => k.endsWith("Mcp") || k === "configure")).toBe(true);
   });
 
+  /** Tests that shell app previews skill keys. */
   test("shell app previews skill keys", () => {
     const program: CliProgram = {
       key: "cliapp",
@@ -55,7 +62,9 @@ describe("resolveInstallTargetPreview", () => {
   });
 });
 
+/** Tests for printInstallStatus json. */
 describe("printInstallStatus json", () => {
+  /** Includes agentIntegration and effective scopes. */
   test("includes agentIntegration and effective scopes", () => {
     const program: CliProgram = {
       key: "app",

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,6 +9,7 @@ import { normalizeUninstallRawOpts } from "./normalize-uninstall.ts";
 import { resolveAgentIntegration, resolveEffectiveInstallTargets } from "./target-effective.ts";
 import { isArtifactInScope } from "./target-scope.ts";
 
+/** Tests for normalizeInstallRawOpts. */
 describe("normalizeInstallRawOpts", () => {
   test("bare install sets all", () => {
     expect(normalizeInstallRawOpts({})).toEqual({ all: "1" });
@@ -22,6 +27,7 @@ describe("normalizeInstallRawOpts", () => {
   });
 });
 
+/** Tests for resolveAgentIntegration. */
 describe("resolveAgentIntegration", () => {
   test("defaults to skill without MCP", () => {
     expect(resolveAgentIntegration(undefined, false)).toBe("skill");
@@ -32,6 +38,7 @@ describe("resolveAgentIntegration", () => {
   });
 });
 
+/** Tests for resolveEffectiveInstallTargets. */
 describe("resolveEffectiveInstallTargets", () => {
   test("defaults app and configure not in --all", () => {
     const t = resolveEffectiveInstallTargets(undefined);
@@ -69,6 +76,7 @@ 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",
@@ -95,6 +103,7 @@ 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",

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 ${`
@@ -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",
@@ -140,6 +144,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",
@@ -174,6 +179,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 +203,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,6 +33,7 @@ const configFixture: CliProgram = {
   commands: [{ key: "run", description: "Run.", handler: () => {} }],
 };
 
+/** Tests for claude plugin. */
 describe("claude plugin", () => {
   test("pluginName is kebab-case", () => {
     expect(pluginName({ ...configFixture, key: "MyApp" })).toBe("my-app");
@@ -57,6 +62,7 @@ describe("claude plugin", () => {
     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];
@@ -40,6 +46,7 @@ describe("mcp/env", () => {
   });
 });
 
+/** Tests for bootstrapMcpEnv. */
 describe("bootstrapMcpEnv", () => {
   let fakeShell: string;
   let prevShell: string | undefined;

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";

package/src/mcp.integration.test.ts

@@ -42,6 +42,7 @@ test("collectMcpTools lists user leaf commands only", () => {
   expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
 });
 
+/** Tests that collectMcpTools appends leaf notes to MCP tool description. */
 test("collectMcpTools appends leaf notes to MCP tool description", () => {
   const root = testProgram({
     key: "app",
@@ -61,6 +62,7 @@ test("collectMcpTools appends leaf notes to MCP tool description", () => {
   expect(tools[0]?.description).toBe("run — Run.\n\nUse `--json` for structured output.");
 });
 
+/** Tests that collectMcpTools appends notes after mcpTool.description override. */
 test("collectMcpTools appends notes after mcpTool.description override", () => {
   const root = testProgram({
     key: "app",
@@ -81,6 +83,7 @@ test("collectMcpTools appends notes after mcpTool.description override", () => {
   expect(tools[0]?.description).toBe("Custom MCP text.\n\nOperational hint.");
 });
 
+/** Tests that collectMcpTools resolves {argsbarg:program} in appended notes. */
 test("collectMcpTools resolves {argsbarg:program} in appended notes", () => {
   const root = testProgram({
     key: "myapp",
@@ -100,6 +103,7 @@ test("collectMcpTools resolves {argsbarg:program} in appended notes", () => {
   expect(tools[0]?.description).toContain("See `myapp docs api`.");
 });
 
+/** CliSchemaExport includes leaf outputSchema. */
 test("cliSchemaExport includes leaf outputSchema", () => {
   const root = testProgram({
     key: "app",
@@ -125,6 +129,7 @@ test("cliSchemaExport includes leaf outputSchema", () => {
   });
 });
 
+/** CliSchemaExport accepts legacy mcpTool.outputSchema. */
 test("cliSchemaExport accepts legacy mcpTool.outputSchema", () => {
   const root = testProgram({
     key: "app",
@@ -147,6 +152,7 @@ test("cliSchemaExport accepts legacy mcpTool.outputSchema", () => {
   });
 });
 
+/** Tests that outputSchema must be a JSON Schema object. */
 test("outputSchema must be a JSON Schema object", () => {
   const root = testProgram({
     key: "app",
@@ -164,6 +170,7 @@ test("outputSchema must be a JSON Schema object", () => {
   expect(() => cliValidateProgram(root)).toThrow(/outputSchema must be a JSON Schema object/);
 });
 
+/** Tests that outputSchema cannot be set on both leaf and mcpTool. */
 test("outputSchema cannot be set on both leaf and mcpTool", () => {
   const root = testProgram({
     key: "app",
@@ -190,6 +197,7 @@ test("collectMcpTools merges parent options into inputSchema", () => {
   expect(schema.required).toContain("path");
 });
 
+/** Tests that collectMcpTools includes outputSchema when set on leaf. */
 test("collectMcpTools includes outputSchema when set on leaf", () => {
   const root = testProgram({
     key: "app",
@@ -242,6 +250,7 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
+/** Tests that reserved command name configure is rejected. */
 test("reserved command name configure is rejected", () => {
   const root = testProgram({
     key: "app",
@@ -257,6 +266,7 @@ test("reserved command name configure is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: configure/);
 });
 
+/** Tests that top-level command name mcp is allowed without mcpServer. */
 test("top-level command name mcp is allowed without mcpServer", () => {
   const root = testProgram({
     key: "app",
@@ -272,6 +282,7 @@ test("top-level command name mcp is allowed without mcpServer", () => {
   expect(() => cliValidateProgram(root)).not.toThrow();
 });
 
+/** Tests that top-level command name mcp is rejected when mcpServer is enabled. */
 test("top-level command name mcp is rejected when mcpServer is enabled", () => {
   const root = testProgram({
     key: "app",
@@ -288,6 +299,7 @@ test("top-level command name mcp is rejected when mcpServer is enabled", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: mcp/);
 });
 
+/** McpServer on non-root node is rejected. */
 test("mcpServer on non-root node is rejected", () => {
   const root = {
     key: "app",
@@ -315,6 +327,7 @@ test("mcpTool on root is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
+/** McpTool on routing node is rejected. */
 test("mcpTool on routing node is rejected", () => {
   const root = testProgram({
     key: "app",
@@ -403,6 +416,7 @@ test("MCP resources/read returns schema JSON", async () => {
   expect(schema.key).toBe("nested.ts");
 });
 
+/** MCP tools/call runs stat_owner_lookup. */
 test("MCP tools/call runs stat_owner_lookup", async () => {
   const readme = join(import.meta.dir, "..", "README.md");
   const responses = await mcpRequest([
@@ -421,6 +435,7 @@ test("MCP tools/call runs stat_owner_lookup", async () => {
   expect(res.result.content[0]?.text).toContain("lookup user=test");
 });
 
+/** MCP tools/call returns structuredContent for JSON stdout. */
 test("MCP tools/call returns structuredContent for JSON stdout", async () => {
   const readme = join(import.meta.dir, "..", "README.md");
   const responses = await mcpRequest([
@@ -446,6 +461,7 @@ test("MCP tools/call returns structuredContent for JSON stdout", async () => {
   expect(JSON.parse(res.result.content[0]?.text.trim())).toEqual({ user: "test", path: readme });
 });
 
+/** MCP tools/call errors on missing required positional. */
 test("MCP tools/call errors on missing required positional", async () => {
   const responses = await mcpRequest([
     {
@@ -484,6 +500,7 @@ test("MCP resources/list includes custom resource", async () => {
   expect(uris).toContain("test://hello");
 });
 
+/** MCP resources/read returns docs topic resource body. */
 test("MCP resources/read returns docs topic resource body", async () => {
   const responses = await mcpRequest(
     [