argsbarg 3.6.4 → 4.0.0

package/examples/consumer-app/src/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Config schema
+ *
+ * Application settings for `consumer-app` (`program.appConfig`).
+ */
+export interface AppConfig {
+  /** API token from the provider dashboard. */
+  apiToken: string;
+  /**
+   * AWS region (default us-east-1).
+   * @default us-east-1
+   */
+  defaultRegion?: string;
+  /**
+   * HTTP retry count (default 3).
+   * @default 3
+   */
+  maxRetries: number;
+  /** Local preferences (file-only; not mapped to process.env). */
+  prefs?: {
+    ttl: number;
+  };
+}

package/examples/consumer-app/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts"]
+}

package/examples/formats.ts

@@ -6,9 +6,15 @@
  */
 
 import pkg from "../package.json" with { type: "json" };
-import { cliRun, CliFallbackMode, CliOptionKind, CliValueFormat, type CliProgram } from "../src/index.ts";
+import {
+  Cli,
+  CliFallbackMode,
+  CliOptionKind,
+  type CliProgram,
+  CliValueFormat,
+} from "../src/index.ts";
 
-const cli = {
+const program = {
   key: "formats.ts",
   version: pkg.version,
   description: "Value formats and readLeafInputs demo.",
@@ -63,4 +69,5 @@ const cli = {
   ],
 } satisfies CliProgram;
 
-await cliRun(cli);
+const cli = new Cli(program);
+await cli.run();

package/examples/mcp-test.ts

@@ -3,17 +3,38 @@
 MCP test fixture for subprocess integration tests only.
 */
 
-import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram } from "../src/index.ts";
 
-const envFilePath = process.env.ARGS_TEST_ENV_FILE;
+const configPath = process.env.ARGS_TEST_CONFIG_FILE;
 
-const cli = {
+const program = {
   key: "mcp-test",
   version: "0.0.0-test",
   description: "MCP integration test fixture.",
+  ...(configPath
+    ? {
+        appConfig: {
+          path: configPath,
+          entries: {
+            argsTestSecret: {
+              description: "Test secret for integration tests.",
+              env: "ARGS_TEST_SECRET",
+            },
+          },
+        },
+      }
+    : {
+        appConfig: {
+          entries: {
+            argsTestSecret: {
+              description: "Test secret for integration tests.",
+              env: "ARGS_TEST_SECRET",
+            },
+          },
+        },
+      }),
   mcpServer: {
     enabled: true,
-    ...(envFilePath ? { envFile: envFilePath } : {}),
     resources: [
       {
         uri: "test://hello",
@@ -28,9 +49,6 @@ const cli = {
     {
       key: "echo-env",
       description: "Echo an env var.",
-      mcpTool: {
-        requiresEnv: ["ARGS_TEST_SECRET"],
-      },
       options: [
         {
           name: "name",
@@ -63,4 +81,5 @@ const cli = {
   ],
 } satisfies CliProgram;
 
-await cliRun(cli);
+const cli = new Cli(program);
+await cli.run();

package/examples/minimal.ts

@@ -8,9 +8,9 @@ It demonstrates the minimal Bun integration path.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram } from "../src/index.ts";
 
-const cli = {
+const program = {
   key: "minimal.ts",
   version: pkg.version,
   description: "Tiny demo.",
@@ -46,4 +46,5 @@ const cli = {
   },
 } satisfies CliProgram;
 
-await cliRun(cli);
+const cli = new Cli(program);
+await cli.run();

package/examples/nested.ts

@@ -8,9 +8,9 @@ It demonstrates how the schema scales beyond one command.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { cliRun, CliProgram, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "../src/index.ts";
 
-const cli = {
+const program = {
   key: "nested.ts",
   version: pkg.version,
   description: "Nested groups demo.",
@@ -99,7 +99,7 @@ const cli = {
             const text = await file.text();
             const firstLine = text.split("\n")[0];
             console.log(`${path}: ${firstLine}`);
-          } catch (err) {
+          } catch {
             console.error(`Cannot open: ${path}`);
           }
         }
@@ -110,4 +110,5 @@ const cli = {
   fallbackMode: CliFallbackMode.MissingOrUnknown,
 } satisfies CliProgram;
 
-await cliRun(cli);
+const cli = new Cli(program);
+await cli.run();

package/examples/option-required.ts

@@ -8,9 +8,9 @@ It demonstrates the minimal Bun integration path.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { cliRun, CliProgram, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram, isInteractiveTty } from "../src/index.ts";
 
-const cli = {
+const program = {
   key: "option-required.ts",
   version: pkg.version,
   description: "Demo of a required option.",
@@ -37,7 +37,10 @@ const cli = {
     },
   ],
   handler: (ctx) => {
-    const requiredAlways = ctx.stringOpt("requiredAlways")!;
+    const requiredAlways = ctx.stringOpt("requiredAlways");
+    if (requiredAlways === undefined) {
+      throw new Error("requiredAlways missing after validation");
+    }
     const requiredNonTty = ctx.stringOpt("requiredNonTty") ?? "valueWhenOmitted";
     const optional = ctx.stringOpt("optional") ?? "valueWhenOmitted";
     console.log(`requiredAlways: ${requiredAlways}`);
@@ -46,4 +49,5 @@ const cli = {
   },
 } satisfies CliProgram;
 
-await cliRun(cli);
+const cli = new Cli(program);
+await cli.run();

package/index.d.ts

@@ -1,5 +1,69 @@
 // Generated by dts-bundle-generator v9.5.1
 
+export type ResolvedConfig = Record<string, unknown>;
+declare class EmptyAppConfigSnapshot {
+	get(_key: string): undefined;
+	require(key: string): never;
+	set(_key: string, _value: unknown): void;
+	read(): ResolvedConfig;
+}
+declare class AppConfigSnapshot {
+	private readonly program;
+	private snapshot;
+	private fileData;
+	constructor(program: CliProgram, fileData: Record<string, unknown>, resolved: ResolvedConfig);
+	get(key: string): unknown;
+	require(key: string): unknown;
+	set(key: string, value: unknown): void;
+	read(): ResolvedConfig;
+	/** Replace snapshot after external bootstrap (internal). */
+	refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void;
+	private assertEntryKey;
+}
+export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
+/** Coerced leaf inputs keyed by option and positional names. */
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
+/**
+ * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
+ */
+export declare class CliContext {
+	readonly appName: string;
+	readonly commandPath: string[];
+	readonly args: string[];
+	readonly program: CliProgram;
+	readonly opts: Record<string, string>;
+	readonly invocation: CliInvocation;
+	readonly appConfig: AnyAppConfigSnapshot;
+	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot);
+	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
+	hasFlag(name: string): boolean;
+	/** Returns the string value for a string-valued option, if present. */
+	stringOpt(name: string): string | undefined;
+	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
+	numberOpt(name: string): number | null;
+	/**
+	 * Generic typed accessor: parses a stored string using the provided parse function.
+	 * This is the TypeScript-native advantage over the Swift version.
+	 */
+	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Duration option in milliseconds (post-parse validated). */
+	durationOpt(name: string): number | undefined;
+	/** Comma-list option as a string array (post-parse validated). */
+	commaListOpt(name: string): string[] | undefined;
+	/** Date option as canonical YYYY-MM-DD (post-parse validated). */
+	dateOpt(name: string): string | undefined;
+	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
+	dateTimeOpt(name: string): string | undefined;
+	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+	positional(name: string): string | string[] | undefined;
+	/** Reads coerced option and positional values for the current leaf from schema metadata. */
+	readLeafInputs(): CliLeafInputs;
+	private _readOptionValue;
+	private _leafNode;
+	private _posMap;
+	private _positionalMap;
+}
 /**
  * How a leaf handler was dispatched.
  */
@@ -128,12 +192,6 @@ export interface CliMcpServerConfig {
 	 * and shell exports that MCP hosts (e.g. Cursor) don't inherit.
 	 */
 	shellEnv?: boolean | string;
-	/**
-	 * Path to a .env file loaded into process.env at MCP server start, after shellEnv.
-	 * Supports `~` expansion. Warns on stderr if the file does not exist.
-	 * Always overwrites — envFile is authoritative for its keys.
-	 */
-	envFile?: string;
 	/**
 	 * Custom MCP resources exposed alongside the built-in schema resource.
 	 * URIs must be unique and must not equal schemaResourceUri.
@@ -168,12 +226,6 @@ export interface CliMcpToolConfig {
 	 * Default: auto-generated from command path and description.
 	 */
 	description?: string;
-	/**
-	 * Environment variable names required at runtime.
-	 * Appended to auto-generated MCP tool descriptions; enforced at tools/call time.
-	 * Empty string counts as absent.
-	 */
-	requiresEnv?: string[];
 	/**
 	 * @deprecated Set `outputSchema` on the leaf command instead.
 	 */
@@ -194,6 +246,43 @@ export interface CliUpdateArtifact {
 export type CliUpdateGetLatest = (ctx: {
 	version: string;
 }) => Promise<CliUpdateArtifact>;
+/**
+ * Metadata overlay for one key in {@link CliAppConfig.entries}.
+ * Types and validation come from {@link CliAppConfig.jsonSchema} when set; otherwise all values are strings.
+ */
+export interface CliAppConfigEntry {
+	/** Help text for prompts, MCP manifests, and generated docs. */
+	description: string;
+	/** Short label in host UIs and CLI prompts. Default: the config key. */
+	title?: string;
+	/** Default when `jsonSchema` is omitted (all-string mode). */
+	default?: string;
+	/** When `false`, optional for bootstrap and MCP enforcement. Default: `true`. */
+	required?: boolean;
+	/**
+	 * Mask stdin during prompts and redact on `config get`.
+	 * Default: `/key|token|secret|password/i.test(name)`.
+	 */
+	sensitive?: boolean;
+	/** When set: non-empty `process.env[env]` overrides file; value exported after resolve. */
+	env?: string;
+}
+/**
+ * App configuration block on the program root ({@link CliProgram.appConfig}).
+ */
+export interface CliAppConfig {
+	/** Default: `~/.config/<sanitized-key>/config` (or `%APPDATA%/<key>/config` on Windows). */
+	path?: string;
+	/** Built-in `config get` / `config set`. Default: enabled when `appConfig` is set. */
+	commands?: boolean | {
+		enabled?: boolean;
+		mcpSet?: boolean;
+	};
+	/** Block JSON Schema (draft-07). When omitted, synthesize all-string schema from `entries`. */
+	jsonSchema?: Record<string, unknown>;
+	/** Per-key metadata; keys must match `jsonSchema.properties` when `jsonSchema` is set. */
+	entries: Record<string, CliAppConfigEntry>;
+}
 export interface CliInstallConfig {
 	/** When `false`, hide/disable `install` (default: enabled). */
 	enabled?: boolean;
@@ -278,12 +367,14 @@ export type CliRouter = CliNodeBase & {
  */
 export type CliNode = CliLeaf | CliRouter;
 /**
- * Program root passed to `cliRun` / `cliInvoke`.
+ * Program root passed to {@link Cli}.
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
 	/** Program version (printed by the `version` built-in and MCP serverInfo). */
 	version: string;
+	/** Schema-driven app config file, bootstrap, and MCP metadata. */
+	appConfig?: CliAppConfig;
 	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
 	mcpServer?: CliMcpServerConfig;
 	/** Opt-out and defaults for `install`. */
@@ -303,48 +394,56 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
-/** Coerced leaf inputs keyed by option and positional names. */
-export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
-/**
- * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
- */
-export declare class CliContext {
-	readonly appName: string;
-	readonly commandPath: string[];
-	readonly args: string[];
+/** Platform builtins derived from program config and runtime. */
+export interface CliCapabilities {
+	completion: true;
+	mcp: boolean;
+	install: boolean;
+	docs: boolean;
+	update: boolean;
+	configCommands: boolean;
+}
+/** JSON-safe command node (no handlers). */
+export interface CliSchemaExport {
+	key: string;
+	description: string;
+	notes?: string;
+	/** JSON Schema for structured stdout when set on the leaf. */
+	outputSchema?: Record<string, unknown>;
+	options?: CliOption[];
+	fallbackCommand?: string;
+	fallbackMode?: CliFallbackMode;
+	commands?: CliSchemaExport[];
+	positionals?: CliPositional[];
+}
+/** Outcome of a non-exiting CLI invocation. */
+export type CliInvokeKind = "ok" | "help" | "error";
+/** Result of Cli.invoke: captured output and exit metadata without process.exit. */
+export interface CliInvokeResult {
+	kind: CliInvokeKind;
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	errorMsg?: string;
+}
+/** Argsbarg runtime for a validated, frozen {@link CliProgram}. */
+export declare class Cli {
 	readonly program: CliProgram;
-	readonly opts: Record<string, string>;
-	readonly invocation: CliInvocation;
-	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation);
-	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
-	hasFlag(name: string): boolean;
-	/** Returns the string value for a string-valued option, if present. */
-	stringOpt(name: string): string | undefined;
-	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
-	numberOpt(name: string): number | null;
-	/**
-	 * Generic typed accessor: parses a stored string using the provided parse function.
-	 * This is the TypeScript-native advantage over the Swift version.
-	 */
-	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
-	/** Duration option in milliseconds (post-parse validated). */
-	durationOpt(name: string): number | undefined;
-	/** Comma-list option as a string array (post-parse validated). */
-	commaListOpt(name: string): string[] | undefined;
-	/** Date option as canonical YYYY-MM-DD (post-parse validated). */
-	dateOpt(name: string): string | undefined;
-	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
-	dateTimeOpt(name: string): string | undefined;
-	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
-	positional(name: string): string | string[] | undefined;
-	/** Reads coerced option and positional values for the current leaf from schema metadata. */
-	readLeafInputs(): CliLeafInputs;
-	private _readOptionValue;
-	private _leafNode;
-	private _posMap;
-	private _positionalMap;
+	readonly caps: CliCapabilities;
+	private readonly parseRootMerged;
+	private readonly presentationRoot;
+	private _appConfig?;
+	constructor(program: CliProgram);
+	get appConfig(): AnyAppConfigSnapshot;
+	exportCommandSchema(): CliSchemaExport;
+	exportAppConfigSchema(): Record<string, unknown> | undefined;
+	run(argv?: string[]): Promise<never>;
+	invoke(argv: string[]): Promise<CliInvokeResult>;
+	serveMcp(): Promise<never>;
+	private prepareDispatch;
+	private buildAppConfigSnapshot;
 }
+export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** Parses a duration string (e.g. 20m, 1h, 30s) into milliseconds. */
 export declare function parseDurationMs(durationStr: string): number;
 /** Splits a comma-separated string into trimmed non-empty tokens. */
@@ -426,26 +525,6 @@ export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
 };
 /** Shared `gh release view` fetcher for hooks and version-check refresh. */
 export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
-/** Outcome of a non-exiting CLI invocation. */
-export type CliInvokeKind = "ok" | "help" | "error";
-/** Result of cliInvoke: captured output and exit metadata without process.exit. */
-export interface CliInvokeResult {
-	/** Invocation outcome. */
-	kind: CliInvokeKind;
-	/** Simulated exit code. */
-	exitCode: number;
-	/** Captured stdout during handler execution. */
-	stdout: string;
-	/** Captured stderr during handler execution. */
-	stderr: string;
-	/** Set when kind === "error" (parse/validation message). */
-	errorMsg?: string;
-}
-/**
- * Parses argv against the user root, runs the leaf handler, and returns captured output.
- * Never calls process.exit.
- */
-export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;
@@ -466,8 +545,6 @@ export interface PackMcpBundleOpts {
  * Requires the compiled binary to exist.
  */
 export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
-export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
-export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.6.4",
+  "version": "4.0.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -127,6 +127,19 @@ describe("completion emitters", () => {
 });
 
 describe("schema export builtins", () => {
+  test("exportPresentationBuiltins includes config when appConfig set", () => {
+    const withConfig: CliProgram = {
+      ...fixture,
+      appConfig: {
+        entries: {
+          apiToken: { description: "Token.", env: "API_TOKEN" },
+        },
+      },
+    };
+    const builtins = exportPresentationBuiltins(withConfig);
+    expect(builtins.map((b) => b.key)).toContain("config");
+  });
+
   test("exportPresentationBuiltins includes install options", () => {
     const builtins = exportPresentationBuiltins(fixture);
     const install = builtins.find((b) => b.key === "install");

package/src/builtins/config.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Cli, type CliProgram } from "../index.ts";
+
+function configFixture(configPath: string): CliProgram {
+  return {
+    key: "cfg-app",
+    version: "1.0.0",
+    description: "Config builtin test.",
+    appConfig: {
+      path: configPath,
+      entries: {
+        apiToken: { description: "Token.", env: "API_TOKEN", sensitive: true },
+        port: { description: "Port.", required: false },
+      },
+    },
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  };
+}
+
+describe("builtins/config", () => {
+  test("config get redacts sensitive values", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
+    const configPath = join(dir, "config");
+    writeFileSync(configPath, `${JSON.stringify({ apiToken: "secret" })}\n`);
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const result = await new Cli(configFixture(configPath)).invoke(["config", "get", "apiToken"]);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe("REDACTED");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("config get --json redacts sensitive as { set: true }", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
+    const configPath = join(dir, "config");
+    writeFileSync(configPath, `${JSON.stringify({ apiToken: "secret" })}\n`);
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const result = await new Cli(configFixture(configPath)).invoke([
+        "config",
+        "get",
+        "apiToken",
+        "--json",
+      ]);
+      expect(result.exitCode).toBe(0);
+      expect(JSON.parse(result.stdout.trim())).toEqual({ set: true });
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("config set writes and resolves without required exit", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
+    const configPath = join(dir, "config");
+    writeFileSync(configPath, `${JSON.stringify({ apiToken: "present" })}\n`);
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const result = await new Cli(configFixture(configPath)).invoke([
+        "config",
+        "set",
+        "port",
+        "9090",
+      ]);
+      expect(result.exitCode).toBe(0);
+      const get = await new Cli(configFixture(configPath)).invoke(["config", "get", "port"]);
+      expect(get.stdout.trim()).toBe("9090");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});