argsbarg 5.0.1 → 5.0.2

package/src/configure/configure.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for configure/configure module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -42,30 +46,37 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for configure opts. */
 describe("configure opts", () => {
+  /** Validate rejects multiple modes. */
   test("validate rejects multiple modes", () => {
     const opts = parseConfigureOpts({ sync: "1", status: "1" });
     expect(validateConfigureOpts(opts)).toContain("only one");
   });
 
+  /** Sync requires --yes. */
   test("sync requires --yes", () => {
     const opts = parseConfigureOpts({ sync: "1" });
     expect(validateConfigureOpts(opts)).toContain("--yes");
   });
 
+  /** Remove-all requires --yes. */
   test("remove-all requires --yes", () => {
     const opts = parseConfigureOpts({ "remove-all": "1" });
     expect(validateConfigureOpts(opts)).toContain("--yes");
   });
 });
 
+/** Tests for install paths. */
 describe("install paths", () => {
+  /** ResolveInstallPaths includes skill and mcp paths. */
   test("resolveInstallPaths includes skill and mcp paths", () => {
     const paths = resolveInstallPaths(fixture);
     expect(paths.cursorSkillDir).toContain(".cursor/skills");
     expect(paths.cursorMcpPath).toContain("mcp.json");
   });
 
+  /** Claude desktop mcp path on darwin. */
   test("claude desktop mcp path on darwin", () => {
     const prev = process.platform;
     Object.defineProperty(process, "platform", { value: "darwin" });
@@ -79,7 +90,9 @@ describe("install paths", () => {
   });
 });
 
+/** Tests for detect installed. */
 describe("detect installed", () => {
+  /** Detects cursor mcp when configured. */
   test("detects cursor mcp when configured", () => {
     const paths = resolveInstallPaths(fixture);
     mkdirSync(join(home, ".cursor"), { recursive: true });
@@ -95,7 +108,9 @@ describe("detect installed", () => {
   });
 });
 
+/** Tests for sync plan. */
 describe("sync plan", () => {
+  /** BuildUpdatePlan greenfield includes agent targets. */
   test("buildUpdatePlan greenfield includes agent targets", () => {
     const paths = resolveInstallPaths(fixture);
     const plan = buildUpdatePlan(fixture, paths, parseInstallOpts({ reinstall: "1", yes: "1" }));
@@ -103,6 +118,7 @@ describe("sync plan", () => {
     expect(plan.some((a) => a.kind === "app")).toBe(false);
   });
 
+  /** BuildInstallPlan --all omits app self-install. */
   test("buildInstallPlan --all omits app self-install", () => {
     const paths = resolveInstallPaths(fixture);
     const plan = buildInstallPlan(fixture, paths, parseInstallOpts({ all: "1" }));
@@ -110,6 +126,7 @@ describe("sync plan", () => {
     expect(plan.some((a) => a.kind.endsWith("-mcp"))).toBe(true);
   });
 
+  /** BuildInstallPlan respects configure.agentIntegration skill. */
   test("buildInstallPlan respects configure.agentIntegration skill", () => {
     const skillApp: CliProgram = {
       ...fixture,
@@ -123,7 +140,9 @@ describe("sync plan", () => {
   });
 });
 
+/** Tests for remove plan. */
 describe("remove plan", () => {
+  /** BuildUninstallPlan --all with nothing installed is empty. */
   test("buildUninstallPlan --all with nothing installed is empty", () => {
     const paths = resolveInstallPaths(fixture);
     const plan = buildUninstallPlan(fixture, paths, parseInstallOpts({ uninstall: "1", all: "1" }));
@@ -131,7 +150,9 @@ describe("remove plan", () => {
   });
 });
 
+/** Tests for app config wizard. */
 describe("app config wizard", () => {
+  /** Tests that appConfigHasEntries when entries exist. */
   test("appConfigHasEntries when entries exist", () => {
     expect(
       appConfigHasEntries({
@@ -141,6 +162,7 @@ describe("app config wizard", () => {
     ).toBe(true);
   });
 
+  /** Tests that appConfigHasEntries false for empty entries or missing appConfig. */
   test("appConfigHasEntries false for empty entries or missing appConfig", () => {
     expect(appConfigHasEntries({ ...fixture, appConfig: { entries: {} } })).toBe(false);
     expect(appConfigHasEntries(fixture)).toBe(false);

package/src/configure/index.ts

@@ -1,3 +1,7 @@
+/*
+Interactive and automated `configure` command orchestration (agent artifacts and app config).
+*/
+
 import { resolveCapabilities } from "../capabilities.ts";
 import { displayAppConfigPath, runConfigure } from "../config/bootstrap.ts";
 import { resolveInstallPaths } from "../install/paths.ts";
@@ -36,6 +40,7 @@ export function appConfigHasEntries(program: CliProgram): boolean {
   return !!entries && Object.keys(entries).length > 0;
 }
 
+/** Parsed flags for the top-level `configure` built-in. */
 export interface ConfigureOpts {
   sync?: boolean;
   removeAll?: boolean;
@@ -46,6 +51,7 @@ export interface ConfigureOpts {
   json?: boolean;
 }
 
+/** Maps raw argv flags into {@link ConfigureOpts}. */
 export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
   const flag = (name: string) => raw[name] === "1";
   return {
@@ -59,6 +65,7 @@ export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
   };
 }
 
+/** Returns an error message when configure flags are inconsistent; otherwise null. */
 export function validateConfigureOpts(opts: ConfigureOpts): string | null {
   const flags = [opts.sync, opts.removeAll, opts.removeConfig, opts.status].filter(Boolean);
   if (flags.length > 1) {
@@ -73,6 +80,7 @@ export function validateConfigureOpts(opts: ConfigureOpts): string | null {
   return null;
 }
 
+/** Adapts configure flags to internal install-plan option shape. */
 function configureToInstallOpts(opts: ConfigureOpts): InstallOpts {
   if (opts.status) {
     return { status: true, yes: opts.yes, dry: opts.dry, json: opts.json };
@@ -89,6 +97,7 @@ function configureToInstallOpts(opts: ConfigureOpts): InstallOpts {
   return { dry: opts.dry, json: opts.json };
 }
 
+/** Installs a skill target and returns changed paths. */
 function runSkillAction(root: CliProgram, kind: InstallActionKind, opts: InstallOpts): string[] {
   const target = skillTargetFromActionKind(kind);
   if (!target) return [];
@@ -99,6 +108,7 @@ function runSkillAction(root: CliProgram, kind: InstallActionKind, opts: Install
   });
 }
 
+/** Runs install or uninstall actions and collects changed paths. */
 function executePlan(
   root: CliProgram,
   actions: Array<InstallAction | UninstallAction>,
@@ -130,6 +140,7 @@ function executePlan(
   return changed;
 }
 
+/** Builds plan context limited to a single artifact key. */
 function buildSingleTargetContext(
   root: CliProgram,
   paths: ReturnType<typeof resolveInstallPaths>,
@@ -147,6 +158,7 @@ function buildSingleTargetContext(
   };
 }
 
+/** Resolves install or uninstall actions for one artifact target. */
 function actionsForTarget(
   root: CliProgram,
   paths: ReturnType<typeof resolveInstallPaths>,
@@ -164,6 +176,7 @@ function actionsForTarget(
   return target.planUninstall(ctx);
 }
 
+/** Walks enabled targets with per-target prompts (TTY required). */
 async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): Promise<string[]> {
   if (!process.stdin.isTTY) {
     throw new Error("Interactive configure requires a TTY. Use flags such as --sync --yes.");
@@ -218,6 +231,7 @@ async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): P
   return changed;
 }
 
+/** Runs sync, remove, or status modes without per-target prompts. */
 async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Promise<string[]> {
   const installOpts = configureToInstallOpts(opts);
   const paths = resolveInstallPaths(root);

package/src/configure/prompt.ts

@@ -1,6 +1,11 @@
+/*
+TTY prompts for per-target install, skip, or uninstall during interactive `configure`.
+*/
+
 import { readSync } from "node:fs";
 import type { CliInstallArtifactKey } from "../install/target-types.ts";
 
+/** Human-readable labels for each install artifact key in interactive prompts. */
 const LABELS: Record<CliInstallArtifactKey, string> = {
   app: "App binary",
   cursorSkill: "Cursor skill",
@@ -18,10 +23,12 @@ const LABELS: Record<CliInstallArtifactKey, string> = {
   configure: "App config",
 };
 
+/** Returns the prompt label for an install artifact key. */
 export function artifactPromptLabel(key: CliInstallArtifactKey): string {
   return LABELS[key];
 }
 
+/** User choice from a per-target Y/n or y/N prompt. */
 export type TargetPromptAction = "install" | "skip" | "uninstall";
 
 /** Prompt per target: Y/n when not installed, y/N when installed. */

package/src/docs/api-guide.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/api-guide module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { cliSchemaExport } from "../schema.ts";
 import type { CliProgram } from "../types.ts";
@@ -45,6 +49,7 @@ const nestedFixture: CliProgram = {
   ],
 };
 
+/** Tests that generateApiGuideBody matches command section of full API guide. */
 test("generateApiGuideBody matches command section of full API guide", () => {
   const body = generateApiGuideBody(nestedFixture);
   const full = generateApiGuide(nestedFixture);
@@ -53,6 +58,7 @@ test("generateApiGuideBody matches command section of full API guide", () => {
   expect(body).not.toContain("CLI API reference");
 });
 
+/** Tests that generateApiGuide covers the same command keys as cliSchemaExport. */
 test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   const md = generateApiGuide(nestedFixture);
   const schema = cliSchemaExport(nestedFixture);
@@ -62,6 +68,7 @@ test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
 });
 
+/** Tests that generateApiGuide resolves program key in install notes. */
 test("generateApiGuide resolves program key in install notes", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -75,6 +82,7 @@ test("generateApiGuide resolves program key in install notes", () => {
   expect(md).not.toContain("Upgrade to latest release");
 });
 
+/** Tests that generateApiGuide mentions Homebrew upgrade. */
 test("generateApiGuide mentions Homebrew upgrade", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -87,6 +95,7 @@ test("generateApiGuide mentions Homebrew upgrade", () => {
   expect(md).not.toContain("install --update");
 });
 
+/** Tests that generateApiGuide resolves {argsbarg:program} in consumer notes. */
 test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -105,6 +114,7 @@ test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   expect(md).toContain("Invoke `myapp run`.");
 });
 
+/** Tests that generateApiGuide and cliSchemaExport include leaf outputSchema. */
 test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
   const fixture: CliProgram = {
     key: "myapp",

package/src/docs/docs.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/docs module behavior.
+*/
+
 import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -49,6 +53,7 @@ function docsFixture(mcp = true): CliProgram {
   };
 }
 
+/** Docs reserved when enabled. */
 test("docs reserved when enabled", () => {
   const root: CliProgram = {
     ...docsFixture(),
@@ -63,6 +68,7 @@ test("docs reserved when enabled", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: docs/);
 });
 
+/** Docs rejects reserved topic keys. */
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
   const docs = root.docs;
@@ -77,22 +83,26 @@ test("docs rejects reserved topic keys", () => {
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
+/** DocsEffectiveDefaultTopic uses first topic key. */
 test("docsEffectiveDefaultTopic uses first topic key", () => {
   expect(docsEffectiveDefaultTopic(docsFixture().docs!)).toBe("readme");
 });
 
+/** Bare docs prints first topic via Cli.invoke. */
 test("bare docs prints first topic via Cli.invoke", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
 
+/** Docs readme prints bundled text. */
 test("docs readme prints bundled text", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
 
+/** Docs defaultTopic override. */
 test("docs defaultTopic override", async () => {
   const root = docsFixture();
   root.docs!.defaultTopic = "arch";
@@ -100,6 +110,7 @@ test("docs defaultTopic override", async () => {
   expect(result.stdout).toContain("Architecture");
 });
 
+/** Docs mcp when MCP enabled. */
 test("docs mcp when MCP enabled", async () => {
   const result = await new Cli(docsFixture(true)).invoke(["docs", "mcp"]);
   expect(result.exitCode).toBe(0);
@@ -109,11 +120,13 @@ test("docs mcp when MCP enabled", async () => {
   expect(result.stdout).toContain("configure --sync --yes");
 });
 
+/** Docs rejects unknown subcommand. */
 test("docs rejects unknown subcommand", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "all"]);
   expect(result.exitCode).not.toBe(0);
 });
 
+/** Docs mcp absent from router when MCP disabled. */
 test("docs mcp absent from router when MCP disabled", async () => {
   const root = docsFixture(false);
   const presentation = cliPresentationRoot(root);
@@ -126,6 +139,7 @@ test("docs mcp absent from router when MCP disabled", async () => {
   expect(result.exitCode).not.toBe(0);
 });
 
+/** Presentation includes docs subtree. */
 test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -135,6 +149,7 @@ test("presentation includes docs subtree", () => {
   ).toBe(true);
 });
 
+/** Docs schema prints JSON. */
 test("docs schema prints JSON", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "schema"]);
   expect(result.exitCode).toBe(0);
@@ -143,6 +158,7 @@ test("docs schema prints JSON", async () => {
   expect(schema.commands.some((c: { key: string }) => c.key === "run")).toBe(true);
 });
 
+/** Docs api prints markdown reference. */
 test("docs api prints markdown reference", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "api"]);
   expect(result.exitCode).toBe(0);
@@ -152,6 +168,7 @@ test("docs api prints markdown reference", async () => {
   expect(result.stdout).toContain("myapp docs schema");
 });
 
+/** Tests that skipsRequiredAppConfigExit includes docs and config builtins. */
 test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
   const program = {
     ...docsFixture(),
@@ -165,6 +182,7 @@ test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
   expect(skipsRequiredAppConfigExit(["run"], caps)).toBe(false);
 });
 
+/** Docs skill prints Cursor SKILL.md. */
 test("docs skill prints Cursor SKILL.md", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "skill"]);
   expect(result.exitCode).toBe(0);
@@ -176,6 +194,7 @@ test("docs skill prints Cursor SKILL.md", async () => {
   expect(result.stdout).not.toContain("mcp.json");
 });
 
+/** Docs skill help recommends configure. */
 test("docs skill help recommends configure", async () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -190,6 +209,7 @@ test("docs skill help recommends configure", async () => {
   }
 });
 
+/** Presentation includes docs schema and skill. */
 test("presentation includes docs schema and skill", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -201,6 +221,7 @@ test("presentation includes docs schema and skill", () => {
   }
 });
 
+/** Completions offer docs subcommands. */
 test("completions offer docs subcommands", () => {
   const bash = completionBashScript(cliPresentationRoot(docsFixture()));
   expect(bash).toContain("docs) echo");
@@ -210,6 +231,7 @@ test("completions offer docs subcommands", () => {
   expect(bash).toContain("skill) echo");
 });
 
+/** Tests that generateMcpGuide includes schema URI and configure sync. */
 test("generateMcpGuide includes schema URI and configure sync", () => {
   const guide = generateMcpGuide(docsFixture(true));
   expect(guide).toContain("myapp://schema");
@@ -223,6 +245,7 @@ test("generateMcpGuide includes schema URI and configure sync", () => {
   expect(guide).toContain("ChatGPT");
 });
 
+/** Docs --save writes topic file. */
 test("docs --save writes topic file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -232,6 +255,7 @@ test("docs --save writes topic file", async () => {
   expect(text).not.toContain("Generated by");
 });
 
+/** Docs api --save prepends generated hint. */
 test("docs api --save prepends generated hint", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "api", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -242,6 +266,7 @@ test("docs api --save prepends generated hint", async () => {
   expect(text).toContain("CLI API reference");
 });
 
+/** Docs skill --save keeps frontmatter first. */
 test("docs skill --save keeps frontmatter first", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "skill", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -252,6 +277,7 @@ test("docs skill --save keeps frontmatter first", async () => {
   expect(text.indexOf(hint)).toBeGreaterThan(text.indexOf("---\n", 4));
 });
 
+/** Docs schema --save writes JSON file. */
 test("docs schema --save writes JSON file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "schema", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -262,6 +288,7 @@ test("docs schema --save writes JSON file", async () => {
   expect(schema.key).toBe("myapp");
 });
 
+/** Tests that saveDocsTopic returns relative path. */
 test("saveDocsTopic returns relative path", () => {
   const path = saveDocsTopic(docsFixture(), "api");
   expect(path).toBe("docs/api.md");

package/src/docs/mcp-resources.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/mcp-resources module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import {
@@ -30,14 +34,17 @@ function fixture(opts?: { docs?: boolean; mcp?: boolean }): CliProgram {
   };
 }
 
+/** DefaultDocsTopicResourceUri. */
 test("defaultDocsTopicResourceUri", () => {
   expect(defaultDocsTopicResourceUri("my_app", "readme")).toBe("my_app://docs/readme");
 });
 
+/** ResolveDocsTopicResourceUri sanitizes program key. */
 test("resolveDocsTopicResourceUri sanitizes program key", () => {
   expect(resolveDocsTopicResourceUri(fixture(), "readme")).toBe("my_app://docs/readme");
 });
 
+/** DocsMcpResources when docs and MCP enabled. */
 test("docsMcpResources when docs and MCP enabled", () => {
   const resources = docsMcpResources(fixture());
   expect(resources.map((r) => r.uri)).toEqual(["my_app://docs/readme", "my_app://docs/arch"]);
@@ -47,14 +54,17 @@ test("docsMcpResources when docs and MCP enabled", () => {
   expect(resources[0]?.load()).toBe("# Readme\n");
 });
 
+/** DocsMcpResources empty when docs disabled. */
 test("docsMcpResources empty when docs disabled", () => {
   expect(docsMcpResources(fixture({ docs: false }))).toEqual([]);
 });
 
+/** DocsMcpResources empty when MCP disabled. */
 test("docsMcpResources empty when MCP disabled", () => {
   expect(docsMcpResources(fixture({ mcp: false }))).toEqual([]);
 });
 
+/** Tests that reservedDocsTopicResourceUris matches docsMcpResources URIs. */
 test("reservedDocsTopicResourceUris matches docsMcpResources URIs", () => {
   const program = fixture();
   expect(reservedDocsTopicResourceUris(program)).toEqual(

package/src/formats.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for formats module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import {
   parseCommaList,
@@ -8,6 +12,7 @@ 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);
@@ -15,21 +20,25 @@ 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

@@ -1,3 +1,7 @@
+/*
+Tests for headless module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import {
   formatDryRunMessage,
@@ -8,12 +12,14 @@ 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);
@@ -21,6 +27,7 @@ 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,
@@ -30,6 +37,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),
@@ -46,11 +54,13 @@ 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");
 });
 
+/** 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;