argsbarg 5.0.1 → 5.0.2

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,12 +57,15 @@ const hiddenFixture: CliProgram = {
   ],
 };
 
+/** Tests for hidden commands and options. */
 describe("hidden commands and options", () => {
+  /** Parse root includes hidden commands. */
   test("parse root includes hidden commands", () => {
     const parse = cliParseRoot(hiddenFixture);
     expect(parse.commands?.map((c) => c.key)).toContain("secret");
   });
 
+  /** Presentation root omits hidden commands. */
   test("presentation root omits hidden commands", () => {
     const presentation = cliPresentationRoot(hiddenFixture);
     const keys = presentation.commands?.map((c) => c.key) ?? [];
@@ -66,23 +73,27 @@ describe("hidden commands and options", () => {
     expect(keys).not.toContain("secret");
   });
 
+  /** Root help omits hidden commands. */
   test("root help omits hidden commands", () => {
     const help = cliHelpRender(cliParseRoot(hiddenFixture), [], false);
     expect(help).toContain("public");
     expect(help).not.toContain("secret");
   });
 
+  /** Hidden command -h still works. */
   test("hidden command -h still works", () => {
     const help = cliHelpRender(cliParseRoot(hiddenFixture), ["secret"], false);
     expect(help).toContain("Hidden command.");
   });
 
+  /** Tests that help omits hidden options. */
   test("help omits hidden options", () => {
     const help = cliHelpRender(cliParseRoot(hiddenFixture), ["flags"], false);
     expect(help).toContain("--visible");
     expect(help).not.toContain("secret-flag");
   });
 
+  /** Tests that schema export omits hidden nodes and options. */
   test("schema export omits hidden nodes and options", () => {
     const schema = cliSchemaExport(hiddenFixture);
     const keys = schema.commands?.map((c) => c.key) ?? [];
@@ -92,13 +103,16 @@ describe("hidden commands and options", () => {
     expect(flags?.options?.map((o) => o.name)).toEqual(["visible"]);
   });
 
+  /** MCP tools omit hidden commands. */
   test("MCP tools omit hidden commands", () => {
     const tools = collectMcpTools(hiddenFixture);
     expect(tools.map((t) => t.name)).toEqual(["public", "flags"]);
   });
 });
 
+/** Tests for mcp router. */
 describe("mcp router", () => {
+  /** Presentation exposes mcp bundle but not hidden serve. */
   test("presentation exposes mcp bundle but not hidden serve", () => {
     const builtins = exportPresentationBuiltins(hiddenFixture);
     const mcp = builtins.find((b) => b.key === "mcp");
@@ -107,6 +121,7 @@ describe("mcp router", () => {
     expect(mcp?.fallbackCommand).toBe("serve");
   });
 
+  /** Mcp help lists bundle. */
   test("mcp help lists bundle", () => {
     const help = cliHelpRender(cliParseRoot(hiddenFixture), ["mcp"], false);
     expect(help).toContain("bundle");
@@ -114,7 +129,9 @@ describe("mcp router", () => {
   });
 });
 
+/** Tests for mcp bundle. */
 describe("mcp bundle", () => {
+  /** Tests that generateMcpManifest uses mcpServerId and binary entry. */
   test("generateMcpManifest uses mcpServerId and binary entry", () => {
     const manifest = generateMcpManifest(hiddenFixture, "myapp");
     expect(manifest.name).toBe("myapp");
@@ -128,6 +145,7 @@ describe("mcp bundle", () => {
     expect((manifest.compatibility as { platforms: string[] }).platforms).toEqual(["darwin"]);
   });
 
+  /** DefaultMcpBundlePaths. */
   test("defaultMcpBundlePaths", () => {
     const cwd = "/tmp/work";
     const paths = defaultMcpBundlePaths(hiddenFixture, cwd);
@@ -135,6 +153,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 +174,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 +208,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[] = [];
@@ -220,6 +241,7 @@ describe("mcp bundle", () => {
     }
   });
 
+  /** RunMcpBundle errors when no bundle flags enabled. */
   test("runMcpBundle errors when no bundle flags enabled", () => {
     const fixture: CliProgram = {
       ...hiddenFixture,

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,12 +34,15 @@ afterEach(() => {
   rmSync(tmp, { recursive: true, force: true });
 });
 
+/** Tests for isExternallyManagedBinary. */
 describe("isExternallyManagedBinary", () => {
+  /** Tests that false when command is not on PATH. */
   test("false when command is not on PATH", () => {
     process.env.PATH = tmp;
     expect(isExternallyManagedBinary("placementapp-not-on-path")).toBe(false);
   });
 
+  /** Tests that true when PATH resolves to execPath. */
   test("true when PATH resolves to execPath", () => {
     const bin = join(tmp, "placementapp");
     writeFileSync(bin, "#!/bin/sh\n", "utf8");
@@ -44,6 +51,7 @@ describe("isExternallyManagedBinary", () => {
     expect(isExternallyManagedBinary("placementapp", bin)).toBe(true);
   });
 
+  /** Tests that true when PATH entry is a symlink to execPath. */
   test("true when PATH entry is a symlink to execPath", () => {
     const bin = join(tmp, "placementapp");
     const target = join(tmp, "real-binary");
@@ -53,6 +61,7 @@ describe("isExternallyManagedBinary", () => {
     expect(isExternallyManagedBinary("placementapp", target)).toBe(true);
   });
 
+  /** Tests that false when PATH points at a different binary. */
   test("false when PATH points at a different binary", () => {
     const bin = join(tmp, "placementapp");
     const other = join(tmp, "other");
@@ -63,7 +72,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 +89,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,7 +105,9 @@ describe("isAppInstalled", () => {
   });
 });
 
+/** Tests for resolvePathCommand. */
 describe("resolvePathCommand", () => {
+  /** Tests that returns undefined when missing. */
   test("returns undefined when missing", () => {
     process.env.PATH = tmp;
     expect(resolvePathCommand("missing-cmd")).toBeUndefined();

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

@@ -1,22 +1,31 @@
+/*
+Tests for install/gh-release-update module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { isAlreadyCurrent, parseReleaseTag } from "./gh-release-update.ts";
 
+/** ParseReleaseTag strips leading v. */
 test("parseReleaseTag strips leading v", () => {
   expect(parseReleaseTag("v1.4.3")).toBe("1.4.3");
 });
 
+/** ParseReleaseTag leaves bare semver unchanged. */
 test("parseReleaseTag leaves bare semver unchanged", () => {
   expect(parseReleaseTag("1.4.3")).toBe("1.4.3");
 });
 
+/** ParseReleaseTag throws on empty tag. */
 test("parseReleaseTag throws on empty tag", () => {
   expect(() => parseReleaseTag("")).toThrow("Release tag is empty");
 });
 
+/** Tests that isAlreadyCurrent returns true when versions match. */
 test("isAlreadyCurrent returns true when versions match", () => {
   expect(isAlreadyCurrent("1.4.3", "1.4.3")).toBe(true);
 });
 
+/** Tests that isAlreadyCurrent returns false when versions differ. */
 test("isAlreadyCurrent returns false when versions differ", () => {
   expect(isAlreadyCurrent("1.4.2", "1.4.3")).toBe(false);
 });

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,11 +14,14 @@ const base: CliProgram = {
   handler: () => {},
 };
 
+/** Tests for validateConfigureConfig. */
 describe("validateConfigureConfig", () => {
+  /** Tests that accepts empty install config. */
   test("accepts empty install config", () => {
     expect(() => cliValidateProgram(base)).not.toThrow();
   });
 
+  /** Rejects removed allSkills shorthand. */
   test("rejects removed allSkills shorthand", () => {
     const program = {
       ...base,
@@ -24,6 +31,7 @@ describe("validateConfigureConfig", () => {
     expect(() => cliValidateProgram(program)).toThrow(/allSkills/);
   });
 
+  /** Rejects both sides of pair without both integration. */
   test("rejects both sides of pair without both integration", () => {
     const program: CliProgram = {
       ...base,
@@ -36,6 +44,7 @@ describe("validateConfigureConfig", () => {
     expect(() => cliValidateProgram(program)).toThrow(/both/);
   });
 
+  /** Rejects explicit MCP target in skill integration mode. */
   test("rejects explicit MCP target in skill integration mode", () => {
     const program: CliProgram = {
       ...base,
@@ -47,6 +56,7 @@ describe("validateConfigureConfig", () => {
     expect(() => cliValidateProgram(program)).toThrow(/cursorMcp/);
   });
 
+  /** Allows explicit pair targets with both integration. */
   test("allows explicit pair targets with both integration", () => {
     const program: CliProgram = {
       ...base,

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,7 +45,9 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for opencode mcp config. */
 describe("opencode mcp config", () => {
+  /** ResolveOpenCodeConfigPathForInstall prefers existing file. */
   test("resolveOpenCodeConfigPathForInstall prefers existing file", () => {
     const dir = opencodeConfigDir(home);
     mkdirSync(dir, { recursive: true });
@@ -50,6 +56,7 @@ describe("opencode mcp config", () => {
     expect(resolveOpenCodeConfigPathForInstall(home)).toBe(existing);
   });
 
+  /** ResolveOpenCodeConfigPathForInstall defaults to config.json. */
   test("resolveOpenCodeConfigPathForInstall defaults to config.json", () => {
     mkdirSync(opencodeConfigDir(home), { recursive: true });
     expect(resolveOpenCodeConfigPathForInstall(home)).toBe(
@@ -57,6 +64,7 @@ describe("opencode mcp config", () => {
     );
   });
 
+  /** MergeOpenCodeMcpConfig writes mcp block. */
   test("mergeOpenCodeMcpConfig writes mcp block", () => {
     const path = resolveOpenCodeConfigPathForInstall(home);
     mkdirSync(opencodeConfigDir(home), { recursive: true });
@@ -70,6 +78,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 });
@@ -86,6 +95,7 @@ describe("opencode mcp config", () => {
     expect(detectOpenCodeMcpConfigPath(home, "testapp")).toBe(path);
   });
 
+  /** RemoveOpenCodeMcpConfig deletes server entry. */
   test("removeOpenCodeMcpConfig deletes server entry", () => {
     const path = resolveOpenCodeConfigPathForInstall(home);
     mkdirSync(opencodeConfigDir(home), { 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,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,6 +86,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 +113,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",
@@ -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 {