argsbarg 4.0.3 → 4.1.0

package/src/config/bootstrap.ts

@@ -1,8 +1,9 @@
 /*
-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 type { CliAppConfigEntry, CliProgram } from "../types.ts";
 import {
   configEntryRequired,
@@ -11,6 +12,7 @@ import {
   jsonSchemaRequiredKeys,
 } from "./entry.ts";
 import {
+  appConfigInstalled,
   displayAppConfigPath,
   readAppConfigFile,
   readAppConfigFileRaw,
@@ -19,6 +21,7 @@ import {
 } from "./file.ts";
 import type { ResolvedConfig } from "./resolve.ts";
 import {
+  captureMappedHostEnv,
   exportConfigToEnv,
   formatMissingConfigMessage,
   missingRequiredConfig,
@@ -27,87 +30,171 @@ 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();
+  }
+  const buf = Buffer.alloc(4096);
+  const n = readSync(0, buf, { length: 4096 });
+  return buf.toString("utf8", 0, n).replace(/\r?\n$/, "");
+}
+
+/** 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 } {
+  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 };
   }
-  return input.length > 0 ? input : undefined;
+  if (input.length > 0) {
+    return { value: input };
+  }
+  return { value: undefined };
+}
+
+/** 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 +203,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 +214,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 } = promptConfigKey(key, entry, undefined, false, fromSchema, hostEnv);
     if (value !== undefined && String(value).length > 0) {
       updates[key] = value;
     }
@@ -133,8 +226,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,16 +247,21 @@ 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 } = promptConfigKey(key, entry, current, true, fromSchema, hostEnv);
     if (value !== undefined && String(value).length > 0) {
       if (JSON.stringify(value) !== JSON.stringify(before)) {
         changed = true;
@@ -171,14 +272,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 +290,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 +309,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 +330,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 +347,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 +364,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);
   }