argsbarg 4.0.4 → 4.1.1

package/src/cli-tool/run-create.ts

@@ -0,0 +1,149 @@
+/** `argsbarg create` command orchestration. */
+
+import { mkdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import {
+  applyCreate,
+  type CreateOptions,
+  classNameFromKey,
+  diffCreateDetails,
+  parseCreateArgv,
+  printCreateDiffs,
+  renderCreateTree,
+  resolveCreateOptions,
+} from "./create.ts";
+import { printPostCreatePlan, runPostCreate } from "./post-create.ts";
+import { promptConfirm, promptOptional, promptRequired } from "./prompt.ts";
+
+function isInteractiveTty(): boolean {
+  return Boolean(process.stdin.isTTY);
+}
+
+function collectInteractiveOptions(
+  partial: Partial<CreateOptions>,
+  dir: string,
+): { opts: CreateOptions; baseDir: string } {
+  process.stderr.write("Argsbarg create — bootstrap a new CLI from full-example\n\n");
+  const targetDir = promptOptional("Target directory", dir) ?? dir;
+  const baseDir = resolve(process.cwd(), targetDir);
+  const key = promptRequired("CLI key (binary name)", partial.key);
+  const className =
+    promptOptional("Formula class name", partial.className ?? classNameFromKey(key)) ??
+    classNameFromKey(key);
+  const releaseRepo =
+    promptOptional("GitHub release repo (org/repo)", partial.releaseRepo ?? `example/${key}`) ??
+    `example/${key}`;
+  const homepage =
+    promptOptional("Homepage URL", partial.homepage ?? `https://github.com/${releaseRepo}`) ??
+    `https://github.com/${releaseRepo}`;
+  const tap =
+    promptOptional("Homebrew tap (org/repo)", partial.tap ?? `local/${key}`) ?? `local/${key}`;
+  const desc =
+    promptOptional("Formula description", partial.desc ?? `${className} CLI`) ?? `${className} CLI`;
+
+  const opts = resolveCreateOptions(
+    {
+      ...partial,
+      key,
+      className,
+      tap,
+      homepage,
+      releaseRepo,
+      desc,
+      force: partial.force ?? false,
+    },
+    baseDir,
+  );
+
+  process.stderr.write(`\nTarget: ${baseDir}\n`);
+  process.stderr.write(`Key: ${opts.key}  Class: ${opts.className}  Tap: ${opts.tap}\n\n`);
+  const tree = renderCreateTree(opts);
+  process.stderr.write(`Files (${tree.size}):\n`);
+  for (const rel of [...tree.keys()].sort()) {
+    process.stderr.write(`  ${rel}\n`);
+  }
+  process.stderr.write("\n");
+  printPostCreatePlan();
+  process.stderr.write("\n");
+
+  if (!promptConfirm("Proceed")) {
+    throw new Error("Aborted.");
+  }
+
+  return { opts, baseDir };
+}
+
+export async function runCreate(input: Partial<CreateOptions> & { dir?: string }): Promise<number> {
+  try {
+    const baseDir = resolve(process.cwd(), input.dir ?? ".");
+    const partial = { ...input };
+    delete (partial as { dir?: string }).dir;
+
+    if (partial.check || partial.diff) {
+      const drifts = diffCreateDetails(baseDir, partial);
+      if (drifts.length > 0) {
+        process.stderr.write(`Create drift in ${baseDir}:\n`);
+        for (const d of drifts) process.stderr.write(`  ${d.rel}\n`);
+        if (partial.diff) printCreateDiffs(drifts, baseDir);
+        return 1;
+      }
+      process.stdout.write(`Create OK: ${baseDir}\n`);
+      return 0;
+    }
+
+    let opts: CreateOptions;
+    if (!partial.yes && isInteractiveTty()) {
+      const collected = collectInteractiveOptions(partial, input.dir ?? ".");
+      opts = collected.opts;
+      return runCreateApply(collected.baseDir, opts, partial.dryRun ?? false);
+    }
+
+    if (!partial.yes && !isInteractiveTty()) {
+      throw new Error("Refusing to proceed without --yes (stdin is not a TTY).");
+    }
+    if (!partial.key) {
+      throw new Error("--key is required in non-interactive mode.");
+    }
+    opts = resolveCreateOptions(partial, baseDir);
+    return runCreateApply(baseDir, opts, partial.dryRun ?? false);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}
+
+async function runCreateApply(
+  baseDir: string,
+  opts: CreateOptions,
+  dryRun: boolean,
+): Promise<number> {
+  if (dryRun) {
+    const written = applyCreate(baseDir, { ...opts, dryRun: true, check: false });
+    process.stdout.write(`Would write ${written.length} file(s) under ${baseDir}\n`);
+    for (const w of written) process.stdout.write(`  ${relative(baseDir, w) || w}\n`);
+    printPostCreatePlan();
+    return 0;
+  }
+
+  mkdirSync(baseDir, { recursive: true });
+  const written = applyCreate(baseDir, {
+    ...opts,
+    dryRun: false,
+    check: false,
+    force: opts.force,
+  });
+  process.stdout.write(`Created ${written.length} file(s) under ${baseDir}\n`);
+  for (const w of written) {
+    process.stdout.write(`  ${relative(baseDir, w) || w}\n`);
+  }
+
+  await runPostCreate(baseDir, false);
+  process.stdout.write("Done.\n");
+  return 0;
+}
+
+/** Parse argv and run create (for tests and direct script invocation). */
+export async function runCreateCommand(rest: string[]): Promise<number> {
+  const { dir, opts } = parseCreateArgv(rest);
+  return runCreate({ ...opts, dir });
+}

package/src/config/bootstrap.ts

@@ -1,8 +1,10 @@
 /*
-Bootstrap: load config, validate, resolve, export, TTY prompts, install --configure.
+Loads the app config file, runs setup prompts when needed, and checks that required
+settings are present before the CLI or MCP server handles a request.
 */
 
-import { existsSync, readSync } from "node:fs";
+import { readSync } from "node:fs";
+import { readPromptLine as readStdinLine } from "../prompt.ts";
 import type { CliAppConfigEntry, CliProgram } from "../types.ts";
 import {
   configEntryRequired,
@@ -11,6 +13,7 @@ import {
   jsonSchemaRequiredKeys,
 } from "./entry.ts";
 import {
+  appConfigInstalled,
   displayAppConfigPath,
   readAppConfigFile,
   readAppConfigFileRaw,
@@ -19,6 +22,7 @@ import {
 } from "./file.ts";
 import type { ResolvedConfig } from "./resolve.ts";
 import {
+  captureMappedHostEnv,
   exportConfigToEnv,
   formatMissingConfigMessage,
   missingRequiredConfig,
@@ -27,87 +31,169 @@ import {
 } from "./resolve.ts";
 import { effectiveJsonSchema } from "./schema.ts";
 
+export { displayAppConfigPath } from "./file.ts";
+
+/** Tells ensureAppConfig whether to prompt the user and how strictly to require settings. */
 export interface EnsureAppConfigOpts {
+  /** In a terminal, ask for any required settings that are still empty (or run the full configure wizard). */
   interactive: boolean;
+  /** Stop the program with an error if required settings are still missing after loading. */
   exitOnMissing: boolean;
+  /** With `interactive`, walk through every setting instead of only the missing required ones. */
   configure?: boolean;
 }
 
+/** Config as read from disk, plus the final values after env vars and defaults are applied. */
 export interface ConfigBootstrapResult {
+  /** Key/value pairs stored in the config file. */
   fileData: Record<string, unknown>;
+  /** Effective values the app will use (file, defaults, and shell env combined). */
   resolved: ResolvedConfig;
 }
 
-/** Load, validate, resolve, and export config. */
+/** Read the config file, merge env overrides, and export mapped values into `process.env`. */
 export function bootstrapAppConfig(
   program: CliProgram,
   opts: { validateFile: boolean },
 ): ConfigBootstrapResult {
-  const path = resolveAppConfigPath(program);
-  const fileData = opts.validateFile ? readAppConfigFile(program) : readAppConfigFileRaw(path);
-  const resolved = resolveAppConfig(program, fileData);
-  exportConfigToEnv(program, resolved);
+  const fileData = opts.validateFile
+    ? readAppConfigFile(program)
+    : readAppConfigFileRaw(resolveAppConfigPath(program));
+  const hostEnv = captureMappedHostEnv(program);
+  const resolved = resolveAppConfig(program, fileData, hostEnv);
+  exportConfigToEnv(program, resolved, hostEnv);
   return { fileData, resolved };
 }
 
-function readPromptLine(mask: boolean): string {
-  if (!mask) {
-    const buf = Buffer.alloc(4096);
-    const n = readSync(0, buf, { length: 4096 });
-    return buf.toString("utf8", 0, n).replace(/\r?\n$/, "");
-  }
-  let result = "";
-  const buf = Buffer.alloc(1);
-  while (true) {
-    const n = readSync(0, buf, { length: 1 });
-    if (n <= 0) {
-      break;
-    }
-    const byte = buf[0];
-    if (byte === undefined) {
-      continue;
+/** Read a line from the terminal without showing what the user types (for tokens and passwords). */
+function readSensitiveLine(): string {
+  const stdin = process.stdin;
+  const canRaw = stdin.isTTY && typeof stdin.setRawMode === "function";
+  const wasRaw = canRaw && stdin.isRaw;
+  if (canRaw) {
+    try {
+      stdin.setRawMode(true);
+    } catch {
+      // Best-effort: read still works if raw mode is unavailable.
     }
-    if (byte === 10 || byte === 13) {
-      break;
+  }
+  try {
+    let result = "";
+    const buf = Buffer.alloc(1);
+    while (true) {
+      const n = readSync(0, buf, { length: 1 });
+      if (n <= 0) {
+        break;
+      }
+      const byte = buf[0];
+      if (byte === 3) {
+        // Raw mode delivers Ctrl+C as ETX instead of SIGINT.
+        process.stderr.write("\n");
+        process.exit(130);
+      }
+      if (byte === 4) {
+        break;
+      }
+      if (byte === 10 || byte === 13) {
+        break;
+      }
+      if (byte === 127 || byte === 8) {
+        if (result.length > 0) {
+          result = result.slice(0, -1);
+          process.stderr.write("\b \b");
+        }
+        continue;
+      }
+      result += String.fromCharCode(byte);
+      process.stderr.write("*");
     }
-    if (byte === 127 || byte === 8) {
-      result = result.slice(0, -1);
-      continue;
+    process.stderr.write("\n");
+    return result;
+  } finally {
+    if (canRaw) {
+      try {
+        stdin.setRawMode(!!wasRaw);
+      } catch {
+        // Ignore restore failures.
+      }
     }
-    result += String.fromCharCode(byte);
-    process.stderr.write("*");
   }
-  process.stderr.write("\n");
-  return result;
 }
 
+/** Read one line of user input; sensitive settings use a hidden prompt. */
+function readPromptLine(mask: boolean): string {
+  if (mask) {
+    return readSensitiveLine();
+  }
+  return readStdinLine();
+}
+
+/** Whether this setting already has a non-empty value in the user's shell environment. */
+function resolvedFromEnv(
+  entry: CliAppConfigEntry,
+  hostEnv: Record<string, string | undefined>,
+): boolean {
+  if (!entry.env) {
+    return false;
+  }
+  const val = hostEnv[entry.env];
+  return val !== undefined && val.length > 0;
+}
+
+/** Ask the user for one setting and return what they chose (or nothing if they skipped it). */
 function promptConfigKey(
   key: string,
   entry: CliAppConfigEntry,
   current: unknown,
   configure: boolean,
   jsonSchemaRequired: Set<string> | undefined,
-): unknown {
-  const title = entry.title ?? defaultConfigEntryTitle(key);
+  hostEnv: Record<string, string | undefined>,
+): { value: unknown; userTyped: boolean } {
+  const baseTitle = entry.title ?? defaultConfigEntryTitle(key);
+  const titleWithEnv = entry.env ? `${baseTitle} (${entry.env})` : baseTitle;
   const required = configEntryRequired(key, entry, jsonSchemaRequired);
-  const heading = required || !configure ? title : `${title} (optional)`;
+  const heading = required || !configure ? titleWithEnv : `${titleWithEnv} (optional)`;
   process.stderr.write(`${heading}\n`);
   process.stderr.write(`  ${entry.description}\n`);
   const hasCurrent = current !== undefined && current !== null && String(current).length > 0;
+  const sensitive = configEntrySensitive(key, entry);
   if (hasCurrent) {
-    const sensitive = configEntrySensitive(key, entry);
-    process.stderr.write(`Current: ${sensitive ? "REDACTED" : stringifyConfigValue(current)}\n`);
-    process.stderr.write("Value (Enter to keep): ");
+    process.stderr.write(`  Current: ${sensitive ? "REDACTED" : stringifyConfigValue(current)}\n`);
+    const acceptPrompt = resolvedFromEnv(entry, hostEnv)
+      ? `  Value (Enter to copy from env): `
+      : `  Value (Enter to keep): `;
+    process.stderr.write(acceptPrompt);
   } else {
-    process.stderr.write("Value: ");
+    process.stderr.write(`  Value: `);
   }
-  const input = readPromptLine(hasCurrent && configEntrySensitive(key, entry));
+  const input = readPromptLine(sensitive);
   if (input.length === 0 && hasCurrent) {
-    return current;
+    return { value: current, userTyped: false };
   }
-  return input.length > 0 ? input : undefined;
+  if (input.length > 0) {
+    return { value: input, userTyped: true };
+  }
+  return { value: undefined, userTyped: false };
+}
+
+/** Options for the interactive `install --configure` wizard. */
+export interface RunInstallConfigureOpts {
+  /** Where the wizard was started from (standalone command vs right after install). */
+  context?: "standalone" | "after-install";
+}
+
+/** Print the "Configuration Setup" heading before the configure prompts. */
+function writeConfigureSetupHeading(): void {
+  process.stderr.write("\nConfiguration Setup\n\n");
+}
+
+/** Whether this app has any settings worth prompting during configure. */
+function shouldShowConfigureSetupHeading(program: CliProgram): boolean {
+  if (!program.appConfig) return false;
+  return Object.keys(program.appConfig.entries).length > 0;
 }
 
+/** Ask the user for each required setting that is still empty; returns updates to save to the config file. */
 function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   const appConfig = program.appConfig;
   const updates: Record<string, unknown> = {};
@@ -116,7 +202,9 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   }
   const jsonSchema = effectiveJsonSchema(program);
   const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const hostEnv = captureMappedHostEnv(program);
   const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  let headingWritten = false;
   for (const [key, entry] of Object.entries(appConfig.entries)) {
     if (!configEntryRequired(key, entry, fromSchema)) {
       continue;
@@ -125,7 +213,11 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
     if (current !== undefined && current !== null && String(current).length > 0) {
       continue;
     }
-    const value = promptConfigKey(key, entry, undefined, false, fromSchema);
+    if (!headingWritten) {
+      writeConfigureSetupHeading();
+      headingWritten = true;
+    }
+    const { value, userTyped } = promptConfigKey(key, entry, undefined, false, fromSchema, hostEnv);
     if (value !== undefined && String(value).length > 0) {
       updates[key] = value;
     }
@@ -133,8 +225,11 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   return updates;
 }
 
-/** Interactive `install --configure`. */
-export function runInstallConfigure(program: CliProgram): { path: string; changed: boolean } {
+/** Run the full interactive configure wizard (`install --configure`). */
+export function runInstallConfigure(
+  program: CliProgram,
+  _opts: RunInstallConfigureOpts = {},
+): { path: string; changed: boolean } {
   if (!program.appConfig) {
     throw new Error("install --configure requires program.appConfig on the program root.");
   }
@@ -151,17 +246,30 @@ export function runInstallConfigure(program: CliProgram): { path: string; change
 
   const path = resolveAppConfigPath(program);
   const existing = readAppConfigFileRaw(path);
+  const hostEnv = captureMappedHostEnv(program);
   const jsonSchema = effectiveJsonSchema(program);
   const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
-  const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  const resolved = resolveAppConfig(program, existing, hostEnv);
   const next: Record<string, unknown> = { ...existing };
   let changed = false;
 
+  if (shouldShowConfigureSetupHeading(program)) {
+    writeConfigureSetupHeading();
+  }
+
   for (const [key, entry] of Object.entries(program.appConfig.entries)) {
-    const current = resolved[key];
     const before = next[key];
-    const value = promptConfigKey(key, entry, current, true, fromSchema);
+    const current = resolved[key];
+    const { value, userTyped } = promptConfigKey(key, entry, current, true, fromSchema, hostEnv);
     if (value !== undefined && String(value).length > 0) {
+      const storedInFile =
+        key in existing &&
+        existing[key] !== undefined &&
+        existing[key] !== null &&
+        String(existing[key]).length > 0;
+      if (!userTyped && !storedInFile) {
+        continue;
+      }
       if (JSON.stringify(value) !== JSON.stringify(before)) {
         changed = true;
       }
@@ -171,14 +279,14 @@ export function runInstallConfigure(program: CliProgram): { path: string; change
 
   if (changed) {
     writeAppConfigFile(program, next);
-    const updated = resolveAppConfig(program, next);
-    exportConfigToEnv(program, updated);
+    const updated = resolveAppConfig(program, next, hostEnv);
+    exportConfigToEnv(program, updated, hostEnv);
     return { path, changed: true };
   }
   return { path, changed: false };
 }
 
-/** Config status for install --status (values never included). */
+/** Summary for `install --status`: config path, whether the file exists, and which required settings are set (never their values). */
 export function appConfigStatus(program: CliProgram):
   | {
       path: string;
@@ -189,15 +297,16 @@ export function appConfigStatus(program: CliProgram):
   if (!program.appConfig) {
     return undefined;
   }
-  const path = resolveAppConfigPath(program);
+  const path = displayAppConfigPath(program);
   let fileData: Record<string, unknown> = {};
   try {
     fileData = readAppConfigFile(program);
   } catch {
-    fileData = readAppConfigFileRaw(path);
+    fileData = readAppConfigFileRaw(resolveAppConfigPath(program));
   }
-  const resolved = resolveAppConfig(program, fileData);
-  exportConfigToEnv(program, resolved);
+  const hostEnv = captureMappedHostEnv(program);
+  const resolved = resolveAppConfig(program, fileData, hostEnv);
+  exportConfigToEnv(program, resolved, hostEnv);
   const jsonSchema = effectiveJsonSchema(program);
   const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
   const required = Object.entries(program.appConfig.entries)
@@ -207,10 +316,10 @@ export function appConfigStatus(program: CliProgram):
       set:
         resolved[key] !== undefined && resolved[key] !== null && String(resolved[key]).length > 0,
     }));
-  return { path, exists: existsSync(path), required };
+  return { path, exists: appConfigInstalled(program), required };
 }
 
-/** Loads config, optionally prompts, and enforces required keys. */
+/** Load config at startup, optionally prompt the user, and fail if required settings are still missing. */
 export function ensureAppConfig(
   program: CliProgram,
   opts: EnsureAppConfigOpts,
@@ -228,15 +337,16 @@ export function ensureAppConfig(
     process.exit(1);
   }
 
-  let resolved = resolveAppConfig(program, fileData);
-  exportConfigToEnv(program, resolved);
+  const hostEnv = captureMappedHostEnv(program);
+  let resolved = resolveAppConfig(program, fileData, hostEnv);
+  exportConfigToEnv(program, resolved, hostEnv);
 
   if (opts.interactive && process.stdin.isTTY) {
     if (opts.configure) {
-      runInstallConfigure(program);
+      runInstallConfigure(program, { context: "standalone" });
       fileData = readAppConfigFileRaw(resolveAppConfigPath(program));
-      resolved = resolveAppConfig(program, fileData);
-      exportConfigToEnv(program, resolved);
+      resolved = resolveAppConfig(program, fileData, hostEnv);
+      exportConfigToEnv(program, resolved, hostEnv);
       return { fileData, resolved };
     }
     const updates = promptMissingRequired(program);
@@ -244,8 +354,8 @@ export function ensureAppConfig(
       const merged = { ...fileData, ...updates };
       writeAppConfigFile(program, merged);
       fileData = merged;
-      resolved = resolveAppConfig(program, fileData);
-      exportConfigToEnv(program, resolved);
+      resolved = resolveAppConfig(program, fileData, hostEnv);
+      exportConfigToEnv(program, resolved, hostEnv);
     }
   }
 
@@ -261,5 +371,3 @@ export function ensureAppConfig(
 
   return { fileData, resolved };
 }
-
-export { displayAppConfigPath };

package/src/config/context.test.ts

@@ -4,33 +4,31 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import type { CliProgram } from "../types.ts";
 import { createAppConfigSnapshot } from "./context.ts";
-import { resolveAppConfigDir } from "./file.ts";
+import { resolveAppConfigDir, resolveAppConfigPath } from "./file.ts";
 import { resolveAppConfig } from "./resolve.ts";
 
-function configProgram(configPath: string): CliProgram {
-  return {
-    key: "ctx-test",
-    version: "1.0.0",
-    description: "Context test.",
-    appConfig: {
-      path: configPath,
-      entries: {
-        apiToken: { description: "Token.", env: "API_TOKEN" },
-        note: { description: "Note.", required: false },
-      },
+const program: CliProgram = {
+  key: "ctx-test",
+  version: "1.0.0",
+  description: "Context test.",
+  appConfig: {
+    entries: {
+      apiToken: { description: "Token.", env: "API_TOKEN" },
+      note: { description: "Note.", required: false },
     },
-    handler: () => {},
-  };
-}
+  },
+  handler: () => {},
+};
 
 describe("config/context", () => {
   test("AppConfigSnapshot get, require, read, set", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-test-"));
-    const path = join(dir, "config");
-    const program = configProgram(path);
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
     const prevToken = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
+      const path = resolveAppConfigPath(program);
       const fileData = { apiToken: "tok", note: "hello" };
       const resolved = resolveAppConfig(program, fileData);
       const ctx = createAppConfigSnapshot(program, fileData, resolved);
@@ -44,6 +42,8 @@ describe("config/context", () => {
       expect(ctx.get("note")).toBe("updated");
       expect(ctx.read().note).toBe("updated");
     } 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 });
@@ -51,39 +51,25 @@ describe("config/context", () => {
   });
 
   test("EmptyAppConfigSnapshot when program.appConfig unset", () => {
-    const program: CliProgram = {
+    const programWithoutConfig: CliProgram = {
       key: "x",
       version: "1.0.0",
       description: "No config.",
       handler: () => {},
     };
-    const empty = createAppConfigSnapshot(program, {}, {});
+    const empty = createAppConfigSnapshot(programWithoutConfig, {}, {});
     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);
+    expect(empty.path.endsWith("/config.json") || empty.path.endsWith("\\config.json")).toBe(true);
     expect(empty.dir).toBe(dirname(empty.path));
   });
 
-  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: () => {},
-    };
+  test("AppConfigSnapshot path uses OS default from program key", () => {
     const ctx = createAppConfigSnapshot(program, {}, {});
     expect(ctx.path).toContain("ctx_test");
-    expect(ctx.path.endsWith("/config") || ctx.path.endsWith("\\config")).toBe(true);
+    expect(ctx.path.endsWith("/config.json") || ctx.path.endsWith("\\config.json")).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

@@ -5,7 +5,7 @@ Handler-facing resolved app config snapshot (ctx.appConfig).
 import type { CliProgram } from "../types.ts";
 import { resolveAppConfigDir, resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
 import type { ResolvedConfig } from "./resolve.ts";
-import { exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
+import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
 
 /** Empty snapshot when program.appConfig is not set. */
 export class EmptyAppConfigSnapshot {
@@ -71,18 +71,19 @@ export class AppConfigSnapshot {
 
   set(key: string, value: unknown): void {
     this.assertEntryKey(key);
+    const hostEnv = captureMappedHostEnv(this.program);
     const next = { ...this.fileData, [key]: value };
     writeAppConfigFile(this.program, next);
     this.fileData = next;
-    this.snapshot = resolveAppConfig(this.program, next);
-    exportConfigToEnv(this.program, this.snapshot);
+    this.snapshot = resolveAppConfig(this.program, next, hostEnv);
+    exportConfigToEnv(this.program, this.snapshot, hostEnv);
   }
 
   read(): ResolvedConfig {
     return { ...this.snapshot };
   }
 
-  /** Resolved absolute path to the app JSON config file (honors `program.appConfig.path` or OS default). */
+  /** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
   get path(): string {
     return resolveAppConfigPath(this.program);
   }