argsbarg 4.0.0 → 4.0.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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
+
+
 ## [4.0.0] - 2026-06-24
 
 ### Added
@@ -449,7 +455,9 @@ 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.0...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
 [3.6.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.3

package/docs/cli-program.md

@@ -425,13 +425,13 @@ 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`).
 
 See [config-schema.md](config-schema.md) for codegen, [install.md](install.md), and [mcp.md](mcp.md).
 
-**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read` — prefer over `process.env` in handlers; env export remains for subprocess inheritance.
+**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read`, `path` — prefer over `process.env` in handlers; env export remains for subprocess inheritance. `path` is the resolved absolute config file path (`program.appConfig.path` when set, otherwise the OS default from `program.key`).
 
 ## Reserved names
 

package/docs/config-schema.md

@@ -42,7 +42,7 @@ await cli.run();
 | `install --configure` / `--status` | Interactive setup and status |
 | Built-in `config get` / `config set` | Read/write resolved values (opt-out via `commands: false`) |
 | MCP bundle / Claude plugin | `userConfig` for entries with `env` set |
-| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read` — prefer over `process.env` |
+| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `path` — prefer over `process.env` |
 
 **Validation at runtime** — argsbarg validates the config file and `config set` / `ctx.appConfig.set` against the effective JSON Schema (block `jsonSchema` or synthesized all-string schema).
 

package/index.d.ts

@@ -2,10 +2,14 @@
 
 export type ResolvedConfig = Record<string, unknown>;
 declare class EmptyAppConfigSnapshot {
+	private readonly program;
+	constructor(program: CliProgram);
 	get(_key: string): undefined;
 	require(key: string): never;
 	set(_key: string, _value: unknown): void;
 	read(): ResolvedConfig;
+	/** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
+	get path(): string;
 }
 declare class AppConfigSnapshot {
 	private readonly program;
@@ -16,6 +20,8 @@ declare class AppConfigSnapshot {
 	require(key: string): unknown;
 	set(key: string, value: unknown): void;
 	read(): ResolvedConfig;
+	/** Resolved absolute path to the app JSON config file (honors `program.appConfig.path` or OS default). */
+	get path(): string;
 	/** Replace snapshot after external bootstrap (internal). */
 	refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void;
 	private assertEntryKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "4.0.0",
+  "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/context.test.ts

@@ -36,6 +36,7 @@ describe("config/context", () => {
 
       expect(ctx.get("note")).toBe("hello");
       expect(ctx.require("apiToken")).toBe("tok");
+      expect(ctx.path).toBe(path);
 
       ctx.set("note", "updated");
       expect(ctx.get("note")).toBe("updated");
@@ -57,5 +58,22 @@ describe("config/context", () => {
     const empty = createAppConfigSnapshot(program, {}, {});
     expect(empty.get("any")).toBeUndefined();
     expect(() => empty.set("any", "v")).toThrow(/program.appConfig is not set/);
+    expect(empty.path).toContain("x");
+    expect(empty.path.endsWith("/config") || empty.path.endsWith("\\config")).toBe(true);
+  });
+
+  test("AppConfigSnapshot path uses OS default when program.appConfig.path omitted", () => {
+    const program: CliProgram = {
+      key: "ctx-test",
+      version: "1.0.0",
+      description: "Context test.",
+      appConfig: {
+        entries: { note: { description: "Note." } },
+      },
+      handler: () => {},
+    };
+    const ctx = createAppConfigSnapshot(program, {}, {});
+    expect(ctx.path).toContain("ctx_test");
+    expect(ctx.path.endsWith("/config") || ctx.path.endsWith("\\config")).toBe(true);
   });
 });

package/src/config/context.ts

@@ -3,12 +3,14 @@ Handler-facing resolved app config snapshot (ctx.appConfig).
 */
 
 import type { CliProgram } from "../types.ts";
-import { writeAppConfigFile } from "./file.ts";
+import { resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
 import type { ResolvedConfig } from "./resolve.ts";
 import { exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
 
 /** Empty snapshot when program.appConfig is not set. */
 export class EmptyAppConfigSnapshot {
+  constructor(private readonly program: CliProgram) {}
+
   get(_key: string): undefined {
     return undefined;
   }
@@ -24,6 +26,11 @@ export class EmptyAppConfigSnapshot {
   read(): ResolvedConfig {
     return {};
   }
+
+  /** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
+  get path(): string {
+    return resolveAppConfigPath(this.program);
+  }
 }
 
 /** Resolved config for handlers with program.appConfig set. */
@@ -70,6 +77,11 @@ export class AppConfigSnapshot {
     return { ...this.snapshot };
   }
 
+  /** Resolved absolute path to the app JSON config file (honors `program.appConfig.path` or OS default). */
+  get path(): string {
+    return resolveAppConfigPath(this.program);
+  }
+
   /** Replace snapshot after external bootstrap (internal). */
   refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void {
     this.fileData = { ...fileData };
@@ -92,7 +104,7 @@ export function createAppConfigSnapshot(
   resolved: ResolvedConfig,
 ): AnyAppConfigSnapshot {
   if (!program.appConfig) {
-    return new EmptyAppConfigSnapshot();
+    return new EmptyAppConfigSnapshot(program);
   }
   return new AppConfigSnapshot(program, fileData, resolved);
 }

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/context.ts

@@ -38,7 +38,7 @@ export class CliContext {
     opts: Record<string, string>,
     program: CliProgram,
     invocation: CliInvocation = "cli",
-    appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(),
+    appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
   ) {
     this.appName = appName;
     this.commandPath = commandPath;

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