argsbarg 5.0.2 → 5.0.3

package/src/formats.test.ts

@@ -12,7 +12,6 @@ import {
 } from "./formats.ts";
 import { CliValueFormat } from "./types.ts";
 
-/** ParseDurationMs parses minutes and hours. */
 test("parseDurationMs parses minutes and hours", () => {
   expect(parseDurationMs("30s")).toBe(30_000);
   expect(parseDurationMs("5m")).toBe(5 * 60 * 1000);
@@ -20,25 +19,21 @@ test("parseDurationMs parses minutes and hours", () => {
   expect(parseDurationMs("1d")).toBe(24 * 60 * 60 * 1000);
 });
 
-/** ParseCommaList splits and trims. */
 test("parseCommaList splits and trims", () => {
   expect(parseCommaList("a,b")).toEqual(["a", "b"]);
   expect(parseCommaList(" a , b , ")).toEqual(["a", "b"]);
 });
 
-/** ParseDate validates calendar dates. */
 test("parseDate validates calendar dates", () => {
   expect(parseDate("2026-06-22")).toBe("2026-06-22");
   expect(() => parseDate("2026-02-30")).toThrow();
 });
 
-/** ParseDateTime normalizes to UTC ISO. */
 test("parseDateTime normalizes to UTC ISO", () => {
   expect(parseDateTime("2026-06-22T15:00:00Z")).toBe("2026-06-22T15:00:00.000Z");
   expect(() => parseDateTime("2026-06-22")).toThrow();
 });
 
-/** ValidateFormatValue rejects invalid duration. */
 test("validateFormatValue rejects invalid duration", () => {
   expect(() => validateFormatValue("nope", CliValueFormat.Duration)).toThrow();
 });

package/src/headless.test.ts

@@ -12,14 +12,12 @@ import {
   wantsExplicitJson,
 } from "./headless.ts";
 
-/** WantsExplicitJson includes MCP invocation. */
 test("wantsExplicitJson includes MCP invocation", () => {
   expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
   expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);
   expect(wantsExplicitJson({ invocation: "cli" }, true)).toBe(true);
 });
 
-/** Tests that shouldRunHeadless is true for MCP and json. */
 test("shouldRunHeadless is true for MCP and json", () => {
   expect(shouldRunHeadless({ invocation: "mcp" }, false)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, true)).toBe(true);
@@ -27,7 +25,6 @@ test("shouldRunHeadless is true for MCP and json", () => {
   expect(shouldRunHeadless({ invocation: "cli" }, false, false, false)).toBe(true);
 });
 
-/** Tests that shouldRunHeadlessWithPositionals requires positionals in non-tty. */
 test("shouldRunHeadlessWithPositionals requires positionals in non-tty", () => {
   expect(shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false)).toBe(
     false,
@@ -54,7 +51,6 @@ test("shouldRunHeadlessWithYes requires yes in non-tty", () => {
   ).toBe(true);
 });
 
-/** Tests that formatDryRunMessage prefixes dry-run output. */
 test("formatDryRunMessage prefixes dry-run output", () => {
   expect(formatDryRunMessage("hello", false)).toBe("hello");
   expect(formatDryRunMessage("hello", true)).toBe("[DRY RUN] hello");

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

@@ -59,13 +59,11 @@ 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) ?? [];
@@ -73,27 +71,23 @@ 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) ?? [];
@@ -103,7 +97,6 @@ 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"]);
@@ -112,7 +105,6 @@ describe("hidden commands and options", () => {
 
 /** 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");
@@ -121,7 +113,6 @@ 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");
@@ -131,7 +122,6 @@ 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");
@@ -145,7 +135,6 @@ describe("mcp bundle", () => {
     expect((manifest.compatibility as { platforms: string[] }).platforms).toEqual(["darwin"]);
   });
 
-  /** DefaultMcpBundlePaths. */
   test("defaultMcpBundlePaths", () => {
     const cwd = "/tmp/work";
     const paths = defaultMcpBundlePaths(hiddenFixture, cwd);
@@ -241,7 +230,6 @@ 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

@@ -36,13 +36,11 @@ afterEach(() => {
 
 /** 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");
@@ -51,7 +49,6 @@ 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");
@@ -61,7 +58,6 @@ 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");
@@ -107,7 +103,6 @@ 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

@@ -5,27 +5,22 @@ 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

@@ -16,12 +16,10 @@ const base: CliProgram = {
 
 /** 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,
@@ -31,7 +29,6 @@ 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,
@@ -44,7 +41,6 @@ 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,
@@ -56,7 +52,6 @@ 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-opencode.test.ts

@@ -47,7 +47,6 @@ afterEach(() => {
 
 /** 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 });
@@ -56,7 +55,6 @@ 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(
@@ -64,7 +62,6 @@ describe("opencode mcp config", () => {
     );
   });
 
-  /** MergeOpenCodeMcpConfig writes mcp block. */
   test("mergeOpenCodeMcpConfig writes mcp block", () => {
     const path = resolveOpenCodeConfigPathForInstall(home);
     mkdirSync(opencodeConfigDir(home), { recursive: true });
@@ -95,7 +92,6 @@ 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/targets.test.ts

@@ -11,12 +11,10 @@ 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",
@@ -24,7 +22,6 @@ describe("normalizeInstallRawOpts", () => {
     });
   });
 
-  /** Configure-only install unchanged. */
   test("configure-only install unchanged", () => {
     expect(normalizeInstallRawOpts({ configure: "1" })).toEqual({ configure: "1" });
   });
@@ -32,12 +29,10 @@ describe("normalizeInstallRawOpts", () => {
 
 /** 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");
   });
@@ -45,14 +40,12 @@ describe("resolveAgentIntegration", () => {
 
 /** 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);
@@ -60,7 +53,6 @@ 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);
@@ -69,7 +61,6 @@ 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);
@@ -77,7 +68,6 @@ 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 },

package/src/invoke.test.ts

@@ -91,7 +91,6 @@ 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);
@@ -101,7 +100,6 @@ 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);
@@ -111,7 +109,6 @@ 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);
@@ -121,7 +118,6 @@ 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);
@@ -131,7 +127,6 @@ 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);
@@ -140,7 +135,6 @@ 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);
@@ -172,7 +166,6 @@ 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;

package/src/mcp/claude.test.ts

@@ -35,12 +35,10 @@ const configFixture: CliProgram = {
 
 /** 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");
@@ -50,7 +48,6 @@ 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> };
@@ -59,7 +56,6 @@ 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);

package/src/mcp/env.test.ts

@@ -33,7 +33,6 @@ 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";
@@ -78,25 +77,21 @@ 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/zip.test.ts

@@ -9,7 +9,6 @@ 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");

package/src/mcp.integration.test.ts

@@ -17,12 +17,10 @@ import { cliSchemaExport } from "./schema.ts";
 import { mcpRequest, nestedMcpFixture, testProgram } from "./test-fixtures.ts";
 import { cliValidateProgram } from "./validate.ts";
 
-/** Tests that sanitizeToolSegment normalizes dotted app keys. */
 test("sanitizeToolSegment normalizes dotted app keys", () => {
   expect(sanitizeToolSegment("minimal.ts")).toBe("minimal_ts");
 });
 
-/** McpToolDescription formats CLI path and root-leaf prefix. */
 test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
   expect(mcpToolDescription(["stat", "owner", "lookup"], "nested.ts", "Resolve owner info.")).toBe(
     "stat owner lookup — Resolve owner info.",
@@ -31,7 +29,6 @@ test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
   expect(mcpToolDescription([], "helloapp", "Tiny demo.")).toBe("helloapp — Tiny demo.");
 });
 
-/** Tests that collectMcpTools lists user leaf commands only. */
 test("collectMcpTools lists user leaf commands only", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const names = tools.map((t) => t.name);
@@ -192,7 +189,6 @@ test("outputSchema cannot be set on both leaf and mcpTool", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Set outputSchema on the leaf only/);
 });
 
-/** Tests that collectMcpTools merges parent options into inputSchema. */
 test("collectMcpTools merges parent options into inputSchema", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -230,14 +226,12 @@ test("collectMcpTools includes outputSchema when set on leaf", () => {
   });
 });
 
-/** Tests that collectMcpTools omits outputSchema when leaf has none. */
 test("collectMcpTools omits outputSchema when leaf has none", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
   expect(lookup.outputSchema).toBeUndefined();
 });
 
-/** McpToolCallToArgv builds nested lookup argv. */
 test("mcpToolCallToArgv builds nested lookup argv", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -249,7 +243,6 @@ test("mcpToolCallToArgv builds nested lookup argv", () => {
   expect(argv).toEqual(["stat", "owner", "lookup", "--json", "--user-name", "alice", "./x"]);
 });
 
-/** McpToolCallToArgv expands varargs positionals. */
 test("mcpToolCallToArgv expands varargs positionals", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const read = tools.find((t) => t.name === "read")!;
@@ -324,7 +317,6 @@ test("mcpServer on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpServer is only supported on the program root/);
 });
 
-/** McpTool on root is rejected. */
 test("mcpTool on root is rejected", () => {
   const root = testProgram({
     key: "app",
@@ -358,7 +350,6 @@ test("mcpTool on routing node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
-/** BuildToolCallSuccess returns stdout only. */
 test("buildToolCallSuccess returns stdout only", () => {
   const result = buildToolCallSuccess("hello\n", "");
   expect(result.isError).toBe(false);
@@ -366,7 +357,6 @@ test("buildToolCallSuccess returns stdout only", () => {
   expect(result.structuredContent).toBeUndefined();
 });
 
-/** BuildToolCallSuccess adds stderr as second content block. */
 test("buildToolCallSuccess adds stderr as second content block", () => {
   const result = buildToolCallSuccess("out\n", "warn\n");
   expect(result.content).toEqual([
@@ -376,7 +366,6 @@ test("buildToolCallSuccess adds stderr as second content block", () => {
   expect(result.structuredContent).toBeUndefined();
 });
 
-/** BuildToolCallSuccess stderr-only still includes stdout slot. */
 test("buildToolCallSuccess stderr-only still includes stdout slot", () => {
   const result = buildToolCallSuccess("", "warn\n");
   expect(result.content).toEqual([
@@ -385,26 +374,22 @@ test("buildToolCallSuccess stderr-only still includes stdout slot", () => {
   ]);
 });
 
-/** BuildToolCallSuccess parses JSON structuredContent. */
 test("buildToolCallSuccess parses JSON structuredContent", () => {
   const result = buildToolCallSuccess('{"a":1}\n', "");
   expect(result.structuredContent).toEqual({ a: 1 });
   expect(result.content[0]?.text).toBe('{"a":1}\n');
 });
 
-/** BuildToolCallSuccess skips structuredContent for plain text. */
 test("buildToolCallSuccess skips structuredContent for plain text", () => {
   const result = buildToolCallSuccess("lookup user=x\n", "");
   expect(result.structuredContent).toBeUndefined();
 });
 
-/** BuildToolCallSuccess parses JSON primitives. */
 test("buildToolCallSuccess parses JSON primitives", () => {
   const result = buildToolCallSuccess("true\n", "");
   expect(result.structuredContent).toBe(true);
 });
 
-/** MCP initialize returns tools and resources capabilities. */
 test("MCP initialize returns tools and resources capabilities", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }]);
   const res = responses.get(1) as { result: { capabilities: Record<string, unknown> } };
@@ -412,7 +397,6 @@ test("MCP initialize returns tools and resources capabilities", async () => {
   expect(res.result.capabilities.resources).toBeDefined();
 });
 
-/** MCP tools/list includes stat_owner_lookup. */
 test("MCP tools/list includes stat_owner_lookup", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }]);
   const res = responses.get(2) as {
@@ -423,7 +407,6 @@ test("MCP tools/list includes stat_owner_lookup", async () => {
   expect(lookup?.inputSchema.required).toContain("path");
 });
 
-/** MCP resources/read returns schema JSON. */
 test("MCP resources/read returns schema JSON", async () => {
   const responses = await mcpRequest([
     { jsonrpc: "2.0", id: 3, method: "resources/read", params: { uri: "nested_ts://schema" } },
@@ -493,21 +476,18 @@ test("MCP tools/call errors on missing required positional", async () => {
   expect(res.result.content[0]?.text).toContain("Missing argument: path");
 });
 
-/** MCP ping returns empty result. */
 test("MCP ping returns empty result", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 99, method: "ping", params: {} }]);
   const res = responses.get(99) as { result: Record<string, never> };
   expect(res.result).toEqual({});
 });
 
-/** Tests that minimal.ts mcp without opt-in fails. */
 test("minimal.ts mcp without opt-in fails", async () => {
   const { stderr, exitCode } = await $`bun run examples/minimal.ts mcp`.nothrow().quiet();
   expect(exitCode).toBe(1);
   expect(stderr.toString()).toContain("MCP is not available");
 });
 
-/** MCP resources/list includes custom resource. */
 test("MCP resources/list includes custom resource", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 10, method: "resources/list", params: {} }],
@@ -537,7 +517,6 @@ test("MCP resources/read returns docs topic resource body", async () => {
   expect(res.result.contents[0]?.text).toBe("# MCP test readme\n");
 });
 
-/** MCP resources/read returns custom resource body. */
 test("MCP resources/read returns custom resource body", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 11, method: "resources/read", params: { uri: "test://hello" } }],
@@ -547,7 +526,6 @@ test("MCP resources/read returns custom resource body", async () => {
   expect(res.result.contents[0]?.text).toBe("hello resource");
 });
 
-/** MCP resources/read unknown URI returns error. */
 test("MCP resources/read unknown URI returns error", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 12, method: "resources/read", params: { uri: "missing://nope" } }],