argsbarg 4.0.1 → 4.0.3

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.3] - 2026-06-24
+
+
+## [4.0.2] - 2026-06-24
+
+
 ## [4.0.1] - 2026-06-24
 
 
@@ -452,7 +458,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.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.0.3...HEAD
+[4.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.3
+[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,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`, `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`).
+**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` in handlers; env export remains for subprocess inheritance. `path` is the resolved absolute config file path; `dir` is its parent directory (both honor `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`, `path` — prefer over `process.env` |
+| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `path`, `dir` — 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

@@ -10,6 +10,8 @@ declare class EmptyAppConfigSnapshot {
 	read(): ResolvedConfig;
 	/** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
 	get path(): string;
+	/** Resolved absolute directory containing the config file. */
+	get dir(): string;
 }
 declare class AppConfigSnapshot {
 	private readonly program;
@@ -22,6 +24,8 @@ declare class AppConfigSnapshot {
 	read(): ResolvedConfig;
 	/** Resolved absolute path to the app JSON config file (honors `program.appConfig.path` or OS default). */
 	get path(): string;
+	/** Resolved absolute directory containing the config file. */
+	get dir(): 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.1",
+  "version": "4.0.3",
   "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

@@ -1,9 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { CliProgram } from "../types.ts";
 import { createAppConfigSnapshot } from "./context.ts";
+import { resolveAppConfigDir } from "./file.ts";
 import { resolveAppConfig } from "./resolve.ts";
 
 function configProgram(configPath: string): CliProgram {
@@ -37,6 +38,7 @@ describe("config/context", () => {
       expect(ctx.get("note")).toBe("hello");
       expect(ctx.require("apiToken")).toBe("tok");
       expect(ctx.path).toBe(path);
+      expect(ctx.dir).toBe(dirname(path));
 
       ctx.set("note", "updated");
       expect(ctx.get("note")).toBe("updated");
@@ -60,6 +62,7 @@ describe("config/context", () => {
     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);
+    expect(empty.dir).toBe(dirname(empty.path));
   });
 
   test("AppConfigSnapshot path uses OS default when program.appConfig.path omitted", () => {
@@ -75,5 +78,12 @@ describe("config/context", () => {
     const ctx = createAppConfigSnapshot(program, {}, {});
     expect(ctx.path).toContain("ctx_test");
     expect(ctx.path.endsWith("/config") || ctx.path.endsWith("\\config")).toBe(true);
+    expect(ctx.dir).toBe(resolveAppConfigDir(program));
+    expect(ctx.dir).toBe(dirname(ctx.path));
+  });
+
+  test("resolveAppConfigDir honors custom program.appConfig.path", () => {
+    const program = configProgram("/tmp/custom/settings.json");
+    expect(resolveAppConfigDir(program)).toBe("/tmp/custom");
   });
 });

package/src/config/context.ts

@@ -3,7 +3,7 @@ Handler-facing resolved app config snapshot (ctx.appConfig).
 */
 
 import type { CliProgram } from "../types.ts";
-import { resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
+import { resolveAppConfigDir, resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
 import type { ResolvedConfig } from "./resolve.ts";
 import { exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
 
@@ -31,6 +31,11 @@ export class EmptyAppConfigSnapshot {
   get path(): string {
     return resolveAppConfigPath(this.program);
   }
+
+  /** Resolved absolute directory containing the config file. */
+  get dir(): string {
+    return resolveAppConfigDir(this.program);
+  }
 }
 
 /** Resolved config for handlers with program.appConfig set. */
@@ -82,6 +87,11 @@ export class AppConfigSnapshot {
     return resolveAppConfigPath(this.program);
   }
 
+  /** Resolved absolute directory containing the config file. */
+  get dir(): string {
+    return resolveAppConfigDir(this.program);
+  }
+
   /** Replace snapshot after external bootstrap (internal). */
   refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void {
     this.fileData = { ...fileData };

package/src/config/file.ts

@@ -22,6 +22,11 @@ export function resolveAppConfigPath(program: CliProgram): string {
   return join(appConfigHome(), dirName, "config");
 }
 
+/** Resolved absolute directory containing the app JSON config file. */
+export function resolveAppConfigDir(program: CliProgram): string {
+  return dirname(resolveAppConfigPath(program));
+}
+
 /** Human-readable config path for error messages (`~` when under home). */
 export function displayAppConfigPath(program: CliProgram): string {
   const resolved = resolveAppConfigPath(program);

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