padrone 1.4.0 → 1.6.0

package/src/extension/auto-output.ts

@@ -0,0 +1,95 @@
+import { defineInterceptor } from '../core/interceptors.ts';
+import { isAsyncIterator, isIterator } from '../core/results.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, InterceptorExecuteResult } from '../types/index.ts';
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Outputs each value and collects into a result.
+ * For iterators: outputs each yielded value, returns collected array.
+ * For promises: awaits, then recurses.
+ * For other values: outputs directly, returns as-is.
+ */
+function outputAndCollect(value: unknown, output: (...args: unknown[]) => void): unknown {
+  if (value == null) return value;
+
+  if (isAsyncIterator(value)) {
+    return (async () => {
+      const items: unknown[] = [];
+      const iter = (value as any)[Symbol.asyncIterator]();
+      while (true) {
+        const { done, value: item } = await iter.next();
+        if (done) break;
+        items.push(item);
+        if (item != null) output(item);
+      }
+      return items;
+    })();
+  }
+
+  if (typeof value !== 'string' && !Array.isArray(value) && isIterator(value)) {
+    const items: unknown[] = [];
+    const iter = (value as any)[Symbol.iterator]();
+    while (true) {
+      const { done, value: item } = iter.next();
+      if (done) break;
+      items.push(item);
+      if (item != null) output(item);
+    }
+    return items;
+  }
+
+  if (value instanceof Promise) {
+    return value.then((resolved) => outputAndCollect(resolved, output));
+  }
+
+  output(value);
+  return value;
+}
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const autoOutputMeta = { id: 'padrone:auto-output', name: 'padrone:auto-output', order: -1100 } as const;
+
+const autoOutputInterceptor = defineInterceptor(autoOutputMeta, () => ({
+  execute(ctx, next) {
+    const handleResult = (e: InterceptorExecuteResult): InterceptorExecuteResult | Promise<InterceptorExecuteResult> => {
+      if (e.result instanceof Promise) {
+        return { result: e.result.then((value: unknown) => outputAndCollect(value, ctx.runtime.output)) };
+      }
+
+      const collected = outputAndCollect(e.result, ctx.runtime.output);
+      if (collected instanceof Promise) return collected.then((v) => ({ result: v }));
+      return { result: collected };
+    };
+
+    const executedOrPromise = next();
+    if (executedOrPromise instanceof Promise) return executedOrPromise.then(handleResult);
+    return handleResult(executedOrPromise);
+  },
+}));
+
+// ── Extension ───────────────────────────────────────────────────────────
+
+/**
+ * Extension that automatically writes a command's return value to output after execution.
+ *
+ * - Values are passed directly to the runtime's `output` function (no stringification).
+ * - Promises are awaited before output.
+ * - Iterators and async iterators are consumed, outputting each yielded value as it arrives.
+ *   The result is replaced with the collected array so `drain()` still works.
+ * - `undefined` and `null` results produce no output.
+ *
+ * Included in the default extensions. Can also be applied per-command:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .command('greet', (c) =>
+ *     c.extend(padroneAutoOutput())
+ *       .action(() => 'hello')
+ *   )
+ * ```
+ */
+export function padroneAutoOutput(options?: { disabled?: boolean }): <T extends CommandTypesBase>(builder: T) => T {
+  const interceptor = options?.disabled ? defineInterceptor({ ...autoOutputMeta, disabled: true }, () => ({})) : autoOutputInterceptor;
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
+}

package/src/extension/color.ts

@@ -0,0 +1,38 @@
+import { thenMaybe } from '#src/core/results.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const colorInterceptor = defineInterceptor({ id: 'padrone:color', name: 'padrone:color', order: -1001 }, () => ({
+  parse(ctx, next) {
+    return thenMaybe(next(), (res) => {
+      if ('color' in res.rawArgs) {
+        const color = res.rawArgs.color;
+        delete res.rawArgs.color;
+
+        ctx.runtime.theme = color as any;
+      }
+      return res;
+    });
+  },
+}));
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that handles `--color` / `--no-color` flags:
+ * - `--color` or `--color=true` → use default theme
+ * - `--color=false` or `--no-color` → disable colors (text format)
+ * - `--color=<theme>` → use the named theme
+ *
+ * Modifies the runtime's format and theme accordingly.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneColor())
+ * ```
+ */
+export function padroneColor(): <T extends CommandTypesBase>(builder: T) => T {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(colorInterceptor)) as any;
+}

package/src/extension/completion.ts

@@ -0,0 +1,49 @@
+import type { ShellType } from '#src/util/shell-utils.ts';
+import { resolveAllCommands } from '../core/commands.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, PadroneCommand } from '../types/index.ts';
+import type { PadroneSchema } from '../types/schema.ts';
+import type { WithCommand } from '../util/type-utils.ts';
+import { getRootCommand } from '../util/utils.ts';
+import { passthroughSchema } from './utils.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+type CompletionArgs = { shell?: string; setup?: boolean };
+
+type CompletionCommand = PadroneCommand<'completion', '', PadroneSchema<CompletionArgs>, string, [], [], true>;
+
+export type WithCompletion<T> = WithCommand<T, 'completion', CompletionCommand>;
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds the `completion` command for shell completion script generation.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneCompletion())
+ * ```
+ */
+export function padroneCompletion(): <T extends CommandTypesBase>(builder: T) => WithCompletion<T> {
+  return ((builder: AnyPadroneBuilder) =>
+    builder.command('completion', (c) =>
+      c
+        .configure({ description: 'Generate shell completion scripts', hidden: true })
+        .arguments(passthroughSchema({ shell: 'string', setup: 'boolean' }), { positional: ['shell'] })
+        .async()
+        .action(async (args, ctx) => {
+          const rootCommand = getRootCommand(ctx.command);
+          resolveAllCommands(rootCommand);
+          const { detectShell, generateCompletionOutput, setupCompletions } = await import('../feature/completion.ts');
+          const shell = args.shell as ShellType;
+          const setup = args.setup;
+          if (setup) {
+            const resolvedShell = shell ?? (await detectShell());
+            if (!resolvedShell) throw new Error('Could not detect shell. Specify one: completion bash --setup');
+            const setupResult = await setupCompletions(rootCommand.name, resolvedShell);
+            return `${setupResult.updated ? 'Updated' : 'Added'} ${rootCommand.name} completions in ${setupResult.file}`;
+          }
+          return generateCompletionOutput(rootCommand, shell);
+        }),
+    )) as any;
+}

package/src/extension/config.ts

@@ -0,0 +1,262 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { applyValues } from '../core/args.ts';
+import { ConfigError } from '../core/errors.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import { thenMaybe } from '../core/results.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
+import { getRootCommand } from '../util/utils.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export 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>;
+};
+
+// ── File system config loader ───────────────────────────────────────────
+
+// Lazily resolved Node.js modules — cached after first import to keep loadConfig sync after initialization.
+let _fs: typeof import('node:fs') | undefined;
+let _path: typeof import('node:path') | undefined;
+
+async function initNodeModules(): Promise<void> {
+  if (_fs && _path) return;
+  _fs = await import('node:fs');
+  _path = await import('node:path');
+}
+
+// Eagerly start caching node modules so loadConfig is sync by the time it's called.
+try {
+  if (typeof process !== 'undefined') initNodeModules();
+} catch {
+  // Non-CLI environments (browser, edge) — ignore
+}
+
+function getUserConfigDir(path: typeof import('node:path'), appName: string): string | undefined {
+  const platform = process.platform;
+
+  // Respect XDG_CONFIG_HOME on all platforms when explicitly set
+  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 undefined;
+
+  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);
+
+  // Linux and other Unix — default XDG path
+  return path.join(home, '.config', appName);
+}
+
+function resolveConfigPath(fs: any, path: any, cwd: string, files: string | string[], xdgAppName?: string): string | undefined {
+  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 undefined;
+    }
+    return abs;
+  }
+
+  // Search in cwd first
+  for (const candidate of files) {
+    const abs = path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
+    if (fs.existsSync(abs)) return abs;
+  }
+
+  // Then search in the user config directory (XDG / platform-specific)
+  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;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function loadConfigSync(
+  fs: typeof import('node:fs'),
+  path: typeof import('node:path'),
+  files: string | string[],
+  xdgAppName?: string,
+): Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> {
+  const cwd = process.cwd();
+  const absolutePath = resolveConfigPath(fs, path, cwd, files, xdgAppName);
+  if (!absolutePath) return undefined;
+
+  const getContent = () => fs.readFileSync(absolutePath, 'utf-8');
+  const ext = path.extname(absolutePath).toLowerCase();
+
+  if (ext === '.yaml' || ext === '.yml') return Bun.YAML.parse(getContent()) as any;
+  if (ext === '.toml') return Bun.TOML.parse(getContent()) as any;
+  if (ext === '.jsonc') return Bun.JSONC.parse(getContent()) as any;
+  if (ext === '.json') {
+    if (Bun.JSONC) return Bun.JSONC.parse(getContent()) as any;
+    try {
+      return JSON.parse(getContent());
+    } catch {
+      return Bun.JSONC.parse(getContent()) as any;
+    }
+  }
+  if (ext === '.js' || ext === '.cjs' || ext === '.mjs' || ext === '.ts' || ext === '.cts' || ext === '.mts') {
+    return import(absolutePath).then((mod) => mod.default ?? mod);
+  }
+
+  // Unknown extension — try JSON
+  try {
+    return JSON.parse(getContent());
+  } catch {
+    console.error(`Unable to parse config file: ${absolutePath}`);
+    return undefined;
+  }
+}
+
+/**
+ * Built-in config file loader. Directly accesses the file system.
+ * Returns `undefined` in non-CLI environments where `node:fs` is unavailable.
+ */
+function loadConfig(
+  files: string | string[],
+  xdgAppName?: string,
+): Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> {
+  if (typeof process === 'undefined') return undefined;
+
+  try {
+    if (_fs && _path) return loadConfigSync(_fs, _path, files, xdgAppName);
+    return initNodeModules().then(() => loadConfigSync(_fs!, _path!, files, xdgAppName));
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * 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() }),
+ *   }))
+ * ```
+ */
+export function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => T {
+  if (options?.disabled) {
+    const disabled = defineInterceptor({ id: 'padrone:config', name: 'padrone:config', order: -999, disabled: true }, () => ({}));
+    return ((builder: AnyPadroneBuilder) => builder.intercept(disabled)) as any;
+  }
+
+  const configFiles = options?.files ? (Array.isArray(options.files) ? options.files : [options.files]) : undefined;
+  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: InterceptorValidateContext, next) {
+        // Extract --config / -c from rawArgs
+        let explicitConfigPath: string | undefined;
+        if (flagEnabled) {
+          explicitConfigPath = (ctx.rawArgs.config ?? ctx.rawArgs.c) as string | undefined;
+          if (typeof explicitConfigPath === 'string') {
+            delete ctx.rawArgs.config;
+            delete ctx.rawArgs.c;
+          }
+        }
+
+        // Skip entirely when there's nothing to load
+        if (!explicitConfigPath && !configFiles) return next();
+
+        // Resolve XDG app name: true → derive from root command name, string → use as-is
+        let xdgAppName: string | undefined;
+        if (typeof xdgOption === 'string') xdgAppName = xdgOption;
+        else if (xdgOption === true) xdgAppName = getRootCommand(ctx.command).name;
+
+        // Load config data: explicit --config flag takes priority, then auto-detect
+        const configDataOrPromise = configLoader(explicitConfigPath ?? configFiles ?? [], xdgAppName);
+
+        const applyConfig = (configData: Record<string, unknown> | undefined) => {
+          if (!configData) return next();
+
+          // Validate against schema if provided
+          if (configSchema) {
+            const validated = configSchema['~standard'].validate(configData);
+            return thenMaybe(validated, (result) => {
+              if (result.issues) {
+                const issueMessages = result.issues
+                  .map((i: StandardSchemaV1.Issue) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`)
+                  .join('\n');
+                throw new ConfigError(`Invalid config file:\n${issueMessages}`, {
+                  command: ctx.command.path || ctx.command.name,
+                });
+              }
+              const validatedData = result.value as Record<string, unknown>;
+              const mergedRawArgs = applyValues(ctx.rawArgs, validatedData);
+              return next({ rawArgs: mergedRawArgs });
+            });
+          }
+
+          // No schema — pass through as-is
+          const mergedRawArgs = applyValues(ctx.rawArgs, configData);
+          return next({ rawArgs: mergedRawArgs });
+        };
+
+        return thenMaybe(configDataOrPromise, applyConfig);
+      },
+    }),
+  );
+
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
+}

package/src/extension/env.ts

@@ -0,0 +1,101 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { applyValues } from '../core/args.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import { thenMaybe } from '../core/results.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
+import type { LoadEnvFilesOptions } from '../util/dotenv.ts';
+import { loadEnvFiles } from '../util/dotenv.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export 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;
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function isSchema(value: unknown): value is StandardSchemaV1 {
+  return value != null && typeof value === 'object' && '~standard' in value;
+}
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => T;
+export function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
+export function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
+export function padroneEnv(
+  schemaOrOptions: StandardSchemaV1 | PadroneEnvOptions,
+  maybeOptions?: PadroneEnvOptions,
+): <T extends CommandTypesBase>(builder: T) => T {
+  const schema = isSchema(schemaOrOptions) ? schemaOrOptions : undefined;
+  const options = isSchema(schemaOrOptions) ? maybeOptions : schemaOrOptions;
+  const hasFiles = options?.modes !== undefined;
+  const fileOptions: LoadEnvFilesOptions | undefined = hasFiles ? options : undefined;
+  const override = options?.override ?? false;
+
+  const interceptor = defineInterceptor({ id: 'padrone:env', name: 'padrone:env', order: -1000 }, () => ({
+    validate(ctx: InterceptorValidateContext, next) {
+      const processEnv = ctx.runtime.env();
+
+      const applyEnv = (envFromFiles: Record<string, string>) => {
+        const rawEnv = override ? { ...processEnv, ...envFromFiles } : { ...envFromFiles, ...processEnv };
+
+        if (schema) {
+          const envValidated = schema['~standard'].validate(rawEnv);
+          return thenMaybe(envValidated, (result) => {
+            if (result.issues || !result.value) return next();
+            return next({ rawArgs: applyValues(ctx.rawArgs, result.value as Record<string, unknown>) });
+          });
+        }
+
+        // No schema — merge file env values directly into rawArgs
+        if (Object.keys(envFromFiles).length > 0) {
+          return next({ rawArgs: applyValues(ctx.rawArgs, envFromFiles) });
+        }
+        return next();
+      };
+
+      if (hasFiles) {
+        const loaded = loadEnvFiles(fileOptions!, processEnv);
+        return thenMaybe(loaded, applyEnv);
+      }
+
+      return applyEnv({});
+    },
+  }));
+
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
+}