argsbarg 5.0.2 → 5.1.0

package/src/cli-tool/full-example-capabilities.test.ts

@@ -59,13 +59,11 @@ describe("full-example template", () => {
     expect(programSource).toContain("appConfig:");
   });
 
-  /** Status command defines outputSchema. */
   test("status command defines outputSchema", () => {
     const statusSource = readFileSync(join(exampleRoot, "src/commands/status/command.ts"), "utf8");
     expect(statusSource).toContain("outputSchema:");
   });
 
-  /** ResolveCapabilities matches full sink shape. */
   test("resolveCapabilities matches full sink shape", () => {
     expect(resolveCapabilities(sinkProgram)).toEqual({
       completion: true,

package/src/config/context.test.ts

@@ -72,7 +72,6 @@ describe("config/context", () => {
     expect(empty.dir).toBe(dirname(empty.path));
   });
 
-  /** Tests that AppConfigSnapshot path uses OS default from program key. */
   test("AppConfigSnapshot path uses OS default from program key", () => {
     const ctx = createAppConfigSnapshot(program, {}, {});
     expect(ctx.path).toContain("ctx_test");

package/src/config/entry.ts

@@ -29,7 +29,7 @@ export function configEntryRequired(
   return true;
 }
 
-/** Whether prompts and `config get` should redact this entry. */
+/** Whether prompts and `configure get` should redact this entry. */
 export function configEntrySensitive(key: string, entry: CliAppConfigEntry): boolean {
   return entry.sensitive ?? defaultConfigEntrySensitive(key);
 }
@@ -56,7 +56,7 @@ export function jsonSchemaRequiredKeys(
   return new Set(required.filter((k): k is string => typeof k === "string"));
 }
 
-/** Whether built-in config get/set commands are enabled. */
+/** Whether built-in `configure get` / `configure set` subcommands are enabled. */
 export function configCommandsEnabled(program: CliProgram): boolean {
   if (!program.appConfig) {
     return false;

package/src/config/file.test.ts

@@ -46,7 +46,6 @@ function withHome<T>(fn: (home: string) => T): T {
 
 /** Tests for config/file. */
 describe("config/file", () => {
-  /** BuildProgramUserConfig from program.appConfig env entries. */
   test("buildProgramUserConfig from program.appConfig env entries", () => {
     const cfg = buildProgramUserConfig(program);
     expect(cfg?.api_token).toMatchObject({
@@ -57,7 +56,6 @@ describe("config/file", () => {
     expect(cfg?.port).toBeUndefined();
   });
 
-  /** ResolveAppConfigPath uses config.json. */
   test("resolveAppConfigPath uses config.json", () => {
     withHome((home) => {
       expect(resolveAppConfigPath(program)).toBe(
@@ -100,7 +98,6 @@ describe("config/file", () => {
     }
   });
 
-  /** Rejects unknown keys on read. */
   test("rejects unknown keys on read", () => {
     withHome(() => {
       const configPath = resolveAppConfigPath(program);
@@ -110,7 +107,6 @@ describe("config/file", () => {
     });
   });
 
-  /** WriteAppConfigFile round-trip. */
   test("writeAppConfigFile round-trip", () => {
     withHome(() => {
       writeAppConfigFile(program, { apiToken: "saved" });
@@ -119,7 +115,6 @@ describe("config/file", () => {
     });
   });
 
-  /** Tests that uninstallAppConfig removes config directory recursively. */
   test("uninstallAppConfig removes config directory recursively", () => {
     withHome(() => {
       writeAppConfigFile(program, { apiToken: "saved" });

package/src/config/resolve.test.ts

@@ -31,7 +31,6 @@ const program: CliProgram = {
 
 /** Tests for config/resolve. */
 describe("config/resolve", () => {
-  /** Tests that prefers env over file for mapped keys. */
   test("prefers env over file for mapped keys", () => {
     const prev = process.env.API_TOKEN;
     process.env.API_TOKEN = "from-env";
@@ -44,7 +43,6 @@ describe("config/resolve", () => {
     }
   });
 
-  /** Tests that uses file when env empty. */
   test("uses file when env empty", () => {
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
@@ -56,7 +54,6 @@ describe("config/resolve", () => {
     }
   });
 
-  /** Tests that empty string in env or file counts as missing. */
   test("empty string in env or file counts as missing", () => {
     const prev = process.env.API_TOKEN;
     process.env.API_TOKEN = "";
@@ -69,7 +66,6 @@ describe("config/resolve", () => {
     }
   });
 
-  /** Applies jsonSchema default when file and env absent. */
   test("applies jsonSchema default when file and env absent", () => {
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
@@ -82,7 +78,6 @@ describe("config/resolve", () => {
     }
   });
 
-  /** All-string mode uses entry.default. */
   test("all-string mode uses entry.default", () => {
     const stringProgram: CliProgram = {
       ...program,
@@ -96,7 +91,6 @@ describe("config/resolve", () => {
     expect(resolved.greeting).toBe("world");
   });
 
-  /** Tests that prefers captured host env over file when process.env was exported from file. */
   test("prefers captured host env over file when process.env was exported from file", () => {
     const hostEnv = { API_TOKEN: "from-host" };
     process.env.API_TOKEN = "from-file-export";
@@ -108,7 +102,6 @@ describe("config/resolve", () => {
     }
   });
 
-  /** ExportConfigToEnv does not overwrite host env. */
   test("exportConfigToEnv does not overwrite host env", () => {
     const prev = process.env.API_TOKEN;
     process.env.API_TOKEN = "from-host";

package/src/config/resolve.ts

@@ -227,7 +227,7 @@ export function formatMissingConfigMessage(program: CliProgram, keys: string[]):
   return [
     `Missing required configuration: ${list}`,
     `Configure interactively:  ${program.key} configure`,
-    `Or set via:               ${program.key} config set <key> <value>`,
+    `Or set via:               ${program.key} configure set <key> <value>`,
     `Config file:              ${path}`,
     `See:                      ${program.key} docs mcp`,
   ].join("\n");
@@ -240,7 +240,7 @@ export function formatMcpMissingConfigMessage(program: CliProgram, keys: string[
   return [
     `Missing required configuration: ${list}`,
     `Configure: ${program.key} configure`,
-    `Or set via: ${program.key} config set`,
+    `Or set via: ${program.key} configure set`,
     `Config file: ${path}`,
   ].join("\n");
 }

package/src/config/validate.test.ts

@@ -23,7 +23,6 @@ const rootSchema = {
 
 /** Tests for config/validate. */
 describe("config/validate", () => {
-  /** Tests that accepts valid document. */
   test("accepts valid document", () => {
     const result = validateConfigDocument(
       { apiToken: "x", maxRetries: 3, prefs: { ttl: 3600 } },
@@ -33,14 +32,12 @@ describe("config/validate", () => {
     expect(result.errors).toEqual([]);
   });
 
-  /** Rejects missing required property. */
   test("rejects missing required property", () => {
     const result = validateConfigDocument({ apiToken: "x" }, rootSchema);
     expect(result.valid).toBe(false);
     expect(result.errors.some((e) => e.includes("maxRetries"))).toBe(true);
   });
 
-  /** Rejects unknown property when additionalProperties is false. */
   test("rejects unknown property when additionalProperties is false", () => {
     const result = validateConfigDocument(
       { apiToken: "x", maxRetries: 1, extra: true },
@@ -50,19 +47,16 @@ describe("config/validate", () => {
     expect(result.errors.some((e) => e.includes("extra"))).toBe(true);
   });
 
-  /** Rejects type mismatch. */
   test("rejects type mismatch", () => {
     const result = validateConfigDocument({ apiToken: "x", maxRetries: "nope" }, rootSchema);
     expect(result.valid).toBe(false);
   });
 
-  /** ParseConfigSetValue coerces number and boolean. */
   test("parseConfigSetValue coerces number and boolean", () => {
     expect(parseConfigSetValue("5", { type: "integer" }, rootSchema, false)).toBe(5);
     expect(parseConfigSetValue("true", { type: "boolean" }, rootSchema, false)).toBe(true);
   });
 
-  /** ParseConfigSetValue requires --json for objects. */
   test("parseConfigSetValue requires --json for objects", () => {
     expect(() => parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, false)).toThrow(
       /--json/,

package/src/configure/configure.test.ts

@@ -48,19 +48,16 @@ afterEach(() => {
 
 /** 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");
@@ -69,14 +66,12 @@ describe("configure opts", () => {
 
 /** 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" });
@@ -110,7 +105,6 @@ 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" }));
@@ -118,7 +112,6 @@ 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" }));
@@ -126,7 +119,6 @@ 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,
@@ -142,7 +134,6 @@ 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" }));
@@ -152,7 +143,6 @@ 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({
@@ -162,7 +152,6 @@ 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/docs/api-guide.test.ts

@@ -49,7 +49,6 @@ 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);
@@ -58,7 +57,6 @@ 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);
@@ -68,7 +66,6 @@ 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",
@@ -82,7 +79,6 @@ 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",

package/src/docs/docs.test.ts

@@ -83,26 +83,22 @@ 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";
@@ -110,7 +106,6 @@ 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);
@@ -120,13 +115,11 @@ 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);
@@ -139,7 +132,6 @@ 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");
@@ -149,7 +141,6 @@ 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);
@@ -158,7 +149,6 @@ 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);
@@ -168,7 +158,6 @@ 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(),
@@ -178,11 +167,10 @@ test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
   };
   const caps = resolveCapabilities(program);
   expect(skipsRequiredAppConfigExit(["docs", "api"], caps)).toBe(true);
-  expect(skipsRequiredAppConfigExit(["config", "get"], caps)).toBe(true);
+  expect(skipsRequiredAppConfigExit(["configure", "get"], caps)).toBe(true);
   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);
@@ -209,7 +197,6 @@ 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");
@@ -221,7 +208,6 @@ 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");
@@ -231,7 +217,6 @@ 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");
@@ -245,7 +230,6 @@ 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);
@@ -255,7 +239,6 @@ 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);
@@ -266,7 +249,6 @@ 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);
@@ -277,7 +259,6 @@ 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);
@@ -288,7 +269,6 @@ 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

@@ -34,17 +34,14 @@ 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"]);
@@ -54,17 +51,14 @@ 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

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