argsbarg 4.0.2 → 4.0.3

package/CHANGELOG.md

@@ -7,6 +7,9 @@ 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
 
 
@@ -455,7 +458,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.2...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

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`, `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.2",
+  "version": "4.0.3",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

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