argsbarg 4.0.4 → 4.1.1

package/src/config/file.test.ts

@@ -1,10 +1,16 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } 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 { bootstrapAppConfig } from "./bootstrap.ts";
-import { readAppConfigFile, resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
+import {
+  readAppConfigFile,
+  resolveAppConfigDir,
+  resolveAppConfigPath,
+  uninstallAppConfig,
+  writeAppConfigFile,
+} from "./file.ts";
 import { buildProgramUserConfig } from "./manifest.ts";
 import { formatMissingConfigMessage, missingRequiredConfig, resolveAppConfig } from "./resolve.ts";
 
@@ -13,7 +19,6 @@ const program: CliProgram = {
   version: "1.0.0",
   description: "Demo.",
   appConfig: {
-    path: "~/.config/myapp-test/config",
     entries: {
       apiToken: { description: "Token.", env: "API_TOKEN" },
       port: { description: "HTTP listen port (default 8080).", required: false },
@@ -22,6 +27,19 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+function withHome<T>(fn: (home: string) => T): T {
+  const home = mkdtempSync(join(tmpdir(), "cfg-test-"));
+  const prevHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    return fn(home);
+  } finally {
+    if (prevHome === undefined) delete process.env.HOME;
+    else process.env.HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
 describe("config/file", () => {
   test("buildProgramUserConfig from program.appConfig env entries", () => {
     const cfg = buildProgramUserConfig(program);
@@ -33,31 +51,29 @@ describe("config/file", () => {
     expect(cfg?.port).toBeUndefined();
   });
 
+  test("resolveAppConfigPath uses config.json", () => {
+    withHome((home) => {
+      expect(resolveAppConfigPath(program)).toBe(
+        join(home, ".local", "lib", "myapp", "config.json"),
+      );
+    });
+  });
+
   test("resolveAppConfig prefers host env over file", () => {
-    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
-    const prevToken = process.env.API_TOKEN;
-    process.env.API_TOKEN = "from-host";
-    try {
-      const p: CliProgram = {
-        ...program,
-        appConfig: {
-          ...program.appConfig!,
-          path: join(dir, ".config", "myapp-test", "config"),
-        },
-      };
-      mkdirSync(join(dir, ".config", "myapp-test"), { recursive: true });
-      writeFileSync(resolveAppConfigPath(p), `${JSON.stringify({ apiToken: "from-file" })}\n`);
-      const resolved = resolveAppConfig(p, { apiToken: "from-file" });
-      expect(resolved.apiToken).toBe("from-host");
-    } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
-      if (prevToken === undefined) delete process.env.API_TOKEN;
-      else process.env.API_TOKEN = prevToken;
-      rmSync(dir, { recursive: true, force: true });
-    }
+    withHome((_home) => {
+      const prevToken = process.env.API_TOKEN;
+      process.env.API_TOKEN = "from-host";
+      try {
+        const configPath = resolveAppConfigPath(program);
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, `${JSON.stringify({ apiToken: "from-file" })}\n`);
+        const resolved = resolveAppConfig(program, { apiToken: "from-file" });
+        expect(resolved.apiToken).toBe("from-host");
+      } finally {
+        if (prevToken === undefined) delete process.env.API_TOKEN;
+        else process.env.API_TOKEN = prevToken;
+      }
+    });
   });
 
   test("missingRequiredConfig and formatMissingConfigMessage", () => {
@@ -76,37 +92,31 @@ describe("config/file", () => {
   });
 
   test("rejects unknown keys on read", () => {
-    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
-    try {
-      const p: CliProgram = {
-        ...program,
-        appConfig: {
-          ...program.appConfig!,
-          path: join(dir, "config"),
-        },
-      };
-      writeFileSync(join(dir, "config"), `${JSON.stringify({ extra: true })}\n`);
-      expect(() => readAppConfigFile(p)).toThrow(/Unknown config key/);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
+    withHome(() => {
+      const configPath = resolveAppConfigPath(program);
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, `${JSON.stringify({ extra: true })}\n`);
+      expect(() => readAppConfigFile(program)).toThrow(/Unknown config key/);
+    });
   });
 
   test("writeAppConfigFile round-trip", () => {
-    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
-    try {
-      const p: CliProgram = {
-        ...program,
-        appConfig: {
-          ...program.appConfig!,
-          path: join(dir, "config"),
-        },
-      };
-      writeAppConfigFile(p, { apiToken: "saved" });
-      const { resolved } = bootstrapAppConfig(p, { validateFile: true });
+    withHome(() => {
+      writeAppConfigFile(program, { apiToken: "saved" });
+      const { resolved } = bootstrapAppConfig(program, { validateFile: true });
       expect(resolved.apiToken).toBe("saved");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
+    });
+  });
+
+  test("uninstallAppConfig removes config directory recursively", () => {
+    withHome(() => {
+      writeAppConfigFile(program, { apiToken: "saved" });
+      const configPath = resolveAppConfigPath(program);
+      const configDir = resolveAppConfigDir(program);
+      writeFileSync(join(configDir, "extra.txt"), "leftover", "utf8");
+      expect(uninstallAppConfig(program, false)).toEqual([configPath, `${configDir}/`]);
+      expect(existsSync(configPath)).toBe(false);
+      expect(existsSync(configDir)).toBe(false);
+    });
   });
 });

package/src/config/file.ts

@@ -2,24 +2,20 @@
 JSON app config file path helpers and strict read/write.
 */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { sanitizeToolSegment } from "../mcp/tools.ts";
-import { appConfigHome, expandTilde } from "../paths/host.ts";
+import { appConfigLibHome, displayHomePath } from "../paths/host.ts";
 import type { CliProgram } from "../types.ts";
 import { effectiveJsonSchema } from "./schema.ts";
 import { validateConfigDocument } from "./validate.ts";
 
 export type AppConfigFileData = Record<string, unknown>;
 
-/** Resolved absolute path to the app JSON config file. */
+/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
 export function resolveAppConfigPath(program: CliProgram): string {
-  const custom = program.appConfig?.path;
-  if (custom) {
-    return expandTilde(custom);
-  }
   const dirName = sanitizeToolSegment(program.key);
-  return join(appConfigHome(), dirName, "config");
+  return join(appConfigLibHome(), dirName, "config.json");
 }
 
 /** Resolved absolute directory containing the app JSON config file. */
@@ -27,14 +23,9 @@ export function resolveAppConfigDir(program: CliProgram): string {
   return dirname(resolveAppConfigPath(program));
 }
 
-/** Human-readable config path for error messages (`~` when under home). */
+/** Human-readable config path for error messages (`~/…` when under home). */
 export function displayAppConfigPath(program: CliProgram): string {
-  const resolved = resolveAppConfigPath(program);
-  const home = process.env.HOME ?? "";
-  if (home.length > 0 && resolved.startsWith(home)) {
-    return `~${resolved.slice(home.length)}`;
-  }
-  return resolved;
+  return displayHomePath(resolveAppConfigPath(program));
 }
 
 function parseConfigJson(text: string, path: string): AppConfigFileData {
@@ -46,7 +37,7 @@ function parseConfigJson(text: string, path: string): AppConfigFileData {
     return parsed as AppConfigFileData;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Invalid JSON in config file ${path}: ${msg}`);
+    throw new Error(`Invalid JSON in config file ${displayHomePath(path)}: ${msg}`);
   }
 }
 
@@ -60,7 +51,7 @@ export function readAppConfigFileRaw(path: string): AppConfigFileData {
     text = readFileSync(path, "utf8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Could not read config file ${path}: ${msg}`);
+    throw new Error(`Could not read config file ${displayHomePath(path)}: ${msg}`);
   }
   return parseConfigJson(text, path);
 }
@@ -89,7 +80,7 @@ export function validateAppConfigData(
   const allowed = new Set(Object.keys(appConfig.entries));
   for (const key of Object.keys(data)) {
     if (!allowed.has(key)) {
-      const where = pathLabel ?? "config";
+      const where = pathLabel ? displayHomePath(pathLabel) : "config";
       throw new Error(`Unknown config key '${key}' in ${where}`);
     }
   }
@@ -99,7 +90,7 @@ export function validateAppConfigData(
   }
   const result = validateConfigDocument(data, jsonSchema);
   if (!result.valid) {
-    const where = pathLabel ?? "config";
+    const where = pathLabel ? displayHomePath(pathLabel) : "config";
     throw new Error(`Invalid config in ${where}: ${result.errors.join("; ")}`);
   }
 }
@@ -112,14 +103,31 @@ export function writeAppConfigFile(program: CliProgram, data: AppConfigFileData)
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
 }
 
-/** Removes the app config file when present. Returns true if removed. */
-export function uninstallAppConfig(program: CliProgram, dry: boolean): boolean {
+/** True when the app config file or config directory is present. */
+export function appConfigInstalled(program: CliProgram): boolean {
   const path = resolveAppConfigPath(program);
-  if (!existsSync(path)) {
-    return false;
+  if (existsSync(path)) return true;
+  return existsSync(resolveAppConfigDir(program));
+}
+
+/** Removes the app config file and config directory when present. */
+export function uninstallAppConfig(program: CliProgram, dry: boolean): string[] {
+  const path = resolveAppConfigPath(program);
+  const dir = resolveAppConfigDir(program);
+  const hasFile = existsSync(path);
+  const hasDir = existsSync(dir);
+
+  if (!hasFile && !hasDir) {
+    return [];
   }
+
+  const changed: string[] = [];
+  if (hasFile) changed.push(path);
+  if (hasDir) changed.push(`${dir}/`);
+
   if (!dry) {
-    unlinkSync(path);
+    if (hasFile) unlinkSync(path);
+    if (hasDir) rmSync(dir, { recursive: true, force: true });
   }
-  return true;
+  return changed;
 }

package/src/config/resolve.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
-import { resolveAppConfig } from "./resolve.ts";
+import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
 
 const program: CliProgram = {
   key: "app",
@@ -85,4 +85,195 @@ describe("config/resolve", () => {
     const resolved = resolveAppConfig(stringProgram, {});
     expect(resolved.greeting).toBe("world");
   });
+
+  test("prefers captured host env over file when process.env was exported from file", () => {
+    const hostEnv = { API_TOKEN: "from-host" };
+    process.env.API_TOKEN = "from-file-export";
+    try {
+      const resolved = resolveAppConfig(program, { apiToken: "from-file" }, hostEnv);
+      expect(resolved.apiToken).toBe("from-host");
+    } finally {
+      delete process.env.API_TOKEN;
+    }
+  });
+
+  test("exportConfigToEnv does not overwrite host env", () => {
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-host";
+    const hostEnv = captureMappedHostEnv(program);
+    try {
+      exportConfigToEnv(program, { apiToken: "from-file" }, hostEnv);
+      expect(process.env.API_TOKEN).toBe("from-host");
+    } finally {
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("resolve callback supplies value when env and file are absent", () => {
+    const resolveProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        ...program.appConfig!,
+        entries: {
+          ...program.appConfig!.entries,
+          apiToken: {
+            description: "Token.",
+            env: "API_TOKEN",
+            resolve: () => "from-resolve",
+          },
+        },
+      },
+    };
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const resolved = resolveAppConfig(resolveProgram, {});
+      expect(resolved.apiToken).toBe("from-resolve");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("env overrides resolve callback", () => {
+    const resolveProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        ...program.appConfig!,
+        entries: {
+          ...program.appConfig!.entries,
+          apiToken: {
+            description: "Token.",
+            env: "API_TOKEN",
+            resolve: () => "from-resolve",
+          },
+        },
+      },
+    };
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-env";
+    try {
+      const resolved = resolveAppConfig(resolveProgram, {});
+      expect(resolved.apiToken).toBe("from-env");
+    } finally {
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("file overrides resolve callback", () => {
+    const resolveProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        ...program.appConfig!,
+        entries: {
+          ...program.appConfig!.entries,
+          apiToken: {
+            description: "Token.",
+            env: "API_TOKEN",
+            resolve: () => "from-resolve",
+          },
+        },
+      },
+    };
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const resolved = resolveAppConfig(resolveProgram, { apiToken: "from-file" });
+      expect(resolved.apiToken).toBe("from-file");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("falls back to env when resolve returns undefined", () => {
+    const resolveProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        ...program.appConfig!,
+        entries: {
+          ...program.appConfig!.entries,
+          apiToken: {
+            description: "Token.",
+            env: "API_TOKEN",
+            resolve: () => undefined,
+          },
+        },
+      },
+    };
+    const hostEnv = { API_TOKEN: "from-env-fallback" };
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const resolved = resolveAppConfig(resolveProgram, {}, hostEnv);
+      expect(resolved.apiToken).toBe("from-env-fallback");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("resolve callback is skipped when env is set", () => {
+    let resolveCalled = false;
+    const resolveProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        ...program.appConfig!,
+        entries: {
+          ...program.appConfig!.entries,
+          apiToken: {
+            description: "Token.",
+            env: "API_TOKEN",
+            resolve: () => {
+              resolveCalled = true;
+              return "from-resolve";
+            },
+          },
+        },
+      },
+    };
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-env";
+    try {
+      const resolved = resolveAppConfig(resolveProgram, {});
+      expect(resolved.apiToken).toBe("from-env");
+      expect(resolveCalled).toBe(false);
+    } finally {
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("async resolve is ignored with stderr warning", () => {
+    const resolveProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        ...program.appConfig!,
+        entries: {
+          ...program.appConfig!.entries,
+          apiToken: {
+            description: "Token.",
+            env: "API_TOKEN",
+            resolve: async () => "from-async-resolve",
+          },
+        },
+      },
+    };
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    const prevStderr = process.stderr.write;
+    const stderrLines: string[] = [];
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderrLines.push(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+    try {
+      const resolved = resolveAppConfig(resolveProgram, {}, { API_TOKEN: undefined });
+      expect(resolved.apiToken).toBeUndefined();
+      expect(stderrLines.join("")).toContain("returned a Promise");
+    } finally {
+      process.stderr.write = prevStderr;
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
 });

package/src/config/resolve.ts

@@ -2,7 +2,7 @@
 Resolve program.appConfig values: defaults, file, env override, export to process.env.
 */
 
-import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+import type { CliAppConfigEntry, CliAppConfigResolveContext, CliProgram } from "../types.ts";
 import { configEntryRequired, jsonSchemaRequiredKeys } from "./entry.ts";
 import type { AppConfigFileData } from "./file.ts";
 import { displayAppConfigPath } from "./file.ts";
@@ -20,8 +20,26 @@ function isPresent(value: unknown): boolean {
   return true;
 }
 
-function envOverrideValue(envName: string): string | undefined {
-  const val = process.env[envName];
+/** Snapshot mapped host env at bootstrap entry (before file exports mutate process.env). */
+export function captureMappedHostEnv(program: CliProgram): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = {};
+  const entries = program.appConfig?.entries;
+  if (!entries) {
+    return out;
+  }
+  for (const entry of Object.values(entries)) {
+    if (entry.env) {
+      out[entry.env] = process.env[entry.env];
+    }
+  }
+  return out;
+}
+
+function envOverrideValue(
+  envName: string,
+  hostEnv?: Record<string, string | undefined>,
+): string | undefined {
+  const val = hostEnv && envName in hostEnv ? hostEnv[envName] : process.env[envName];
   if (val === undefined || val.length === 0) {
     return undefined;
   }
@@ -55,15 +73,19 @@ function coerceEnvValue(program: CliProgram, key: string, raw: string): unknown
   return raw;
 }
 
-/** Resolve all schema keys from file data and process.env. */
-export function resolveAppConfig(program: CliProgram, fileData: AppConfigFileData): ResolvedConfig {
+/** Resolve all schema keys from file data and mapped host env (env wins over file). */
+export function resolveAppConfig(
+  program: CliProgram,
+  fileData: AppConfigFileData,
+  hostEnv?: Record<string, string | undefined>,
+): ResolvedConfig {
   const appConfig = program.appConfig;
   if (!appConfig) {
     return {};
   }
   const out: ResolvedConfig = {};
   for (const [key, entry] of Object.entries(appConfig.entries)) {
-    const value = resolveConfigKey(program, key, entry, fileData);
+    const value = resolveConfigKey(program, key, entry, fileData, hostEnv);
     if (value !== undefined) {
       out[key] = value;
     }
@@ -71,21 +93,66 @@ export function resolveAppConfig(program: CliProgram, fileData: AppConfigFileDat
   return out;
 }
 
+function tryEnvOverride(
+  program: CliProgram,
+  key: string,
+  entry: CliAppConfigEntry,
+  hostEnv?: Record<string, string | undefined>,
+): unknown {
+  if (!entry.env) {
+    return undefined;
+  }
+  const fromEnv = envOverrideValue(entry.env, hostEnv);
+  if (fromEnv === undefined) {
+    return undefined;
+  }
+  return coerceEnvValue(program, key, fromEnv);
+}
+
+function buildResolveContext(
+  program: CliProgram,
+  key: string,
+  entry: CliAppConfigEntry,
+  fileData: AppConfigFileData,
+  hostEnv?: Record<string, string | undefined>,
+): CliAppConfigResolveContext {
+  return {
+    key,
+    entry,
+    program,
+    fileValue: fileData[key],
+    envValue: entry.env ? envOverrideValue(entry.env, hostEnv) : undefined,
+  };
+}
+
 function resolveConfigKey(
   program: CliProgram,
   key: string,
   entry: CliAppConfigEntry,
   fileData: AppConfigFileData,
+  hostEnv?: Record<string, string | undefined>,
 ): unknown {
-  if (entry.env) {
-    const fromEnv = envOverrideValue(entry.env);
-    if (fromEnv !== undefined) {
-      return coerceEnvValue(program, key, fromEnv);
-    }
+  const fromEnv = tryEnvOverride(program, key, entry, hostEnv);
+  if (fromEnv !== undefined) {
+    return fromEnv;
   }
   if (key in fileData && isPresent(fileData[key])) {
     return fileData[key];
   }
+  if (entry.resolve) {
+    const fromResolve = entry.resolve(buildResolveContext(program, key, entry, fileData, hostEnv));
+    if (fromResolve != null && typeof (fromResolve as Promise<unknown>).then === "function") {
+      process.stderr.write(
+        `[argsbarg] config "${key}": resolve() returned a Promise; use a synchronous resolver (e.g. Bun.spawnSync with piped stdout).\n`,
+      );
+    } else if (isPresent(fromResolve)) {
+      return fromResolve;
+    }
+  }
+  const fromEnvFallback = tryEnvOverride(program, key, entry, hostEnv);
+  if (fromEnvFallback !== undefined) {
+    return fromEnvFallback;
+  }
   const def = schemaDefaultForKey(program, key);
   if (def !== undefined) {
     return def;
@@ -93,8 +160,12 @@ function resolveConfigKey(
   return undefined;
 }
 
-/** Write mapped config values to process.env for subprocess inheritance. */
-export function exportConfigToEnv(program: CliProgram, resolved: ResolvedConfig): void {
+/** Write mapped config values to process.env for subprocess inheritance (never overwrites host env). */
+export function exportConfigToEnv(
+  program: CliProgram,
+  resolved: ResolvedConfig,
+  hostEnv?: Record<string, string | undefined>,
+): void {
   const appConfig = program.appConfig;
   if (!appConfig) {
     return;
@@ -103,6 +174,14 @@ export function exportConfigToEnv(program: CliProgram, resolved: ResolvedConfig)
     if (!entry.env) {
       continue;
     }
+    const captured = hostEnv?.[entry.env];
+    if (captured !== undefined && captured.length > 0) {
+      continue;
+    }
+    const existing = process.env[entry.env];
+    if (existing !== undefined && existing.length > 0) {
+      continue;
+    }
     const value = resolved[key];
     if (!isPresent(value)) {
       continue;