argsbarg 5.0.2 → 5.0.3

package/CHANGELOG.md

@@ -7,11 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.3] - 2026-07-04
+
+### Changed
+
+- **JSDoc style** — short `test()` callbacks no longer carry redundant one-liners; `describe` blocks still documented. `requireYesInNonTty` uses per-parameter JSDoc instead of `@param`. Pure re-export barrels stay comment-free.
+
 ## [5.0.2] - 2026-07-04
 
 ### Changed
 
-- **JSDoc style** — every `describe` and `test` block in `src/**/*.test.ts` now has a human-readable JSDoc; `configure` modules brought in line with file headers and symbol docs.
+- **JSDoc style** — every `describe` block in `src/**/*.test.ts` now has a human-readable JSDoc; `configure` modules brought in line with file headers and symbol docs.
 
 ## [5.0.1] - 2026-07-04
 
@@ -573,7 +579,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.0.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.0.3...HEAD
+[5.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.3
 [5.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.2
 [5.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.1
 [5.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.0

package/index.d.ts

@@ -551,11 +551,16 @@ export declare function shouldRunHeadlessWithYes(ctx: HeadlessContext, opts: {
 	hasRequiredArgs: boolean;
 	dryRun?: boolean;
 }, interactive?: boolean): boolean;
-/**
- * Exits when non-interactive mode is used without `--yes`.
- * @param hint - Command-specific guidance appended to the error
- */
-export declare function requireYesInNonTty(yes: boolean, hint: string, dryRun?: boolean, interactive?: boolean): void;
+/** Exits when non-interactive mode is used without `--yes`. */
+export declare 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?: boolean, 
+/** Injectable TTY probe for tests. */
+interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
 /** Resolved paths for `mcp bundle`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -37,7 +37,6 @@ const noMcp: CliProgram = {
 
 /** Tests for builtins help copy. */
 describe("builtins help copy", () => {
-  /** Configure command includes Homebrew-oriented description. */
   test("configure command includes Homebrew-oriented description", () => {
     const configure = cliBuiltinConfigureCommand(fixture);
     expect(configure.description).toContain("agent skills");
@@ -51,7 +50,6 @@ describe("builtins help copy", () => {
     expect(yesOpt?.shortName).toBe("y");
   });
 
-  /** Configure copy omits MCP when mcpServer unset. */
   test("configure copy omits MCP when mcpServer unset", () => {
     const caps = resolveCapabilities(noMcp);
     expect(configureCommandDescription(noMcp, caps)).toBe(
@@ -79,7 +77,6 @@ describe("builtins help copy", () => {
     expect(configureBuiltinOptions(withConfig).map((o) => o.name)).toContain("remove-config");
   });
 
-  /** Configure -y parses as --yes. */
   test("configure -y parses as --yes", () => {
     const root = cliParseRoot(fixture);
     const pr = postParseValidate(root, parse(root, ["configure", "-y", "--sync"]));
@@ -90,7 +87,6 @@ describe("builtins help copy", () => {
     }
   });
 
-  /** Mcp builtin description is user-facing. */
   test("mcp builtin description is user-facing", () => {
     const withDocs: CliProgram = {
       ...fixture,
@@ -105,7 +101,6 @@ describe("builtins help copy", () => {
 
 /** Tests for presentation root. */
 describe("presentation root", () => {
-  /** Includes mcp and configure when enabled. */
   test("includes mcp and configure when enabled", () => {
     const root = cliPresentationRoot(fixture);
     const keys = root.commands?.map((c) => c.key) ?? [];
@@ -115,14 +110,12 @@ describe("presentation root", () => {
     expect(keys).not.toContain("install");
   });
 
-  /** Omits configure when configure.enabled is false. */
   test("omits configure when configure.enabled is false", () => {
     const disabled: CliProgram = { ...fixture, configure: { enabled: false } };
     const root = cliPresentationRoot(disabled);
     expect(root.commands?.map((c) => c.key)).not.toContain("configure");
   });
 
-  /** Includes version builtin. */
   test("includes version builtin", () => {
     const root = cliPresentationRoot(fixture);
     expect(root.commands?.map((c) => c.key)).toContain("version");
@@ -131,7 +124,6 @@ describe("presentation root", () => {
 
 /** Tests for completion emitters. */
 describe("completion emitters", () => {
-  /** Tests that fish script references app key and subcommands. */
   test("fish script references app key and subcommands", () => {
     const schema = cliPresentationRoot(fixture);
     const fish = completionFishScript(schema);
@@ -140,7 +132,6 @@ describe("completion emitters", () => {
     expect(fish).toContain("configure");
   });
 
-  /** Tests that bash script includes configure flags. */
   test("bash script includes configure flags", () => {
     const schema = cliPresentationRoot(fixture);
     const bash = completionBashScript(schema);
@@ -148,7 +139,6 @@ describe("completion emitters", () => {
     expect(bash).toContain("--sync");
   });
 
-  /** Tests that zsh script registers compdef. */
   test("zsh script registers compdef", () => {
     const schema = cliPresentationRoot({
       key: "zapp",
@@ -179,7 +169,6 @@ describe("schema export builtins", () => {
     expect(builtins.map((b) => b.key)).toContain("configure");
   });
 
-  /** ExportPresentationBuiltins omits hidden completion. */
   test("exportPresentationBuiltins omits hidden completion", () => {
     const builtins = exportPresentationBuiltins(fixture);
     expect(builtins.map((b) => b.key)).not.toContain("completion");

package/src/cli-tool/cli-smoke.test.ts

@@ -10,14 +10,12 @@ const main = join(import.meta.dir, "main.ts");
 
 /** Tests for argsbarg cli-tool. */
 describe("argsbarg cli-tool", () => {
-  /** Tests that version subcommand prints version. */
   test("version subcommand prints version", () => {
     const proc = spawnSync("bun", [main, "version"], { encoding: "utf8" });
     expect(proc.status).toBe(0);
     expect(proc.stdout.trim().length).toBeGreaterThan(0);
   });
 
-  /** Tests that help lists create and version only (no install, completion, mcp). */
   test("help lists create and version only (no install, completion, mcp)", () => {
     const proc = spawnSync("bun", [main, "--help"], { encoding: "utf8" });
     expect(proc.status).toBe(0);
@@ -28,7 +26,6 @@ describe("argsbarg cli-tool", () => {
     expect(proc.stdout).not.toContain("mcp");
   });
 
-  /** Completion subcommand is disabled. */
   test("completion subcommand is disabled", () => {
     const proc = spawnSync("bun", [main, "completion", "bash"], { encoding: "utf8" });
     expect(proc.status).toBe(1);

package/src/cli-tool/create.test.ts

@@ -44,7 +44,6 @@ describe("argsbarg create", () => {
     expect(out).not.toContain("{key}");
   });
 
-  /** Tests that classNameFromKey. */
   test("classNameFromKey", () => {
     expect(classNameFromKey("sqsp-i18n")).toBe("SqspI18n");
     expect(classNameFromKey("at1")).toBe("At1");
@@ -67,7 +66,6 @@ describe("argsbarg create", () => {
     expect(opts.desc).toBe("At1 CLI");
   });
 
-  /** ResolveCreateOptions requires release repo. */
   test("resolveCreateOptions requires release repo", () => {
     expect(() => resolveCreateOptions({ key: "at1" })).toThrow(/release repo/i);
   });
@@ -146,7 +144,6 @@ describe("argsbarg create", () => {
     }
   });
 
-  /** Tests that --diff captures drift details. */
   test("--diff captures drift details", () => {
     const drifts = diffCreateDetails("/nonexistent", { key: "x", releaseRepo: "org/x" });
     expect(drifts.length).toBeGreaterThan(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/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/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(),
@@ -182,7 +171,6 @@ 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);
@@ -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(