argsbarg 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.2] - 2026-06-24
+
+
 ## [4.0.1] - 2026-06-24
 
 
@@ -452,7 +455,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/v4.0.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.0.2...HEAD
+[4.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.2
 [4.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.1
 [4.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.0
 [3.6.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.4

package/docs/cli-program.md

@@ -425,7 +425,7 @@ await cli.run();
 - Default: `$XDG_CONFIG_HOME/<sanitized-key>/config` or `%APPDATA%/<key>/config`.
 - JSON: flat object keyed by schema names — `{ "apiToken": "…", "maxRetries": 5 }`.
 - **Strict:** unknown keys rejected on load.
-- **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `config get`/`set` skip this exit.
+- **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `docs` and `config get`/`set` skip this exit.
 - **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
 - **Configure:** `myapp install --configure` (not part of `--all`).
 

package/package.json

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

package/src/capabilities.ts

@@ -47,6 +47,18 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   return names;
 }
 
+/** Commands that may run without required appConfig values (read-only / config introspection). */
+export function skipsRequiredAppConfigExit(path: string[], caps: CliCapabilities): boolean {
+  const root = path[0];
+  if (root === "config" && caps.configCommands) {
+    return true;
+  }
+  if (root === "docs" && caps.docs) {
+    return true;
+  }
+  return false;
+}
+
 export type CapabilityFeature = "mcp" | "install" | "docs" | "config";
 
 /** Stderr message when a disabled built-in is invoked from the CLI. */

package/src/cli.ts

@@ -5,7 +5,12 @@ Runtime entry point: validate program, cache derived state, run / invoke / MCP s
 import { format } from "node:util";
 import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
 import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
-import { assertBuiltinAllowed, type CliCapabilities, resolveCapabilities } from "./capabilities.ts";
+import {
+  assertBuiltinAllowed,
+  type CliCapabilities,
+  resolveCapabilities,
+  skipsRequiredAppConfigExit,
+} from "./capabilities.ts";
 import {
   bootstrapAppConfig,
   type EnsureAppConfigOpts,
@@ -113,10 +118,10 @@ export class Cli {
       });
     }
 
-    const isConfigCmd = pr.path[0] === "config" && this.caps.configCommands;
+    const skipRequiredConfig = skipsRequiredAppConfigExit(pr.path, this.caps);
     const snapshot = this.buildAppConfigSnapshot({
-      interactive: !isConfigCmd && !!process.stdin.isTTY,
-      exitOnMissing: !isConfigCmd,
+      interactive: !skipRequiredConfig && !!process.stdin.isTTY,
+      exitOnMissing: !skipRequiredConfig,
     });
 
     const ctx = new CliContext(

package/src/config.integration.test.ts

@@ -98,3 +98,47 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
   expect(res.result.isError).toBe(false);
   expect(res.result.content[0]?.text.trim()).toBe("present");
 });
+
+test("Cli.run docs api skips required appConfig exit", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "argsbarg-docs-skip-"));
+  const configFile = join(dir, "config");
+  writeFileSync(configFile, "{}\n");
+  const entry = join(import.meta.dir, "index.ts");
+  const mainPath = join(dir, "run-docs.ts");
+  writeFileSync(
+    mainPath,
+    `import { Cli, type CliProgram } from ${JSON.stringify(entry)};
+const program = {
+  key: "docs-skip-test",
+  version: "1.0.0",
+  description: "test",
+  docs: { enabled: true, topics: { readme: { text: "# readme\\n" } } },
+  appConfig: {
+    path: ${JSON.stringify(configFile)},
+    entries: { token: { description: "Token.", env: "DOCS_SKIP_RUN_TOKEN" } },
+  },
+  handler: () => {},
+} satisfies CliProgram;
+await new Cli(program).run(process.argv.slice(2));
+`,
+  );
+  const env = { ...process.env };
+  delete env.DOCS_SKIP_RUN_TOKEN;
+  try {
+    const proc = Bun.spawn(["bun", "run", mainPath, "docs", "api"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env,
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("# docs-skip-test — CLI API reference");
+    expect(stderr).not.toContain("Missing required configuration");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/docs/docs.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { completionBashScript } from "../builtins/index.ts";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { resolveCapabilities, skipsRequiredAppConfigExit } from "../capabilities.ts";
 import { Cli } from "../index.ts";
 import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
@@ -151,6 +152,19 @@ test("docs api prints markdown reference", async () => {
   expect(result.stdout).toContain("myapp docs schema");
 });
 
+test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
+  const program = {
+    ...docsFixture(),
+    appConfig: {
+      entries: { token: { description: "Token.", env: "DOCS_SKIP_TOKEN" } },
+    },
+  };
+  const caps = resolveCapabilities(program);
+  expect(skipsRequiredAppConfigExit(["docs", "api"], caps)).toBe(true);
+  expect(skipsRequiredAppConfigExit(["config", "get"], caps)).toBe(true);
+  expect(skipsRequiredAppConfigExit(["run"], caps)).toBe(false);
+});
+
 test("docs skill prints Cursor SKILL.md", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "skill"]);
   expect(result.exitCode).toBe(0);