argsbarg 4.1.0 → 5.0.1

package/src/cli-tool/prompt.ts

@@ -0,0 +1,28 @@
+/** Interactive prompts for `argsbarg create`. */
+
+import { readPromptLine as readStdinLine } from "../prompt.ts";
+
+export function readPromptLine(prompt: string): string {
+  process.stderr.write(prompt);
+  return readStdinLine().trim();
+}
+
+export function promptConfirm(message: string): boolean {
+  const ans = readPromptLine(`${message} [y/N]: `);
+  return ans === "y" || ans === "Y";
+}
+
+export function promptOptional(label: string, current?: string): string | undefined {
+  const suffix = current ? ` [${current}]` : "";
+  const ans = readPromptLine(`${label}${suffix}: `);
+  if (ans.length === 0) return current;
+  return ans;
+}
+
+export function promptRequired(label: string, current?: string): string {
+  while (true) {
+    const value = promptOptional(label, current);
+    if (value && value.length > 0) return value;
+    process.stderr.write("  (required)\n");
+  }
+}

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

@@ -0,0 +1,138 @@
+/** `argsbarg create` command orchestration. */
+
+import { mkdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import {
+  applyCreate,
+  type CreateOptions,
+  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 releaseRepo = promptRequired("GitHub release repo (org/repo)", partial.releaseRepo);
+
+  const opts = resolveCreateOptions(
+    {
+      ...partial,
+      key,
+      releaseRepo,
+      force: partial.force ?? false,
+    },
+    baseDir,
+  );
+
+  process.stderr.write(`\nTarget: ${baseDir}\n`);
+  process.stderr.write(
+    `Key: ${opts.key}  Class: ${opts.className}  Tap: ${opts.tap}  Release: ${opts.releaseRepo}\n`,
+  );
+  process.stderr.write(`Homepage: ${opts.homepage}\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.");
+    }
+    if (!partial.releaseRepo) {
+      throw new Error("--release-repo 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/cli.ts

@@ -20,7 +20,6 @@ import { type AnyAppConfigSnapshot, createAppConfigSnapshot } from "./config/con
 import { effectiveJsonSchema } from "./config/schema.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
-import { maybeBootstrapInstallArgv } from "./install/bootstrap.ts";
 import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
@@ -95,7 +94,6 @@ export class Cli {
   }
 
   async run(argv: string[] = process.argv.slice(2)): Promise<never> {
-    argv = maybeBootstrapInstallArgv(argv, this.program);
     assertBuiltinAllowed(argv, this.caps);
 
     const prep = this.prepareDispatch(argv);

package/src/config/bootstrap.ts

@@ -4,6 +4,7 @@ settings are present before the CLI or MCP server handles a request.
 */
 
 import { readSync } from "node:fs";
+import { readPromptLine as readStdinLine } from "../prompt.ts";
 import type { CliAppConfigEntry, CliProgram } from "../types.ts";
 import {
   configEntryRequired,
@@ -124,9 +125,7 @@ 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$/, "");
+  return readStdinLine();
 }
 
 /** Whether this setting already has a non-empty value in the user's shell environment. */
@@ -149,7 +148,7 @@ function promptConfigKey(
   configure: boolean,
   jsonSchemaRequired: Set<string> | undefined,
   hostEnv: Record<string, string | undefined>,
-): { value: unknown } {
+): { value: unknown; userTyped: boolean } {
   const baseTitle = entry.title ?? defaultConfigEntryTitle(key);
   const titleWithEnv = entry.env ? `${baseTitle} (${entry.env})` : baseTitle;
   const required = configEntryRequired(key, entry, jsonSchemaRequired);
@@ -169,18 +168,20 @@ function promptConfigKey(
   }
   const input = readPromptLine(sensitive);
   if (input.length === 0 && hasCurrent) {
-    return { value: current };
+    return { value: current, userTyped: false };
   }
   if (input.length > 0) {
-    return { value: input };
+    return { value: input, userTyped: true };
   }
-  return { value: undefined };
+  return { value: undefined, userTyped: false };
 }
 
-/** Options for the interactive `install --configure` wizard. */
+/** Options for the interactive configure wizard (app config target). */
 export interface RunInstallConfigureOpts {
   /** Where the wizard was started from (standalone command vs right after install). */
   context?: "standalone" | "after-install";
+  /** When false, omit the "Configuration Setup" banner (e.g. inside interactive `configure`). */
+  showHeading?: boolean;
 }
 
 /** Print the "Configuration Setup" heading before the configure prompts. */
@@ -218,7 +219,7 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
       writeConfigureSetupHeading();
       headingWritten = true;
     }
-    const { value } = promptConfigKey(key, entry, undefined, false, fromSchema, hostEnv);
+    const { value, userTyped } = promptConfigKey(key, entry, undefined, false, fromSchema, hostEnv);
     if (value !== undefined && String(value).length > 0) {
       updates[key] = value;
     }
@@ -226,13 +227,13 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   return updates;
 }
 
-/** Run the full interactive configure wizard (`install --configure`). */
-export function runInstallConfigure(
+/** Run the full interactive app config wizard (`configure`). */
+export function runConfigure(
   program: CliProgram,
-  _opts: RunInstallConfigureOpts = {},
+  opts: RunInstallConfigureOpts = {},
 ): { path: string; changed: boolean } {
   if (!program.appConfig) {
-    throw new Error("install --configure requires program.appConfig on the program root.");
+    throw new Error("configure requires program.appConfig on the program root.");
   }
   if (!process.stdin.isTTY) {
     const { resolved } = bootstrapAppConfig(program, { validateFile: false });
@@ -240,7 +241,7 @@ export function runInstallConfigure(
     if (missing.length > 0) {
       process.stderr.write(`${formatMissingConfigMessage(program, missing)}\n`);
     } else {
-      process.stderr.write("install --configure requires an interactive terminal.\n");
+      process.stderr.write("configure requires an interactive terminal.\n");
     }
     process.exit(1);
   }
@@ -254,15 +255,23 @@ export function runInstallConfigure(
   const next: Record<string, unknown> = { ...existing };
   let changed = false;
 
-  if (shouldShowConfigureSetupHeading(program)) {
+  if (opts.showHeading !== false && shouldShowConfigureSetupHeading(program)) {
     writeConfigureSetupHeading();
   }
 
   for (const [key, entry] of Object.entries(program.appConfig.entries)) {
     const before = next[key];
     const current = resolved[key];
-    const { value } = promptConfigKey(key, entry, current, true, fromSchema, hostEnv);
+    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;
       }
@@ -279,7 +288,7 @@ export function runInstallConfigure(
   return { path, changed: false };
 }
 
-/** Summary for `install --status`: config path, whether the file exists, and which required settings are set (never their values). */
+/** Summary for `configure --status`: config path, whether the file exists, and which required settings are set (never their values). */
 export function appConfigStatus(program: CliProgram):
   | {
       path: string;
@@ -336,7 +345,7 @@ export function ensureAppConfig(
 
   if (opts.interactive && process.stdin.isTTY) {
     if (opts.configure) {
-      runInstallConfigure(program, { context: "standalone" });
+      runConfigure(program, { context: "standalone" });
       fileData = readAppConfigFileRaw(resolveAppConfigPath(program));
       resolved = resolveAppConfig(program, fileData, hostEnv);
       exportConfigToEnv(program, resolved, hostEnv);

package/src/config/file.test.ts

@@ -85,7 +85,7 @@ describe("config/file", () => {
       expect(missing).toContain("apiToken");
       expect(missing).not.toContain("port");
       const msg = formatMissingConfigMessage(program, missing);
-      expect(msg).toContain("install --configure");
+      expect(msg).toContain("configure");
     } finally {
       if (prev !== undefined) process.env.API_TOKEN = prev;
     }

package/src/config/resolve.test.ts

@@ -109,4 +109,171 @@ describe("config/resolve", () => {
       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";
@@ -93,6 +93,38 @@ export function resolveAppConfig(
   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,
@@ -100,15 +132,27 @@ function resolveConfigKey(
   fileData: AppConfigFileData,
   hostEnv?: Record<string, string | undefined>,
 ): unknown {
-  if (entry.env) {
-    const fromEnv = envOverrideValue(entry.env, hostEnv);
-    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;
@@ -182,7 +226,7 @@ export function formatMissingConfigMessage(program: CliProgram, keys: string[]):
   const path = displayAppConfigPath(program);
   return [
     `Missing required configuration: ${list}`,
-    `Configure interactively:  ${program.key} install --configure`,
+    `Configure interactively:  ${program.key} configure`,
     `Or set via:               ${program.key} config set <key> <value>`,
     `Config file:              ${path}`,
     `See:                      ${program.key} docs mcp`,
@@ -195,7 +239,7 @@ export function formatMcpMissingConfigMessage(program: CliProgram, keys: string[
   const path = displayAppConfigPath(program);
   return [
     `Missing required configuration: ${list}`,
-    `Configure: ${program.key} install --configure`,
+    `Configure: ${program.key} configure`,
     `Or set via: ${program.key} config set`,
     `Config file: ${path}`,
   ].join("\n");