argsbarg 5.0.1 → 5.0.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
 ## [5.0.1] - 2026-07-04
 
 
@@ -567,7 +573,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.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.0.2...HEAD
+[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
 [4.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.1.1

package/docs/distribution-homebrew.md

@@ -60,6 +60,8 @@ Completions require users to configure their shell per [Homebrew Shell Completio
 
 **Why configure is separate from `post_install`:** the wizard is interactive (TTY + prompts for secrets). Formula `post_install` runs non-interactively during `brew install` and in CI (`brew test`). Apps with `appConfig` print a one-line configure hint in formula `caveats` instead.
 
+**MCP hosts:** when `mcpServer.enabled` is true, add a caveats line that chat apps (Cursor, Claude Desktop, etc.) must be **restarted** after `brew install` / `brew upgrade` — `post_install` updates MCP config on disk, but hosts typically load it only at startup.
+
 ## Bootstrap CLI (`argsbarg create`)
 
 Copy the shipped `examples/full-example` template into a new directory with identity substitutions, then run install, schemagen, tests, and git init (when appropriate):

package/examples/full-example/scripts/formula-shared.ts

@@ -17,6 +17,7 @@ export const formulaPostInstallRuby = `def post_install
 export const formulaCaveatsRuby = `def caveats
     <<~EOS
       Run \`${key} configure\` to set up agent artifacts and app config (interactive).
+      Restart MCP chat apps (Cursor, Claude Desktop, etc.) after install or upgrade so they load the updated server.
     EOS
   end`;
 

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for builtins/builtins module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { resolveCapabilities } from "../capabilities.ts";
 import { cliBuiltinDocsGroup } from "../docs/builtin.ts";
@@ -31,7 +35,9 @@ const noMcp: CliProgram = {
   commands: [{ key: "ping", description: "Ping.", handler: () => {} }],
 };
 
+/** 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");
@@ -45,6 +51,7 @@ 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(
@@ -56,6 +63,7 @@ describe("builtins help copy", () => {
     expect(configure.description).not.toContain("MCP");
   });
 
+  /** Configure notes mention brew upgrade and interactive configure. */
   test("configure notes mention brew upgrade and interactive configure", () => {
     const configure = cliBuiltinConfigureCommand(fixture);
     expect(configure.notes).toContain("brew upgrade");
@@ -71,6 +79,7 @@ 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"]));
@@ -81,6 +90,7 @@ describe("builtins help copy", () => {
     }
   });
 
+  /** Mcp builtin description is user-facing. */
   test("mcp builtin description is user-facing", () => {
     const withDocs: CliProgram = {
       ...fixture,
@@ -93,7 +103,9 @@ 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) ?? [];
@@ -103,19 +115,23 @@ 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");
   });
 });
 
+/** 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);
@@ -124,6 +140,7 @@ 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);
@@ -131,6 +148,7 @@ describe("completion emitters", () => {
     expect(bash).toContain("--sync");
   });
 
+  /** Tests that zsh script registers compdef. */
   test("zsh script registers compdef", () => {
     const schema = cliPresentationRoot({
       key: "zapp",
@@ -144,7 +162,9 @@ describe("completion emitters", () => {
   });
 });
 
+/** Tests for schema export builtins. */
 describe("schema export builtins", () => {
+  /** ExportPresentationBuiltins includes config when appConfig set. */
   test("exportPresentationBuiltins includes config when appConfig set", () => {
     const withConfig: CliProgram = {
       ...fixture,
@@ -159,13 +179,16 @@ 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");
   });
 });
 
+/** Tests for docs skill topic copy. */
 describe("docs skill topic copy", () => {
+  /** Tests that mentions configure when configure is enabled. */
   test("mentions configure when configure is enabled", () => {
     const withDocs: CliProgram = {
       ...noMcp,

package/src/builtins/config.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for builtins/config module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -20,7 +24,9 @@ function configFixture(): CliProgram {
   };
 }
 
+/** Tests for builtins/config. */
 describe("builtins/config", () => {
+  /** Tests that config get redacts sensitive values. */
   test("config get redacts sensitive values", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
     const prevHome = process.env.HOME;
@@ -43,6 +49,7 @@ describe("builtins/config", () => {
     }
   });
 
+  /** Tests that config get --json redacts sensitive as { set: true }. */
   test("config get --json redacts sensitive as { set: true }", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
     const prevHome = process.env.HOME;
@@ -65,6 +72,7 @@ describe("builtins/config", () => {
     }
   });
 
+  /** Tests that config set writes and resolves without required exit. */
   test("config set writes and resolves without required exit", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
     const prevHome = process.env.HOME;

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

@@ -1,16 +1,23 @@
+/*
+Tests for cli-tool/cli-smoke module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 
 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);
@@ -21,6 +28,7 @@ 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

@@ -1,3 +1,7 @@
+/*
+Tests for cli-tool/create module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -12,7 +16,9 @@ import {
   substituteTemplateContent,
 } from "./create.ts";
 
+/** Tests for argsbarg create. */
 describe("argsbarg create", () => {
+  /** Tests that substitutes {key} tokens. */
   test("substitutes {key} tokens", () => {
     const out = substituteTemplateContent(
       "key={key} class={className} env={envPrefix}_API_TOKEN tap={tap} org={tapOrg}",
@@ -38,12 +44,14 @@ describe("argsbarg create", () => {
     expect(out).not.toContain("{key}");
   });
 
+  /** Tests that classNameFromKey. */
   test("classNameFromKey", () => {
     expect(classNameFromKey("sqsp-i18n")).toBe("SqspI18n");
     expect(classNameFromKey("at1")).toBe("At1");
     expect(classNameFromKey("1password")).toBe("App1password");
   });
 
+  /** ResolveCreateOptions derives identity defaults from key. */
   test("resolveCreateOptions derives identity defaults from key", () => {
     expect(resolveCreateOptions({ key: "1password", releaseRepo: "org/1password" }).className).toBe(
       "App1password",
@@ -59,10 +67,12 @@ 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);
   });
 
+  /** Tests that renderCreateTree includes justfile and create-identity. */
   test("renderCreateTree includes justfile and create-identity", () => {
     const tree = renderCreateTree({
       key: "testapp",
@@ -88,6 +98,7 @@ describe("argsbarg create", () => {
     expect(formula).toContain("create-identity.ts");
   });
 
+  /** Tests that --check detects drift. */
   test("--check detects drift", () => {
     const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
     try {
@@ -111,6 +122,7 @@ describe("argsbarg create", () => {
     }
   });
 
+  /** Tests that --check infers options from create-identity.ts. */
   test("--check infers options from create-identity.ts", () => {
     const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
     try {
@@ -134,6 +146,7 @@ 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

@@ -1,3 +1,7 @@
+/*
+Tests for cli-tool/full-example-capabilities module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -45,7 +49,9 @@ const sinkProgram = {
   ],
 } satisfies CliProgram;
 
+/** Tests for full-example template. */
 describe("full-example template", () => {
+  /** Tests that program source enables every builtin flag. */
   test("program source enables every builtin flag", () => {
     expect(programSource).toContain("mcpServer: {");
     expect(programSource).toContain("enabled: true");
@@ -53,11 +59,13 @@ 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

@@ -1,3 +1,7 @@
+/*
+Tests for config/context module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -20,7 +24,9 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+/** Tests for config/context. */
 describe("config/context", () => {
+  /** Tests that AppConfigSnapshot get, require, read, set. */
   test("AppConfigSnapshot get, require, read, set", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-test-"));
     const prevHome = process.env.HOME;
@@ -50,6 +56,7 @@ describe("config/context", () => {
     }
   });
 
+  /** Tests that EmptyAppConfigSnapshot when program.appConfig unset. */
   test("EmptyAppConfigSnapshot when program.appConfig unset", () => {
     const programWithoutConfig: CliProgram = {
       key: "x",
@@ -65,6 +72,7 @@ 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

@@ -1,3 +1,7 @@
+/*
+Tests for config/file module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -40,7 +44,9 @@ 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({
@@ -51,6 +57,7 @@ describe("config/file", () => {
     expect(cfg?.port).toBeUndefined();
   });
 
+  /** ResolveAppConfigPath uses config.json. */
   test("resolveAppConfigPath uses config.json", () => {
     withHome((home) => {
       expect(resolveAppConfigPath(program)).toBe(
@@ -59,6 +66,7 @@ describe("config/file", () => {
     });
   });
 
+  /** ResolveAppConfig prefers host env over file. */
   test("resolveAppConfig prefers host env over file", () => {
     withHome((_home) => {
       const prevToken = process.env.API_TOKEN;
@@ -76,6 +84,7 @@ describe("config/file", () => {
     });
   });
 
+  /** MissingRequiredConfig and formatMissingConfigMessage. */
   test("missingRequiredConfig and formatMissingConfigMessage", () => {
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
@@ -91,6 +100,7 @@ describe("config/file", () => {
     }
   });
 
+  /** Rejects unknown keys on read. */
   test("rejects unknown keys on read", () => {
     withHome(() => {
       const configPath = resolveAppConfigPath(program);
@@ -100,6 +110,7 @@ describe("config/file", () => {
     });
   });
 
+  /** WriteAppConfigFile round-trip. */
   test("writeAppConfigFile round-trip", () => {
     withHome(() => {
       writeAppConfigFile(program, { apiToken: "saved" });
@@ -108,6 +119,7 @@ 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

@@ -1,3 +1,7 @@
+/*
+Tests for config/resolve module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
@@ -25,7 +29,9 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+/** 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";
@@ -38,6 +44,7 @@ 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;
@@ -49,6 +56,7 @@ 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 = "";
@@ -61,6 +69,7 @@ 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;
@@ -73,6 +82,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** All-string mode uses entry.default. */
   test("all-string mode uses entry.default", () => {
     const stringProgram: CliProgram = {
       ...program,
@@ -86,6 +96,7 @@ 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";
@@ -97,6 +108,7 @@ 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";
@@ -110,6 +122,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Resolve callback supplies value when env and file are absent. */
   test("resolve callback supplies value when env and file are absent", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -135,6 +148,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Env overrides resolve callback. */
   test("env overrides resolve callback", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -161,6 +175,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** File overrides resolve callback. */
   test("file overrides resolve callback", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -186,6 +201,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Tests that falls back to env when resolve returns undefined. */
   test("falls back to env when resolve returns undefined", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -212,6 +228,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Resolve callback is skipped when env is set. */
   test("resolve callback is skipped when env is set", () => {
     let resolveCalled = false;
     const resolveProgram: CliProgram = {
@@ -243,6 +260,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Tests that async resolve is ignored with stderr warning. */
   test("async resolve is ignored with stderr warning", () => {
     const resolveProgram: CliProgram = {
       ...program,

package/src/config/validate.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for config/validate module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { parseConfigSetValue, validateConfigDocument } from "./validate.ts";
 
@@ -17,7 +21,9 @@ 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 } },
@@ -27,12 +33,14 @@ 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 },
@@ -42,16 +50,19 @@ 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/config.integration.test.ts

@@ -10,6 +10,7 @@ import { bootstrapAppConfig } from "./config/bootstrap.ts";
 import { resolveAppConfigPath } from "./config/file.ts";
 import { mcpRequest, testProgram } from "./test-fixtures.ts";
 
+/** Tests that bootstrapAppConfig prefers host env over config file. */
 test("bootstrapAppConfig prefers host env over config file", () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-env-"));
   const prevHome = process.env.HOME;
@@ -43,6 +44,7 @@ test("bootstrapAppConfig prefers host env over config file", () => {
   }
 });
 
+/** MCP program.appConfig fails when required config missing. */
 test("MCP program.appConfig fails when required config missing", async () => {
   const responses = await mcpRequest(
     [
@@ -60,6 +62,7 @@ test("MCP program.appConfig fails when required config missing", async () => {
   expect(res.result.content[0]?.text).toContain("argsTestSecret");
 });
 
+/** MCP program.appConfig succeeds when env present. */
 test("MCP program.appConfig succeeds when env present", async () => {
   const responses = await mcpRequest(
     [
@@ -77,6 +80,7 @@ test("MCP program.appConfig succeeds when env present", async () => {
   expect(res.result.content[0]?.text.trim()).toBe("sekrit");
 });
 
+/** MCP config file loads and exports vars for tool handlers. */
 test("MCP config file loads and exports vars for tool handlers", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-mcp-"));
   const configFile = join(dir, ".local", "lib", "mcp_test", "config");
@@ -106,6 +110,7 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
   rmSync(dir, { recursive: true, force: true });
 });
 
+/** Cli.run docs api skips required appConfig exit. */
 test("Cli.run docs api skips required appConfig exit", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-docs-skip-"));
   const configFile = join(dir, ".local", "lib", "docs_skip_test", "config");