argsbarg 4.0.0 → 4.0.1

package/CHANGELOG.md

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

@@ -431,7 +431,7 @@ await cli.run();
 
 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.1",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

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