argsbarg 4.1.1 → 5.0.2

package/src/builtins/dispatch.ts

@@ -1,7 +1,7 @@
 import { capabilityDeniedMessage, resolveCapabilities } from "../capabilities.ts";
 import { Cli } from "../cli.ts";
+import { cliConfigure } from "../configure/index.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
-import { cliInstall, cliUninstall } from "../install/index.ts";
 import { runMcpBundle } from "../mcp/bundle.ts";
 import type { ParseResult } from "../parse.ts";
 import { ParseKind } from "../parse.ts";
@@ -12,10 +12,9 @@ import { completionFishScript } from "./completion-fish.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { completionZshScript } from "./completion-zsh.ts";
 import { cliBuiltinConfigGroupIfEnabled } from "./config.ts";
-import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinConfigureCommand } from "./configure.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
-import { cliBuiltinUninstallCommand } from "./uninstall.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 
 export interface DispatchBuiltinOpts {
@@ -45,6 +44,10 @@ export async function dispatchBuiltin(
   const caps = resolveCapabilities(program);
 
   if (pr.path[0] === "completion") {
+    if (!caps.completion) {
+      process.stderr.write(capabilityDeniedMessage("completion"));
+      process.exit(1);
+    }
     const schemaForCompletion = completionSchema(program, opts);
     if (pr.path[1] === "bash") {
       process.stdout.write(completionBashScript(schemaForCompletion));
@@ -93,28 +96,16 @@ export async function dispatchBuiltin(
     process.exit(1);
   }
 
-  if (pr.path[0] === "install") {
-    if (!caps.install) {
-      process.stderr.write(capabilityDeniedMessage("install"));
-      process.exit(1);
-    }
-    if (pr.path.length !== 1) {
-      process.stderr.write(`Unknown subcommand: install ${pr.path.slice(1).join(" ")}\n`);
-      process.exit(1);
-    }
-    await cliInstall(program, pr.opts);
-  }
-
-  if (pr.path[0] === "uninstall") {
-    if (!caps.install) {
-      process.stderr.write(capabilityDeniedMessage("install"));
+  if (pr.path[0] === "configure") {
+    if (!caps.configure) {
+      process.stderr.write(capabilityDeniedMessage("configure"));
       process.exit(1);
     }
     if (pr.path.length !== 1) {
-      process.stderr.write(`Unknown subcommand: uninstall ${pr.path.slice(1).join(" ")}\n`);
+      process.stderr.write(`Unknown subcommand: configure ${pr.path.slice(1).join(" ")}\n`);
       process.exit(1);
     }
-    await cliUninstall(program, pr.opts);
+    await cliConfigure(program, pr.opts);
   }
 }
 
@@ -141,23 +132,12 @@ export function builtinInterceptRoot(
     };
   }
 
-  if (first === "install" && caps.install) {
-    return {
-      parseRoot: {
-        key: program.key,
-        description: program.description,
-        commands: [cliBuiltinInstallCommand(program)],
-      },
-      isLeafCompletionIntercept: false,
-    };
-  }
-
-  if (first === "uninstall" && caps.install) {
+  if (first === "configure" && caps.configure) {
     return {
       parseRoot: {
         key: program.key,
         description: program.description,
-        commands: [cliBuiltinUninstallCommand(program)],
+        commands: [cliBuiltinConfigureCommand(program)],
       },
       isLeafCompletionIntercept: false,
     };

package/src/builtins/index.ts

@@ -2,9 +2,9 @@ export { completionBashScript } from "./completion-bash.ts";
 export { completionFishScript } from "./completion-fish.ts";
 export { cliBuiltinCompletionGroup } from "./completion-group.ts";
 export { completionZshScript } from "./completion-zsh.ts";
+export { cliBuiltinConfigureCommand, configureBuiltinOptions } from "./configure.ts";
 export { builtinInterceptRoot, dispatchBuiltin } from "./dispatch.ts";
 export { type CliSchemaExport, exportPresentationBuiltins } from "./export.ts";
-export { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 export { cliBuiltinMcpCommand } from "./mcp.ts";
 export {
   cliParseRoot,

package/src/builtins/mcp.ts

@@ -12,8 +12,8 @@ export function cliBuiltinMcpCommand(program: CliProgram): CliRouter {
     "  args: mcp",
     "",
   ];
-  if (caps.install) {
-    lines.push("Or:", "", "  {argsbarg:program} install --mcp --yes", "");
+  if (caps.configure) {
+    lines.push("Or:", "", "  {argsbarg:program} configure", "");
   }
   if (docsEnabled(program)) {
     lines.push("Full setup guide: {argsbarg:program} docs mcp");

package/src/builtins/registry.ts

@@ -3,9 +3,8 @@ import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import type { CliNode, CliProgram } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinConfigGroupIfEnabled } from "./config.ts";
-import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinConfigureCommand } from "./configure.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
-import { cliBuiltinUninstallCommand } from "./uninstall.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 
 type BuiltinFactory = (program: CliProgram) => CliNode | null;
@@ -27,11 +26,12 @@ function pushBuiltin(
 /** Capability-gated built-in command nodes in stable order (parse, help, export). */
 export function resolveBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
   const builtins: CliNode[] = [];
-  pushBuiltin(builtins, program, (p) => cliBuiltinCompletionGroup(p));
+  if (caps.completion) {
+    pushBuiltin(builtins, program, (p) => cliBuiltinCompletionGroup(p));
+  }
   pushBuiltin(builtins, program, () => cliBuiltinVersionCommand());
-  if (caps.install) {
-    pushBuiltin(builtins, program, (p) => cliBuiltinInstallCommand(p));
-    pushBuiltin(builtins, program, (p) => cliBuiltinUninstallCommand(p));
+  if (caps.configure) {
+    pushBuiltin(builtins, program, (p) => cliBuiltinConfigureCommand(p));
   }
   pushBuiltin(builtins, program, (p) => cliBuiltinDocsGroupIfEnabled(p) ?? null);
   if (caps.mcp) {

package/src/capabilities.ts

@@ -8,20 +8,20 @@ import type { CliProgram } from "./types.ts";
 
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {
-  completion: true;
+  completion: boolean;
   mcp: boolean;
-  install: boolean;
+  configure: boolean;
   docs: boolean;
   configCommands: boolean;
 }
 
 /** Resolves which capabilities are enabled for a program. */
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
-  const install = program.install?.enabled !== false;
+  const configure = program.configure?.enabled !== false;
   return {
-    completion: true,
+    completion: program.completion?.enabled !== false,
     mcp: program.mcpServer?.enabled === true,
-    install,
+    configure,
     docs: program.docs?.enabled === true,
     configCommands: configCommandsEnabled(program),
   };
@@ -29,9 +29,12 @@ export function resolveCapabilities(program: CliProgram): CliCapabilities {
 
 /** Reserved top-level command names for the given capabilities. */
 export function reservedCommandNames(caps: CliCapabilities): string[] {
-  const names = ["completion", "version"];
-  if (caps.install) {
-    names.push("install", "uninstall");
+  const names = ["version"];
+  if (caps.completion) {
+    names.unshift("completion");
+  }
+  if (caps.configure) {
+    names.push("configure");
   }
   if (caps.docs) {
     names.push("docs");
@@ -57,15 +60,17 @@ export function skipsRequiredAppConfigExit(path: string[], caps: CliCapabilities
   return false;
 }
 
-export type CapabilityFeature = "mcp" | "install" | "docs" | "config";
+export type CapabilityFeature = "mcp" | "configure" | "docs" | "config" | "completion";
 
 /** Stderr message when a disabled built-in is invoked from the CLI. */
 export function capabilityDeniedMessage(feature: CapabilityFeature): string {
   switch (feature) {
+    case "completion":
+      return "Shell completion is not available for this app.\n";
     case "mcp":
       return "MCP is not available for this app.\n";
-    case "install":
-      return "Install is not available for this app.\n";
+    case "configure":
+      return "Configure is not available for this app.\n";
     case "docs":
       return "Documentation commands are not available for this app.\n";
     case "config":
@@ -79,12 +84,16 @@ export function assertBuiltinAllowed(argv: string[], caps: CliCapabilities): voi
     return;
   }
   const first = argv[0];
+  if (first === "completion" && !caps.completion) {
+    process.stderr.write(capabilityDeniedMessage("completion"));
+    process.exit(1);
+  }
   if (first === "mcp" && !caps.mcp) {
     process.stderr.write(capabilityDeniedMessage("mcp"));
     process.exit(1);
   }
-  if (first === "install" && !caps.install) {
-    process.stderr.write(capabilityDeniedMessage("install"));
+  if (first === "configure" && !caps.configure) {
+    process.stderr.write(capabilityDeniedMessage("configure"));
     process.exit(1);
   }
   if (first === "docs" && !caps.docs) {

package/src/cli-tool/cli-smoke.test.ts

@@ -1,19 +1,37 @@
+/*
+Tests for cli-tool/cli-smoke module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 
 const main = join(import.meta.dir, "main.ts");
 
+/** Tests for argsbarg cli-tool. */
 describe("argsbarg cli-tool", () => {
+  /** Tests that version subcommand prints version. */
   test("version subcommand prints version", () => {
     const proc = spawnSync("bun", [main, "version"], { encoding: "utf8" });
     expect(proc.status).toBe(0);
     expect(proc.stdout.trim().length).toBeGreaterThan(0);
   });
 
-  test("completion subcommand emits bash script", () => {
-    const proc = spawnSync("bun", [main, "completion", "bash"], { encoding: "utf8" });
+  /** Tests that help lists create and version only (no install, completion, mcp). */
+  test("help lists create and version only (no install, completion, mcp)", () => {
+    const proc = spawnSync("bun", [main, "--help"], { encoding: "utf8" });
     expect(proc.status).toBe(0);
-    expect(proc.stdout).toContain("complete");
+    expect(proc.stdout).toContain("create");
+    expect(proc.stdout).toContain("version");
+    expect(proc.stdout).not.toContain("configure");
+    expect(proc.stdout).not.toContain("completion");
+    expect(proc.stdout).not.toContain("mcp");
+  });
+
+  /** Completion subcommand is disabled. */
+  test("completion subcommand is disabled", () => {
+    const proc = spawnSync("bun", [main, "completion", "bash"], { encoding: "utf8" });
+    expect(proc.status).toBe(1);
+    expect(proc.stderr).toContain("Shell completion is not available");
   });
 });

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

@@ -1,3 +1,7 @@
+/*
+Tests for cli-tool/create module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -8,10 +12,13 @@ import {
   diffCreate,
   diffCreateDetails,
   renderCreateTree,
+  resolveCreateOptions,
   substituteTemplateContent,
 } from "./create.ts";
 
+/** Tests for argsbarg create. */
 describe("argsbarg create", () => {
+  /** Tests that substitutes {key} tokens. */
   test("substitutes {key} tokens", () => {
     const out = substituteTemplateContent(
       "key={key} class={className} env={envPrefix}_API_TOKEN tap={tap} org={tapOrg}",
@@ -37,10 +44,35 @@ describe("argsbarg create", () => {
     expect(out).not.toContain("{key}");
   });
 
+  /** Tests that classNameFromKey. */
   test("classNameFromKey", () => {
     expect(classNameFromKey("sqsp-i18n")).toBe("SqspI18n");
+    expect(classNameFromKey("at1")).toBe("At1");
+    expect(classNameFromKey("1password")).toBe("App1password");
+  });
+
+  /** ResolveCreateOptions derives identity defaults from key. */
+  test("resolveCreateOptions derives identity defaults from key", () => {
+    expect(resolveCreateOptions({ key: "1password", releaseRepo: "org/1password" }).className).toBe(
+      "App1password",
+    );
+    expect(
+      resolveCreateOptions({ key: "my-cli", className: "Custom", releaseRepo: "org/my-cli" })
+        .className,
+    ).toBe("Custom");
+    const opts = resolveCreateOptions({ key: "at1", releaseRepo: "bdombro/at1" });
+    expect(opts.tap).toBe("bdombro/at1");
+    expect(opts.releaseRepo).toBe("bdombro/at1");
+    expect(opts.homepage).toBe("https://github.com/bdombro/at1");
+    expect(opts.desc).toBe("At1 CLI");
+  });
+
+  /** ResolveCreateOptions requires release repo. */
+  test("resolveCreateOptions requires release repo", () => {
+    expect(() => resolveCreateOptions({ key: "at1" })).toThrow(/release repo/i);
   });
 
+  /** Tests that renderCreateTree includes justfile and create-identity. */
   test("renderCreateTree includes justfile and create-identity", () => {
     const tree = renderCreateTree({
       key: "testapp",
@@ -66,6 +98,7 @@ describe("argsbarg create", () => {
     expect(formula).toContain("create-identity.ts");
   });
 
+  /** Tests that --check detects drift. */
   test("--check detects drift", () => {
     const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
     try {
@@ -89,6 +122,7 @@ describe("argsbarg create", () => {
     }
   });
 
+  /** Tests that --check infers options from create-identity.ts. */
   test("--check infers options from create-identity.ts", () => {
     const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
     try {
@@ -112,8 +146,9 @@ describe("argsbarg create", () => {
     }
   });
 
+  /** Tests that --diff captures drift details. */
   test("--diff captures drift details", () => {
-    const drifts = diffCreateDetails("/nonexistent", { key: "x" });
+    const drifts = diffCreateDetails("/nonexistent", { key: "x", releaseRepo: "org/x" });
     expect(drifts.length).toBeGreaterThan(0);
   });
 });

package/src/cli-tool/create.ts

@@ -44,11 +44,20 @@ export function keyToEnvPrefix(key: string): string {
     .toUpperCase();
 }
 
+/** PascalCase Homebrew formula class from CLI key; prefix `App` when Ruby constant rules require it. */
 export function classNameFromKey(key: string): string {
-  return key
+  const name = key
     .split(/[-_]/)
+    .filter((s) => s.length > 0)
     .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
     .join("");
+  if (name.length === 0) {
+    throw new Error(`Invalid CLI key: ${key}`);
+  }
+  if (!/^[A-Z]/.test(name)) {
+    return `App${name}`;
+  }
+  return name;
 }
 
 function tapLibraryParts(tap: string): { org: string; repo: string } {
@@ -131,6 +140,12 @@ export function inferCreateOptions(
   };
 }
 
+function assertReleaseRepoFormat(releaseRepo: string): void {
+  if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(releaseRepo)) {
+    throw new Error(`Invalid release repo (expected org/repo): ${releaseRepo}`);
+  }
+}
+
 export function resolveCreateOptions(
   partial: Partial<CreateOptions>,
   baseDir?: string,
@@ -139,13 +154,20 @@ export function resolveCreateOptions(
   const tmpl = templateIdentity();
   const key = merged.key ?? tmpl.key ?? "full-example";
   const className = merged.className ?? classNameFromKey(key);
+  const releaseRepo = merged.releaseRepo;
+  if (!releaseRepo) {
+    throw new Error(
+      "GitHub release repo (org/repo) is required. Pass --release-repo or use the interactive wizard.",
+    );
+  }
+  assertReleaseRepoFormat(releaseRepo);
   const devTemplate = merged.devTemplate ?? (baseDir ? isDevTemplateDir(baseDir) : false);
   return {
     key,
     className,
-    tap: merged.tap ?? `local/${key}`,
-    homepage: merged.homepage ?? `https://github.com/${merged.releaseRepo ?? `example/${key}`}`,
-    releaseRepo: merged.releaseRepo ?? `example/${key}`,
+    tap: merged.tap ?? releaseRepo,
+    homepage: merged.homepage ?? `https://github.com/${releaseRepo}`,
+    releaseRepo,
     desc: merged.desc ?? `${className} CLI`,
     force: merged.force ?? false,
     dryRun: merged.dryRun ?? false,

package/src/cli-tool/full-example-capabilities.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for cli-tool/full-example-capabilities module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -22,7 +26,7 @@ const sinkProgram = {
     topics: { readme: { text: "# readme\n" } },
   },
   mcpServer: { enabled: true },
-  install: {},
+  configure: {},
   commands: [
     {
       key: "status",
@@ -45,7 +49,9 @@ const sinkProgram = {
   ],
 } satisfies CliProgram;
 
+/** Tests for full-example template. */
 describe("full-example template", () => {
+  /** Tests that program source enables every builtin flag. */
   test("program source enables every builtin flag", () => {
     expect(programSource).toContain("mcpServer: {");
     expect(programSource).toContain("enabled: true");
@@ -53,16 +59,18 @@ describe("full-example template", () => {
     expect(programSource).toContain("appConfig:");
   });
 
+  /** Status command defines outputSchema. */
   test("status command defines outputSchema", () => {
     const statusSource = readFileSync(join(exampleRoot, "src/commands/status/command.ts"), "utf8");
     expect(statusSource).toContain("outputSchema:");
   });
 
+  /** ResolveCapabilities matches full sink shape. */
   test("resolveCapabilities matches full sink shape", () => {
     expect(resolveCapabilities(sinkProgram)).toEqual({
       completion: true,
       mcp: true,
-      install: true,
+      configure: true,
       docs: true,
       configCommands: true,
     });

package/src/cli-tool/program.ts

@@ -10,6 +10,8 @@ export const program = {
   key: "argsbarg",
   version: pkg.version,
   description: "Argsbarg developer tools — bootstrap CLIs from the full-example template.",
+  completion: { enabled: false },
+  configure: { enabled: false },
   commands: [
     {
       key: "create",
@@ -18,17 +20,30 @@ export const program = {
         { name: "key", description: "CLI binary name.", kind: CliOptionKind.String },
         {
           name: "class-name",
-          description: "Homebrew formula class name.",
+          description: "Homebrew formula Ruby class (default: derived from --key).",
+          kind: CliOptionKind.String,
+        },
+        {
+          name: "tap",
+          description: "Homebrew tap (default: same as --release-repo).",
+          kind: CliOptionKind.String,
+        },
+        {
+          name: "homepage",
+          description: "Formula homepage (default: https://github.com/<release-repo>).",
           kind: CliOptionKind.String,
         },
-        { name: "tap", description: "Homebrew tap (org/repo).", kind: CliOptionKind.String },
-        { name: "homepage", description: "Formula homepage URL.", kind: CliOptionKind.String },
         {
           name: "release-repo",
-          description: "GitHub org/repo for release binary.",
+          description: "GitHub org/repo for releases (required in non-interactive mode).",
+          kind: CliOptionKind.String,
+        },
+        {
+          name: "desc",
+          description:
+            "App + formula description (default: <ClassName> CLI; stored in create-identity.ts).",
           kind: CliOptionKind.String,
         },
-        { name: "desc", description: "Formula description.", kind: CliOptionKind.String },
         { name: "force", description: "Overwrite existing files.", kind: CliOptionKind.Presence },
         {
           name: "dry-run",

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

@@ -5,7 +5,6 @@ import { relative, resolve } from "node:path";
 import {
   applyCreate,
   type CreateOptions,
-  classNameFromKey,
   diffCreateDetails,
   parseCreateArgv,
   printCreateDiffs,
@@ -27,36 +26,23 @@ function collectInteractiveOptions(
   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 releaseRepo = promptRequired("GitHub release repo (org/repo)", partial.releaseRepo);
 
   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`);
+  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()) {
@@ -104,6 +90,9 @@ export async function runCreate(input: Partial<CreateOptions> & { dir?: string }
     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) {

package/src/config/bootstrap.ts

@@ -176,10 +176,12 @@ function promptConfigKey(
   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. */
@@ -225,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 });
@@ -239,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);
   }
@@ -253,7 +255,7 @@ export function runInstallConfigure(
   const next: Record<string, unknown> = { ...existing };
   let changed = false;
 
-  if (shouldShowConfigureSetupHeading(program)) {
+  if (opts.showHeading !== false && shouldShowConfigureSetupHeading(program)) {
     writeConfigureSetupHeading();
   }
 
@@ -286,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;
@@ -343,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/context.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for config/context module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -20,7 +24,9 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+/** Tests for config/context. */
 describe("config/context", () => {
+  /** Tests that AppConfigSnapshot get, require, read, set. */
   test("AppConfigSnapshot get, require, read, set", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-test-"));
     const prevHome = process.env.HOME;
@@ -50,6 +56,7 @@ describe("config/context", () => {
     }
   });
 
+  /** Tests that EmptyAppConfigSnapshot when program.appConfig unset. */
   test("EmptyAppConfigSnapshot when program.appConfig unset", () => {
     const programWithoutConfig: CliProgram = {
       key: "x",
@@ -65,6 +72,7 @@ describe("config/context", () => {
     expect(empty.dir).toBe(dirname(empty.path));
   });
 
+  /** Tests that AppConfigSnapshot path uses OS default from program key. */
   test("AppConfigSnapshot path uses OS default from program key", () => {
     const ctx = createAppConfigSnapshot(program, {}, {});
     expect(ctx.path).toContain("ctx_test");