padrone 1.8.2 → 2.0.0

package/dist/extension/config.d.mts

@@ -0,0 +1,55 @@
+import { WithAsync } from "../util/type-utils.mjs";
+import { CommandTypesBase } from "../types/command.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/extension/config.d.ts
+type PadroneConfigOptions = {
+  /** Config file names to auto-detect (e.g. `['config.json', '.myapprc']`). First found is used. */files?: string | string[]; /** Schema to validate and transform config file data into the args shape. */
+  schema?: StandardSchemaV1; /** Disable this extension. */
+  disabled?: boolean; /** Whether to add `--config` / `-c` flag support. Defaults to `true`. */
+  flag?: boolean; /** Whether subcommands inherit this interceptor. Defaults to `true`. */
+  inherit?: boolean;
+  /**
+   * Search for config files in the user's platform-specific config directory.
+   * - `true` — use the program name as the subdirectory (e.g. program `'myapp'` → `~/.config/myapp/`).
+   * - `string` — use a custom app name as the subdirectory.
+   * - `false` — disable (default).
+   *
+   * Directories searched (after cwd):
+   * - **Linux**: `$XDG_CONFIG_HOME/<app>` or `~/.config/<app>`
+   * - **macOS**: `~/Library/Application Support/<app>` (or `$XDG_CONFIG_HOME/<app>` when set)
+   * - **Windows**: `%APPDATA%\<app>`
+   *
+   * Config files found in cwd always take precedence over XDG paths.
+   */
+  xdg?: string | boolean;
+  /**
+   * Custom config loader. When provided, replaces the built-in file system loader.
+   * Useful for testing or non-CLI environments.
+   */
+  loadConfig?: (files: string | string[], xdgAppName?: string) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+};
+/**
+ * Extension that handles config file loading, validation, and merging into command arguments.
+ *
+ * Features:
+ * - `--config` / `-c` flag for explicit config file path (can be disabled via `flag: false`)
+ * - Auto-detection of config files from a list of candidate names
+ * - Optional schema validation and transformation of config data
+ * - Directly accesses the file system (gracefully no-ops in non-CLI environments)
+ *
+ * Config values have the lowest precedence (CLI > stdin > env > config).
+ *
+ * Not included in the default built-in extensions — must be explicitly added:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneConfig({
+ *     files: ['config.json', '.myapprc'],
+ *     schema: z.object({ port: z.number(), host: z.string() }),
+ *   }))
+ * ```
+ */
+declare function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+//#endregion
+export { PadroneConfigOptions, padroneConfig };
+//# sourceMappingURL=config.d.mts.map

package/dist/extension/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../src/extension/config.ts"],"mappings":";;;;;KAWY,oBAAA;oGAEV,KAAA,sBAFU;EAIV,MAAA,GAAS,gBAAA;EAET,QAAA,YA0BK;EAxBL,IAAA,YAwB2C;EAtB3C,OAAA;EAsBkD;;;;;;;;;;;;;EARlD,GAAA;EAQyD;AAAA;AAqJ3D;;EAxJE,UAAA,IACE,KAAA,qBACA,UAAA,cACG,MAAA,gCAAsC,OAAA,CAAQ,MAAA;AAAA;;;;;;;;;;;;;;;;AAqJiE;;;;;iBAAtG,aAAA,CAAc,OAAA,GAAU,oBAAA,cAAkC,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,SAAA,CAAU,CAAA"}

package/dist/extension/config.mjs

@@ -0,0 +1,162 @@
+import { applyValues } from "../core/args.mjs";
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+import { ConfigError } from "../core/errors.mjs";
+import { getRootCommand } from "../util/utils.mjs";
+//#region src/extension/config.ts
+let _fs;
+let _path;
+async function initNodeModules() {
+	if (_fs && _path) return;
+	_fs = await import("node:fs");
+	_path = await import("node:path");
+}
+try {
+	if (typeof process !== "undefined") initNodeModules();
+} catch {}
+function getUserConfigDir(path, appName) {
+	const platform = process.platform;
+	const xdgHome = process.env.XDG_CONFIG_HOME;
+	if (xdgHome) return path.join(xdgHome, appName);
+	const home = process.env.HOME || process.env.USERPROFILE;
+	if (!home) return void 0;
+	if (platform === "win32") {
+		const appData = process.env.APPDATA;
+		return appData ? path.join(appData, appName) : path.join(home, "AppData", "Roaming", appName);
+	}
+	if (platform === "darwin") return path.join(home, "Library", "Application Support", appName);
+	return path.join(home, ".config", appName);
+}
+function resolveConfigPath(fs, path, cwd, files, xdgAppName) {
+	if (typeof files === "string") {
+		const abs = path.isAbsolute(files) ? files : path.resolve(cwd, files);
+		if (!fs.existsSync(abs)) {
+			console.error(`Config file not found: ${abs}`);
+			return;
+		}
+		return abs;
+	}
+	for (const candidate of files) {
+		const abs = path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
+		if (fs.existsSync(abs)) return abs;
+	}
+	if (xdgAppName) {
+		const configDir = getUserConfigDir(path, xdgAppName);
+		if (configDir) for (const candidate of files) {
+			const abs = path.join(configDir, candidate);
+			if (fs.existsSync(abs)) return abs;
+		}
+	}
+}
+function loadConfigSync(fs, path, files, xdgAppName) {
+	const absolutePath = resolveConfigPath(fs, path, process.cwd(), files, xdgAppName);
+	if (!absolutePath) return void 0;
+	const getContent = () => fs.readFileSync(absolutePath, "utf-8");
+	const ext = path.extname(absolutePath).toLowerCase();
+	if (ext === ".yaml" || ext === ".yml") return Bun.YAML.parse(getContent());
+	if (ext === ".toml") return Bun.TOML.parse(getContent());
+	if (ext === ".jsonc") return Bun.JSONC.parse(getContent());
+	if (ext === ".json") {
+		if (Bun.JSONC) return Bun.JSONC.parse(getContent());
+		try {
+			return JSON.parse(getContent());
+		} catch {
+			return Bun.JSONC.parse(getContent());
+		}
+	}
+	if (ext === ".js" || ext === ".cjs" || ext === ".mjs" || ext === ".ts" || ext === ".cts" || ext === ".mts") return import(
+		/* @vite-ignore */
+		absolutePath
+).then((mod) => mod.default ?? mod);
+	try {
+		return JSON.parse(getContent());
+	} catch {
+		console.error(`Unable to parse config file: ${absolutePath}`);
+		return;
+	}
+}
+/**
+* Built-in config file loader. Directly accesses the file system.
+* Returns `undefined` in non-CLI environments where `node:fs` is unavailable.
+*/
+function loadConfig(files, xdgAppName) {
+	if (typeof process === "undefined") return void 0;
+	try {
+		if (_fs && _path) return loadConfigSync(_fs, _path, files, xdgAppName);
+		return initNodeModules().then(() => loadConfigSync(_fs, _path, files, xdgAppName));
+	} catch {
+		return;
+	}
+}
+/**
+* Extension that handles config file loading, validation, and merging into command arguments.
+*
+* Features:
+* - `--config` / `-c` flag for explicit config file path (can be disabled via `flag: false`)
+* - Auto-detection of config files from a list of candidate names
+* - Optional schema validation and transformation of config data
+* - Directly accesses the file system (gracefully no-ops in non-CLI environments)
+*
+* Config values have the lowest precedence (CLI > stdin > env > config).
+*
+* Not included in the default built-in extensions — must be explicitly added:
+* ```ts
+* createPadrone('my-cli')
+*   .extend(padroneConfig({
+*     files: ['config.json', '.myapprc'],
+*     schema: z.object({ port: z.number(), host: z.string() }),
+*   }))
+* ```
+*/
+function padroneConfig(options) {
+	if (options?.disabled) {
+		const disabled = defineInterceptor({
+			id: "padrone:config",
+			name: "padrone:config",
+			order: -999,
+			disabled: true
+		}, () => ({}));
+		return ((builder) => builder.intercept(disabled));
+	}
+	const configFiles = options?.files ? Array.isArray(options.files) ? options.files : [options.files] : void 0;
+	const configSchema = options?.schema;
+	const flagEnabled = options?.flag !== false;
+	const inherit = options?.inherit;
+	const xdgOption = options?.xdg;
+	const configLoader = options?.loadConfig ?? loadConfig;
+	const interceptor = defineInterceptor({
+		id: "padrone:config",
+		name: "padrone:config",
+		order: -999,
+		...inherit === false && { inherit: false }
+	}, () => ({ validate(ctx, next) {
+		let explicitConfigPath;
+		if (flagEnabled) {
+			explicitConfigPath = ctx.rawArgs.config ?? ctx.rawArgs.c;
+			if (typeof explicitConfigPath === "string") {
+				delete ctx.rawArgs.config;
+				delete ctx.rawArgs.c;
+			}
+		}
+		if (!explicitConfigPath && !configFiles) return next();
+		let xdgAppName;
+		if (typeof xdgOption === "string") xdgAppName = xdgOption;
+		else if (xdgOption === true) xdgAppName = getRootCommand(ctx.command).name;
+		const configDataOrPromise = configLoader(explicitConfigPath ?? configFiles ?? [], xdgAppName);
+		const applyConfig = (configData) => {
+			if (!configData) return next();
+			if (configSchema) return thenMaybe(configSchema["~standard"].validate(configData), (result) => {
+				if (result.issues) throw new ConfigError(`Invalid config file:\n${result.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n")}`, { command: ctx.command.path || ctx.command.name });
+				const validatedData = result.value;
+				return next({ rawArgs: applyValues(ctx.rawArgs, validatedData) });
+			});
+			return next({ rawArgs: applyValues(ctx.rawArgs, configData) });
+		};
+		return thenMaybe(configDataOrPromise, applyConfig);
+	} }));
+	return ((builder) => builder.intercept(interceptor));
+}
+//#endregion
+export { padroneConfig };
+
+//# sourceMappingURL=config.mjs.map

package/dist/extension/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":[],"sources":["../../src/extension/config.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { applyValues } from '../core/args.ts';\nimport { ConfigError } from '../core/errors.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport { thenMaybe } from '../core/results.ts';\nimport type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';\nimport type { WithAsync } from '../util/type-utils.ts';\nimport { getRootCommand } from '../util/utils.ts';\n\n// ── Types ────────────────────────────────────────────────────────────────\n\nexport type PadroneConfigOptions = {\n  /** Config file names to auto-detect (e.g. `['config.json', '.myapprc']`). First found is used. */\n  files?: string | string[];\n  /** Schema to validate and transform config file data into the args shape. */\n  schema?: StandardSchemaV1;\n  /** Disable this extension. */\n  disabled?: boolean;\n  /** Whether to add `--config` / `-c` flag support. Defaults to `true`. */\n  flag?: boolean;\n  /** Whether subcommands inherit this interceptor. Defaults to `true`. */\n  inherit?: boolean;\n  /**\n   * Search for config files in the user's platform-specific config directory.\n   * - `true` — use the program name as the subdirectory (e.g. program `'myapp'` → `~/.config/myapp/`).\n   * - `string` — use a custom app name as the subdirectory.\n   * - `false` — disable (default).\n   *\n   * Directories searched (after cwd):\n   * - **Linux**: `$XDG_CONFIG_HOME/<app>` or `~/.config/<app>`\n   * - **macOS**: `~/Library/Application Support/<app>` (or `$XDG_CONFIG_HOME/<app>` when set)\n   * - **Windows**: `%APPDATA%\\<app>`\n   *\n   * Config files found in cwd always take precedence over XDG paths.\n   */\n  xdg?: string | boolean;\n  /**\n   * Custom config loader. When provided, replaces the built-in file system loader.\n   * Useful for testing or non-CLI environments.\n   */\n  loadConfig?: (\n    files: string | string[],\n    xdgAppName?: string,\n  ) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;\n};\n\n// ── File system config loader ───────────────────────────────────────────\n\n// Lazily resolved Node.js modules — cached after first import to keep loadConfig sync after initialization.\nlet _fs: typeof import('node:fs') | undefined;\nlet _path: typeof import('node:path') | undefined;\n\nasync function initNodeModules(): Promise<void> {\n  if (_fs && _path) return;\n  _fs = await import('node:fs');\n  _path = await import('node:path');\n}\n\n// Eagerly start caching node modules so loadConfig is sync by the time it's called.\ntry {\n  if (typeof process !== 'undefined') initNodeModules();\n} catch {\n  // Non-CLI environments (browser, edge) — ignore\n}\n\nfunction getUserConfigDir(path: typeof import('node:path'), appName: string): string | undefined {\n  const platform = process.platform;\n\n  // Respect XDG_CONFIG_HOME on all platforms when explicitly set\n  const xdgHome = process.env.XDG_CONFIG_HOME;\n  if (xdgHome) return path.join(xdgHome, appName);\n\n  const home = process.env.HOME || process.env.USERPROFILE;\n  if (!home) return undefined;\n\n  if (platform === 'win32') {\n    const appData = process.env.APPDATA;\n    return appData ? path.join(appData, appName) : path.join(home, 'AppData', 'Roaming', appName);\n  }\n  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', appName);\n\n  // Linux and other Unix — default XDG path\n  return path.join(home, '.config', appName);\n}\n\nfunction resolveConfigPath(fs: any, path: any, cwd: string, files: string | string[], xdgAppName?: string): string | undefined {\n  if (typeof files === 'string') {\n    const abs = path.isAbsolute(files) ? files : path.resolve(cwd, files);\n    if (!fs.existsSync(abs)) {\n      console.error(`Config file not found: ${abs}`);\n      return undefined;\n    }\n    return abs;\n  }\n\n  // Search in cwd first\n  for (const candidate of files) {\n    const abs = path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);\n    if (fs.existsSync(abs)) return abs;\n  }\n\n  // Then search in the user config directory (XDG / platform-specific)\n  if (xdgAppName) {\n    const configDir = getUserConfigDir(path, xdgAppName);\n    if (configDir) {\n      for (const candidate of files) {\n        const abs = path.join(configDir, candidate);\n        if (fs.existsSync(abs)) return abs;\n      }\n    }\n  }\n\n  return undefined;\n}\n\nfunction loadConfigSync(\n  fs: typeof import('node:fs'),\n  path: typeof import('node:path'),\n  files: string | string[],\n  xdgAppName?: string,\n): Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> {\n  const cwd = process.cwd();\n  const absolutePath = resolveConfigPath(fs, path, cwd, files, xdgAppName);\n  if (!absolutePath) return undefined;\n\n  const getContent = () => fs.readFileSync(absolutePath, 'utf-8');\n  const ext = path.extname(absolutePath).toLowerCase();\n\n  if (ext === '.yaml' || ext === '.yml') return Bun.YAML.parse(getContent()) as any;\n  if (ext === '.toml') return Bun.TOML.parse(getContent()) as any;\n  if (ext === '.jsonc') return Bun.JSONC.parse(getContent()) as any;\n  if (ext === '.json') {\n    if (Bun.JSONC) return Bun.JSONC.parse(getContent()) as any;\n    try {\n      return JSON.parse(getContent());\n    } catch {\n      return Bun.JSONC.parse(getContent()) as any;\n    }\n  }\n  if (ext === '.js' || ext === '.cjs' || ext === '.mjs' || ext === '.ts' || ext === '.cts' || ext === '.mts') {\n    return import(/* @vite-ignore */ absolutePath).then((mod) => mod.default ?? mod);\n  }\n\n  // Unknown extension — try JSON\n  try {\n    return JSON.parse(getContent());\n  } catch {\n    console.error(`Unable to parse config file: ${absolutePath}`);\n    return undefined;\n  }\n}\n\n/**\n * Built-in config file loader. Directly accesses the file system.\n * Returns `undefined` in non-CLI environments where `node:fs` is unavailable.\n */\nfunction loadConfig(\n  files: string | string[],\n  xdgAppName?: string,\n): Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> {\n  if (typeof process === 'undefined') return undefined;\n\n  try {\n    if (_fs && _path) return loadConfigSync(_fs, _path, files, xdgAppName);\n    return initNodeModules().then(() => loadConfigSync(_fs!, _path!, files, xdgAppName));\n  } catch {\n    return undefined;\n  }\n}\n\n// ── Extension ────────────────────────────────────────────────────────────\n\n/**\n * Extension that handles config file loading, validation, and merging into command arguments.\n *\n * Features:\n * - `--config` / `-c` flag for explicit config file path (can be disabled via `flag: false`)\n * - Auto-detection of config files from a list of candidate names\n * - Optional schema validation and transformation of config data\n * - Directly accesses the file system (gracefully no-ops in non-CLI environments)\n *\n * Config values have the lowest precedence (CLI > stdin > env > config).\n *\n * Not included in the default built-in extensions — must be explicitly added:\n * ```ts\n * createPadrone('my-cli')\n *   .extend(padroneConfig({\n *     files: ['config.json', '.myapprc'],\n *     schema: z.object({ port: z.number(), host: z.string() }),\n *   }))\n * ```\n */\nexport function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T> {\n  if (options?.disabled) {\n    const disabled = defineInterceptor({ id: 'padrone:config', name: 'padrone:config', order: -999, disabled: true }, () => ({}));\n    return ((builder: AnyPadroneBuilder) => builder.intercept(disabled)) as any;\n  }\n\n  const configFiles = options?.files ? (Array.isArray(options.files) ? options.files : [options.files]) : undefined;\n  const configSchema = options?.schema;\n  const flagEnabled = options?.flag !== false;\n  const inherit = options?.inherit;\n  const xdgOption = options?.xdg;\n  const configLoader = options?.loadConfig ?? loadConfig;\n\n  const interceptor = defineInterceptor(\n    { id: 'padrone:config', name: 'padrone:config', order: -999, ...(inherit === false && { inherit: false }) },\n    () => ({\n      validate(ctx: InterceptorValidateContext, next) {\n        // Extract --config / -c from rawArgs\n        let explicitConfigPath: string | undefined;\n        if (flagEnabled) {\n          explicitConfigPath = (ctx.rawArgs.config ?? ctx.rawArgs.c) as string | undefined;\n          if (typeof explicitConfigPath === 'string') {\n            delete ctx.rawArgs.config;\n            delete ctx.rawArgs.c;\n          }\n        }\n\n        // Skip entirely when there's nothing to load\n        if (!explicitConfigPath && !configFiles) return next();\n\n        // Resolve XDG app name: true → derive from root command name, string → use as-is\n        let xdgAppName: string | undefined;\n        if (typeof xdgOption === 'string') xdgAppName = xdgOption;\n        else if (xdgOption === true) xdgAppName = getRootCommand(ctx.command).name;\n\n        // Load config data: explicit --config flag takes priority, then auto-detect\n        const configDataOrPromise = configLoader(explicitConfigPath ?? configFiles ?? [], xdgAppName);\n\n        const applyConfig = (configData: Record<string, unknown> | undefined) => {\n          if (!configData) return next();\n\n          // Validate against schema if provided\n          if (configSchema) {\n            const validated = configSchema['~standard'].validate(configData);\n            return thenMaybe(validated, (result) => {\n              if (result.issues) {\n                const issueMessages = result.issues\n                  .map((i: StandardSchemaV1.Issue) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`)\n                  .join('\\n');\n                throw new ConfigError(`Invalid config file:\\n${issueMessages}`, {\n                  command: ctx.command.path || ctx.command.name,\n                });\n              }\n              const validatedData = result.value as Record<string, unknown>;\n              const mergedRawArgs = applyValues(ctx.rawArgs, validatedData);\n              return next({ rawArgs: mergedRawArgs });\n            });\n          }\n\n          // No schema — pass through as-is\n          const mergedRawArgs = applyValues(ctx.rawArgs, configData);\n          return next({ rawArgs: mergedRawArgs });\n        };\n\n        return thenMaybe(configDataOrPromise, applyConfig);\n      },\n    }),\n  );\n\n  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;\n}\n"],"mappings":"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"}

package/dist/extension/env.d.mts

@@ -0,0 +1,42 @@
+import { WithAsync } from "../util/type-utils.mjs";
+import { CommandTypesBase } from "../types/command.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/extension/env.d.ts
+type PadroneEnvOptions = {
+  /** Env modes to load (e.g. `['production']`). Loads `.env.{mode}` files. */modes?: string[]; /** Whether to load `.env.local` and `.env.{mode}.local` files. @default true */
+  local?: boolean; /** Directory to search for `.env` files. @default process.cwd() */
+  dir?: string; /** When `true`, file values override `process.env` values. @default false */
+  override?: boolean; /** When `false`, the base `.env` (and `.env.local`) files are not loaded. @default true */
+  base?: boolean;
+};
+/**
+ * Extension that reads environment variables, validates them against a schema,
+ * and merges the transformed values into command arguments.
+ *
+ * Supports loading `.env` files with mode-based overrides and variable expansion.
+ *
+ * ```ts
+ * // Schema only (reads process.env)
+ * .extend(padroneEnv(
+ *   z.object({ PORT: z.string() }).transform(e => ({ port: Number(e.PORT) }))
+ * ))
+ *
+ * // Schema + .env file loading
+ * .extend(padroneEnv(
+ *   z.object({ PORT: z.string() }).transform(e => ({ port: Number(e.PORT) })),
+ *   { modes: ['production'] }
+ * ))
+ *
+ * // .env file loading only (no schema validation)
+ * .extend(padroneEnv({ modes: ['production'] }))
+ * ```
+ *
+ * Env values have lower precedence than CLI args and stdin, but higher than config files.
+ */
+declare function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+declare function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+declare function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+//#endregion
+export { PadroneEnvOptions, padroneEnv };
+//# sourceMappingURL=env.d.mts.map

package/dist/extension/env.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.mts","names":[],"sources":["../../src/extension/env.ts"],"mappings":";;;;;KAWY,iBAAA;8EAEV,KAAA,aAFU;EAIV,KAAA;EAEA,GAAA,WAJA;EAMA,QAAA,YAFA;EAIA,IAAA;AAAA;;AAAI;AAmCN;;;;;;;;;;;;;;;;;;;AAA6G;AAC7G;;iBADgB,UAAA,CAAW,MAAA,EAAQ,gBAAA,cAA8B,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,SAAA,CAAU,CAAA;AAAA,iBAC5F,UAAA,CAAW,MAAA,EAAQ,gBAAA,EAAkB,OAAA,EAAS,iBAAA,cAA+B,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,SAAA,CAAU,CAAA;AAAA,iBACxH,UAAA,CAAW,OAAA,EAAS,iBAAA,cAA+B,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,SAAA,CAAU,CAAA"}

package/dist/extension/env.mjs

@@ -0,0 +1,44 @@
+import { applyValues } from "../core/args.mjs";
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+import { loadEnvFiles } from "../util/dotenv.mjs";
+//#region src/extension/env.ts
+function isSchema(value) {
+	return value != null && typeof value === "object" && "~standard" in value;
+}
+function padroneEnv(schemaOrOptions, maybeOptions) {
+	const schema = isSchema(schemaOrOptions) ? schemaOrOptions : void 0;
+	const options = isSchema(schemaOrOptions) ? maybeOptions : schemaOrOptions;
+	const hasFiles = options?.modes !== void 0;
+	const fileOptions = hasFiles ? options : void 0;
+	const override = options?.override ?? false;
+	const interceptor = defineInterceptor({
+		id: "padrone:env",
+		name: "padrone:env",
+		order: -1e3
+	}, () => ({ validate(ctx, next) {
+		const processEnv = ctx.runtime.env();
+		const applyEnv = (envFromFiles) => {
+			const rawEnv = override ? {
+				...processEnv,
+				...envFromFiles
+			} : {
+				...envFromFiles,
+				...processEnv
+			};
+			if (schema) return thenMaybe(schema["~standard"].validate(rawEnv), (result) => {
+				if (result.issues || !result.value) return next();
+				return next({ rawArgs: applyValues(ctx.rawArgs, result.value) });
+			});
+			if (Object.keys(envFromFiles).length > 0) return next({ rawArgs: applyValues(ctx.rawArgs, envFromFiles) });
+			return next();
+		};
+		if (hasFiles) return thenMaybe(loadEnvFiles(fileOptions, processEnv), applyEnv);
+		return applyEnv({});
+	} }));
+	return ((builder) => builder.intercept(interceptor));
+}
+//#endregion
+export { padroneEnv };
+
+//# sourceMappingURL=env.mjs.map

package/dist/extension/env.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.mjs","names":[],"sources":["../../src/extension/env.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { applyValues } from '../core/args.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport { thenMaybe } from '../core/results.ts';\nimport type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';\nimport type { LoadEnvFilesOptions } from '../util/dotenv.ts';\nimport { loadEnvFiles } from '../util/dotenv.ts';\nimport type { WithAsync } from '../util/type-utils.ts';\n\n// ── Types ────────────────────────────────────────────────────────────────\n\nexport type PadroneEnvOptions = {\n  /** Env modes to load (e.g. `['production']`). Loads `.env.{mode}` files. */\n  modes?: string[];\n  /** Whether to load `.env.local` and `.env.{mode}.local` files. @default true */\n  local?: boolean;\n  /** Directory to search for `.env` files. @default process.cwd() */\n  dir?: string;\n  /** When `true`, file values override `process.env` values. @default false */\n  override?: boolean;\n  /** When `false`, the base `.env` (and `.env.local`) files are not loaded. @default true */\n  base?: boolean;\n};\n\n// ── Helpers ──────────────────────────────────────────────────────────────\n\nfunction isSchema(value: unknown): value is StandardSchemaV1 {\n  return value != null && typeof value === 'object' && '~standard' in value;\n}\n\n// ── Extension ────────────────────────────────────────────────────────────\n\n/**\n * Extension that reads environment variables, validates them against a schema,\n * and merges the transformed values into command arguments.\n *\n * Supports loading `.env` files with mode-based overrides and variable expansion.\n *\n * ```ts\n * // Schema only (reads process.env)\n * .extend(padroneEnv(\n *   z.object({ PORT: z.string() }).transform(e => ({ port: Number(e.PORT) }))\n * ))\n *\n * // Schema + .env file loading\n * .extend(padroneEnv(\n *   z.object({ PORT: z.string() }).transform(e => ({ port: Number(e.PORT) })),\n *   { modes: ['production'] }\n * ))\n *\n * // .env file loading only (no schema validation)\n * .extend(padroneEnv({ modes: ['production'] }))\n * ```\n *\n * Env values have lower precedence than CLI args and stdin, but higher than config files.\n */\nexport function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;\nexport function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;\nexport function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;\nexport function padroneEnv(\n  schemaOrOptions: StandardSchemaV1 | PadroneEnvOptions,\n  maybeOptions?: PadroneEnvOptions,\n): <T extends CommandTypesBase>(builder: T) => WithAsync<T> {\n  const schema = isSchema(schemaOrOptions) ? schemaOrOptions : undefined;\n  const options = isSchema(schemaOrOptions) ? maybeOptions : schemaOrOptions;\n  const hasFiles = options?.modes !== undefined;\n  const fileOptions: LoadEnvFilesOptions | undefined = hasFiles ? options : undefined;\n  const override = options?.override ?? false;\n\n  const interceptor = defineInterceptor({ id: 'padrone:env', name: 'padrone:env', order: -1000 }, () => ({\n    validate(ctx: InterceptorValidateContext, next) {\n      const processEnv = ctx.runtime.env();\n\n      const applyEnv = (envFromFiles: Record<string, string>) => {\n        const rawEnv = override ? { ...processEnv, ...envFromFiles } : { ...envFromFiles, ...processEnv };\n\n        if (schema) {\n          const envValidated = schema['~standard'].validate(rawEnv);\n          return thenMaybe(envValidated, (result) => {\n            if (result.issues || !result.value) return next();\n            return next({ rawArgs: applyValues(ctx.rawArgs, result.value as Record<string, unknown>) });\n          });\n        }\n\n        // No schema — merge file env values directly into rawArgs\n        if (Object.keys(envFromFiles).length > 0) {\n          return next({ rawArgs: applyValues(ctx.rawArgs, envFromFiles) });\n        }\n        return next();\n      };\n\n      if (hasFiles) {\n        const loaded = loadEnvFiles(fileOptions!, processEnv);\n        return thenMaybe(loaded, applyEnv);\n      }\n\n      return applyEnv({});\n    },\n  }));\n\n  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;\n}\n"],"mappings":";;;;;AA0BA,SAAS,SAAS,OAA2C;CAC3D,OAAO,SAAS,QAAQ,OAAO,UAAU,YAAY,eAAe;AACtE;AA+BA,SAAgB,WACd,iBACA,cAC0D;CAC1D,MAAM,SAAS,SAAS,eAAe,IAAI,kBAAkB,KAAA;CAC7D,MAAM,UAAU,SAAS,eAAe,IAAI,eAAe;CAC3D,MAAM,WAAW,SAAS,UAAU,KAAA;CACpC,MAAM,cAA+C,WAAW,UAAU,KAAA;CAC1E,MAAM,WAAW,SAAS,YAAY;CAEtC,MAAM,cAAc,kBAAkB;EAAE,IAAI;EAAe,MAAM;EAAe,OAAO;CAAM,UAAU,EACrG,SAAS,KAAiC,MAAM;EAC9C,MAAM,aAAa,IAAI,QAAQ,IAAI;EAEnC,MAAM,YAAY,iBAAyC;GACzD,MAAM,SAAS,WAAW;IAAE,GAAG;IAAY,GAAG;GAAa,IAAI;IAAE,GAAG;IAAc,GAAG;GAAW;GAEhG,IAAI,QAEF,OAAO,UADc,OAAO,YAAY,CAAC,SAAS,MACtB,IAAI,WAAW;IACzC,IAAI,OAAO,UAAU,CAAC,OAAO,OAAO,OAAO,KAAK;IAChD,OAAO,KAAK,EAAE,SAAS,YAAY,IAAI,SAAS,OAAO,KAAgC,EAAE,CAAC;GAC5F,CAAC;GAIH,IAAI,OAAO,KAAK,YAAY,CAAC,CAAC,SAAS,GACrC,OAAO,KAAK,EAAE,SAAS,YAAY,IAAI,SAAS,YAAY,EAAE,CAAC;GAEjE,OAAO,KAAK;EACd;EAEA,IAAI,UAEF,OAAO,UADQ,aAAa,aAAc,UACpB,GAAG,QAAQ;EAGnC,OAAO,SAAS,CAAC,CAAC;CACpB,EACF,EAAE;CAEF,SAAS,YAA+B,QAAQ,UAAU,WAAW;AACvE"}

package/dist/extension/help.d.mts

@@ -0,0 +1,29 @@
+import { HelpDetail, HelpFormat } from "../output/formatter.mjs";
+import { PadroneSchema } from "../types/schema.mjs";
+import { WithCommand } from "../util/type-utils.mjs";
+import { CommandTypesBase, PadroneCommand } from "../types/command.mjs";
+//#region src/extension/help.d.ts
+type HelpArgs = {
+  command?: string[];
+  detail?: HelpDetail;
+  format?: HelpFormat;
+  all?: boolean;
+};
+type HelpCommand = PadroneCommand<'help', '', PadroneSchema<HelpArgs>, string, [], ['h', ''], false>;
+type WithHelp<T> = WithCommand<T, 'help', HelpCommand>;
+/**
+ * Extension that adds help support:
+ * - `help` command with aliases `h` and `` (empty = executes on root when no subcommand matches)
+ * - `--help` / `-h` flags
+ * - `<cmd> help` reverse syntax
+ * - Default help display when a command has no action
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneHelp())
+ * ```
+ */
+declare function padroneHelp(): <T extends CommandTypesBase>(builder: T) => WithHelp<T>;
+//#endregion
+export { HelpCommand, WithHelp, padroneHelp };
+//# sourceMappingURL=help.d.mts.map

package/dist/extension/help.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.mts","names":[],"sources":["../../src/extension/help.ts"],"mappings":";;;;;KAeK,QAAA;EAAa,OAAA;EAAoB,MAAA,GAAS,UAAA;EAAY,MAAA,GAAS,UAAU;EAAE,GAAA;AAAA;AAAA,KAEpE,WAAA,GAAc,cAAA,aAA2B,aAAA,CAAc,QAAA;AAAA,KAEvD,QAAA,MAAc,WAAA,CAAY,CAAA,UAAW,WAAA;;;;;;;AAJkC;AAEnF;;;;;iBAqJgB,WAAA,eAA0B,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,QAAA,CAAS,CAAA"}

package/dist/extension/help.mjs

@@ -0,0 +1,161 @@
+import { resolveAllCommands, resolveCommand } from "../core/commands.mjs";
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+import { RoutingError, ValidationError } from "../core/errors.mjs";
+import { formatIssueMessages } from "../core/validate.mjs";
+import { getRootCommand } from "../util/utils.mjs";
+import { generateHelp } from "../output/help.mjs";
+import { findCommandInTree, passthroughSchema } from "./utils.mjs";
+//#region src/extension/help.ts
+const helpInterceptor = defineInterceptor({
+	id: "padrone:help",
+	name: "padrone:help",
+	order: -1e3
+}, () => {
+	let helpText;
+	let showDefaultHelp = false;
+	return {
+		parse(ctx, next) {
+			return thenMaybe(next(), (res) => {
+				const hasHelpFlag = res.rawArgs.help || res.rawArgs.h;
+				const reverseHelp = !hasHelpFlag && res.positionalArgs?.length > 0 && res.positionalArgs[res.positionalArgs.length - 1] === "help";
+				if (hasHelpFlag || reverseHelp) {
+					delete res.rawArgs.help;
+					delete res.rawArgs.h;
+					const detail = res.rawArgs.detail;
+					const format = res.rawArgs.format;
+					const all = res.rawArgs.all;
+					delete res.rawArgs.detail;
+					delete res.rawArgs.format;
+					delete res.rawArgs.all;
+					delete res.rawArgs.d;
+					delete res.rawArgs.f;
+					const rootCommand = getRootCommand(res.command);
+					resolveAllCommands(rootCommand);
+					helpText = generateHelp(rootCommand, res.command, {
+						detail,
+						format: format ?? ctx.runtime.format,
+						theme: ctx.runtime.theme,
+						all,
+						terminal: ctx.runtime.terminal,
+						env: ctx.runtime.env()
+					});
+					return res;
+				}
+				if (helpText === void 0) {
+					const { command } = res;
+					const hasSubcommands = command.commands && command.commands.length > 0;
+					const hasSchema = command.argsSchema != null;
+					const hasUnmatchedTerms = res.positionalArgs?.length > 0 && !command.meta?.positional?.length;
+					if (!command.action && (hasSubcommands || !hasSchema) && !hasUnmatchedTerms) showDefaultHelp = true;
+				}
+				return res;
+			});
+		},
+		validate(_ctx, next) {
+			if (helpText !== void 0) return {
+				args: void 0,
+				argsResult: { value: void 0 }
+			};
+			return next();
+		},
+		execute(ctx, next) {
+			if (helpText !== void 0) return { result: helpText };
+			if (showDefaultHelp) {
+				const rootCommand = getRootCommand(ctx.command);
+				resolveAllCommands(rootCommand);
+				return { result: generateHelp(rootCommand, ctx.command, {
+					format: ctx.runtime.format,
+					theme: ctx.runtime.theme,
+					terminal: ctx.runtime.terminal,
+					env: ctx.runtime.env()
+				}) };
+			}
+			return next();
+		},
+		error(ctx, next) {
+			return thenMaybe(next(), (er) => {
+				if (ctx.caller !== "cli" || !er.error) return er;
+				const rootCommand = getRootCommand(ctx.command);
+				if (er.error instanceof RoutingError) {
+					const targetPath = er.error.command;
+					const sourceCmd = (targetPath ? findCommandInTree(targetPath, rootCommand) : void 0) ?? rootCommand;
+					ctx.runtime.error(er.error.message);
+					if (er.error.suggestions.length > 0) {
+						const visibleCommands = (sourceCmd.commands ?? []).filter((c) => !c.hidden && c.name);
+						if (visibleCommands.length > 0) {
+							for (const cmd of visibleCommands) resolveCommand(cmd);
+							const cmdList = visibleCommands.map((c) => c.name).join(", ");
+							ctx.runtime.output(`\nAvailable commands: ${cmdList}`);
+						}
+					} else {
+						resolveAllCommands(rootCommand);
+						const helpText = generateHelp(rootCommand, sourceCmd, {
+							format: ctx.runtime.format,
+							theme: ctx.runtime.theme,
+							terminal: ctx.runtime.terminal,
+							env: ctx.runtime.env()
+						});
+						ctx.runtime.error(helpText);
+					}
+					return er;
+				}
+				if (er.error instanceof ValidationError) {
+					const targetPath = er.error.command;
+					const targetCommand = targetPath ? findCommandInTree(targetPath, rootCommand) : void 0;
+					const issueMessages = formatIssueMessages(er.error.issues);
+					resolveAllCommands(rootCommand);
+					const helpText = generateHelp(rootCommand, targetCommand ?? rootCommand, {
+						format: ctx.runtime.format,
+						theme: ctx.runtime.theme,
+						terminal: ctx.runtime.terminal,
+						env: ctx.runtime.env()
+					});
+					ctx.runtime.error(`Validation error:\n${issueMessages}`);
+					ctx.runtime.error(helpText);
+					return er;
+				}
+				return er;
+			});
+		}
+	};
+});
+/**
+* Extension that adds help support:
+* - `help` command with aliases `h` and `` (empty = executes on root when no subcommand matches)
+* - `--help` / `-h` flags
+* - `<cmd> help` reverse syntax
+* - Default help display when a command has no action
+*
+* Usage:
+* ```ts
+* createPadrone('my-cli').extend(padroneHelp())
+* ```
+*/
+function padroneHelp() {
+	return ((builder) => builder.command(["help", "h"], (c) => c.configure({
+		description: "Display help for a command",
+		hidden: true
+	}).arguments(passthroughSchema({
+		command: "string[]",
+		detail: "string",
+		format: "string",
+		all: "boolean"
+	}), { positional: ["...command"] }).action((args, ctx) => {
+		const rootCommand = getRootCommand(ctx.command);
+		resolveAllCommands(rootCommand);
+		const commandName = args.command?.join(" ");
+		return generateHelp(rootCommand, (commandName ? findCommandInTree(commandName, rootCommand) : rootCommand) ?? rootCommand, {
+			detail: args.detail,
+			format: args.format ?? ctx.runtime.format,
+			theme: ctx.runtime.theme,
+			all: args.all,
+			terminal: ctx.runtime.terminal,
+			env: ctx.runtime.env()
+		});
+	})).intercept(helpInterceptor));
+}
+//#endregion
+export { padroneHelp };
+
+//# sourceMappingURL=help.mjs.map

package/dist/extension/help.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.mjs","names":[],"sources":["../../src/extension/help.ts"],"sourcesContent":["import { resolveAllCommands, resolveCommand } from '../core/commands.ts';\nimport { RoutingError, ValidationError } from '../core/errors.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport { thenMaybe } from '../core/results.ts';\nimport { formatIssueMessages } from '../core/validate.ts';\nimport type { HelpDetail, HelpFormat } from '../output/formatter.ts';\nimport { generateHelp } from '../output/help.ts';\nimport type { AnyPadroneBuilder, AnyPadroneCommand, CommandTypesBase, PadroneCommand } from '../types/index.ts';\nimport type { PadroneSchema } from '../types/schema.ts';\nimport type { WithCommand } from '../util/type-utils.ts';\nimport { getRootCommand } from '../util/utils.ts';\nimport { findCommandInTree, passthroughSchema } from './utils.ts';\n\n// ── Types ────────────────────────────────────────────────────────────────\n\ntype HelpArgs = { command?: string[]; detail?: HelpDetail; format?: HelpFormat; all?: boolean };\n\nexport type HelpCommand = PadroneCommand<'help', '', PadroneSchema<HelpArgs>, string, [], ['h', ''], false>;\n\nexport type WithHelp<T> = WithCommand<T, 'help', HelpCommand>;\n\n// ── Interceptor ─────────────────────────────────────────────────────────\n\nconst helpInterceptor = defineInterceptor({ id: 'padrone:help', name: 'padrone:help', order: -1000 }, () => {\n  let helpText: string | undefined;\n  let showDefaultHelp = false;\n\n  return {\n    parse(ctx, next) {\n      return thenMaybe(next(), (res) => {\n        const hasHelpFlag = res.rawArgs.help || res.rawArgs.h;\n        const reverseHelp = !hasHelpFlag && res.positionalArgs?.length > 0 && res.positionalArgs[res.positionalArgs.length - 1] === 'help';\n\n        if (hasHelpFlag || reverseHelp) {\n          delete res.rawArgs.help;\n          delete res.rawArgs.h;\n\n          const detail = res.rawArgs.detail as HelpDetail | undefined;\n          const format = res.rawArgs.format as HelpFormat | undefined;\n          const all = res.rawArgs.all as boolean | undefined;\n          delete res.rawArgs.detail;\n          delete res.rawArgs.format;\n          delete res.rawArgs.all;\n          delete res.rawArgs.d;\n          delete res.rawArgs.f;\n\n          const rootCommand = getRootCommand(res.command);\n          resolveAllCommands(rootCommand);\n\n          helpText = generateHelp(rootCommand, res.command, {\n            detail,\n            format: format ?? ctx.runtime.format,\n            theme: ctx.runtime.theme,\n            all,\n            terminal: ctx.runtime.terminal,\n            env: ctx.runtime.env(),\n          });\n          return res;\n        }\n\n        // Track whether the parsed command has no action (for default help in execute phase)\n        if (helpText === undefined) {\n          const { command } = res;\n          const hasSubcommands = command.commands && command.commands.length > 0;\n          const hasSchema = command.argsSchema != null;\n          const hasUnmatchedTerms = res.positionalArgs?.length > 0 && !command.meta?.positional?.length;\n          if (!command.action && (hasSubcommands || !hasSchema) && !hasUnmatchedTerms) {\n            showDefaultHelp = true;\n          }\n        }\n\n        return res;\n      });\n    },\n    validate(_ctx, next) {\n      if (helpText !== undefined) return { args: undefined as any, argsResult: { value: undefined } as any };\n      return next();\n    },\n    execute(ctx, next) {\n      if (helpText !== undefined) return { result: helpText };\n      if (showDefaultHelp) {\n        const rootCommand = getRootCommand(ctx.command);\n        resolveAllCommands(rootCommand);\n        return {\n          result: generateHelp(rootCommand, ctx.command, {\n            format: ctx.runtime.format,\n            theme: ctx.runtime.theme,\n            terminal: ctx.runtime.terminal,\n            env: ctx.runtime.env(),\n          }),\n        };\n      }\n      return next();\n    },\n    error(ctx, next) {\n      return thenMaybe(next(), (er) => {\n        if (ctx.caller !== 'cli' || !er.error) return er;\n\n        const rootCommand = getRootCommand(ctx.command);\n\n        if (er.error instanceof RoutingError) {\n          const targetPath = er.error.command;\n          const targetCommand = targetPath ? findCommandInTree(targetPath, rootCommand) : undefined;\n          const sourceCmd = targetCommand ?? rootCommand;\n\n          ctx.runtime.error(er.error.message);\n\n          if (er.error.suggestions.length > 0) {\n            const visibleCommands = (sourceCmd.commands ?? []).filter((c: AnyPadroneCommand) => !c.hidden && c.name);\n            if (visibleCommands.length > 0) {\n              for (const cmd of visibleCommands) resolveCommand(cmd);\n              const cmdList = visibleCommands.map((c: AnyPadroneCommand) => c.name).join(', ');\n              ctx.runtime.output(`\\nAvailable commands: ${cmdList}`);\n            }\n          } else {\n            resolveAllCommands(rootCommand);\n            const helpText = generateHelp(rootCommand, sourceCmd, {\n              format: ctx.runtime.format,\n              theme: ctx.runtime.theme,\n              terminal: ctx.runtime.terminal,\n              env: ctx.runtime.env(),\n            });\n            ctx.runtime.error(helpText);\n          }\n\n          return er;\n        }\n\n        if (er.error instanceof ValidationError) {\n          const targetPath = er.error.command;\n          const targetCommand = targetPath ? findCommandInTree(targetPath, rootCommand) : undefined;\n          const issueMessages = formatIssueMessages(er.error.issues);\n\n          resolveAllCommands(rootCommand);\n          const helpText = generateHelp(rootCommand, targetCommand ?? rootCommand, {\n            format: ctx.runtime.format,\n            theme: ctx.runtime.theme,\n            terminal: ctx.runtime.terminal,\n            env: ctx.runtime.env(),\n          });\n          ctx.runtime.error(`Validation error:\\n${issueMessages}`);\n          ctx.runtime.error(helpText);\n\n          return er;\n        }\n\n        return er;\n      });\n    },\n  };\n});\n\n// ── Extension ────────────────────────────────────────────────────────────\n\n/**\n * Extension that adds help support:\n * - `help` command with aliases `h` and `` (empty = executes on root when no subcommand matches)\n * - `--help` / `-h` flags\n * - `<cmd> help` reverse syntax\n * - Default help display when a command has no action\n *\n * Usage:\n * ```ts\n * createPadrone('my-cli').extend(padroneHelp())\n * ```\n */\nexport function padroneHelp(): <T extends CommandTypesBase>(builder: T) => WithHelp<T> {\n  return ((builder: AnyPadroneBuilder) =>\n    builder\n      .command(['help', 'h'], (c) =>\n        c\n          .configure({ description: 'Display help for a command', hidden: true })\n          .arguments(passthroughSchema({ command: 'string[]', detail: 'string', format: 'string', all: 'boolean' }), {\n            positional: ['...command'],\n          })\n          .action((args, ctx) => {\n            const rootCommand = getRootCommand(ctx.command);\n            resolveAllCommands(rootCommand);\n            const commandName = args.command?.join(' ');\n            const targetCommand = commandName ? findCommandInTree(commandName, rootCommand) : rootCommand;\n            return generateHelp(rootCommand, targetCommand ?? rootCommand, {\n              detail: args.detail as HelpDetail,\n              format: (args.format as HelpFormat) ?? ctx.runtime.format,\n              theme: ctx.runtime.theme,\n              all: args.all,\n              terminal: ctx.runtime.terminal,\n              env: ctx.runtime.env(),\n            });\n          }),\n      )\n      .intercept(helpInterceptor)) as any;\n}\n"],"mappings":"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"}

package/dist/extension/index.d.mts

@@ -0,0 +1,18 @@
+import { WithAsync } from "../util/type-utils.mjs";
+import { PadroneLogLevel, PadroneLogger, PadroneLoggerConfig, WithLogger, padroneLogger } from "./logger.mjs";
+import { HelpCommand, WithHelp, padroneHelp } from "./help.mjs";
+import { VersionCommand, WithVersion, padroneVersion } from "./version.mjs";
+import { PadroneAutoOutputOptions, padroneAutoOutput } from "./auto-output.mjs";
+import { padroneColor } from "./color.mjs";
+import { PadroneConfigOptions, padroneConfig } from "./config.mjs";
+import { PadroneEnvOptions, padroneEnv } from "./env.mjs";
+import { padroneInteractive } from "./interactive.mjs";
+import { PadroneProgressRenderer, createTerminalProgress } from "./progress-renderer.mjs";
+import { PadroneProgressConfig, PadroneProgressDefaults, PadroneProgressMessage, PadroneProgressMessages, WithProgress, padroneProgress } from "./progress.mjs";
+import { WithRepl, padroneRepl } from "./repl.mjs";
+import { padroneSignalHandling } from "./signal.mjs";
+import { padroneStdin } from "./stdin.mjs";
+import { padroneSuggestions } from "./suggestions.mjs";
+import { PadroneTimingOptions, padroneTiming } from "./timing.mjs";
+import { padroneUpdateCheck } from "./update-check.mjs";
+export { type HelpCommand, type PadroneLogLevel, type PadroneLogger, type PadroneLoggerConfig, type PadroneProgressConfig, type PadroneProgressDefaults, type PadroneProgressMessage, type PadroneProgressMessages, type PadroneProgressRenderer, type VersionCommand, type WithAsync, type WithHelp, type WithLogger, type WithProgress, type WithRepl, type WithVersion, createTerminalProgress, padroneAutoOutput, padroneColor, padroneConfig, padroneEnv, padroneHelp, padroneInteractive, padroneLogger, padroneProgress, padroneRepl, padroneSignalHandling, padroneStdin, padroneSuggestions, padroneTiming, padroneUpdateCheck, padroneVersion };

package/dist/extension/ink.d.mts

@@ -0,0 +1,31 @@
+import { CommandTypesBase } from "../types/command.mjs";
+//#region src/extension/ink.d.ts
+/** Checks whether a value is a React element (JSX) by inspecting its `$$typeof` symbol. */
+declare function isReactElement(value: unknown): boolean;
+type InkOptions = {
+  /** Whether to wait for the Ink app to unmount before resolving. Defaults to `true`. */waitUntilExit?: boolean; /** Options forwarded to Ink's `render()`. */
+  render?: import('ink').RenderOptions;
+};
+/**
+ * Extension that renders React (Ink) components returned from command actions.
+ *
+ * When a command's action returns a React element (JSX), this extension
+ * renders it using Ink instead of passing it to the normal output path.
+ *
+ * Requires `ink` and `react` as peer dependencies.
+ *
+ * ```ts
+ * import { createPadrone } from 'padrone';
+ * import { padroneInk } from 'padrone/ink';
+ *
+ * const program = createPadrone('my-tui')
+ *   .extend(padroneInk())
+ *   .command('dashboard', (c) =>
+ *     c.action(() => <Dashboard />)
+ *   );
+ * ```
+ */
+declare function padroneInk(options?: InkOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+export { InkOptions, isReactElement, padroneInk };
+//# sourceMappingURL=ink.d.mts.map

package/dist/extension/ink.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ink.d.mts","names":[],"sources":["../../src/extension/ink.ts"],"mappings":";;;iBAUgB,cAAA,CAAe,KAAc;AAAA,KAQjC,UAAA;EARI,uFAUd,aAAA;EAEA,MAAA,iBAAuB,aAAA;AAAA;AAJzB;;;;;;;;AAIsC;AAoEtC;;;;;;;;;;AAxEA,iBAwEgB,UAAA,CAAW,OAAA,GAAU,UAAA,cAAwB,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,CAAA"}