padrone 1.5.0 → 1.6.0

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;
+}

package/src/extension/help.ts

@@ -0,0 +1,192 @@
+import { resolveAllCommands, resolveCommand } from '../core/commands.ts';
+import { RoutingError, ValidationError } from '../core/errors.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import { thenMaybe } from '../core/results.ts';
+import { formatIssueMessages } from '../core/validate.ts';
+import type { HelpDetail, HelpFormat } from '../output/formatter.ts';
+import { generateHelp } from '../output/help.ts';
+import type { AnyPadroneBuilder, AnyPadroneCommand, 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 { findCommandInTree, passthroughSchema } from './utils.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+type HelpArgs = { command?: string[]; detail?: HelpDetail; format?: HelpFormat; all?: boolean };
+
+export type HelpCommand = PadroneCommand<'help', '', PadroneSchema<HelpArgs>, string, [], ['h', ''], false>;
+
+export type WithHelp<T> = WithCommand<T, 'help', HelpCommand>;
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const helpInterceptor = defineInterceptor({ id: 'padrone:help', name: 'padrone:help', order: -1000 }, () => {
+  let helpText: string | undefined;
+  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 as HelpDetail | undefined;
+          const format = res.rawArgs.format as HelpFormat | undefined;
+          const all = res.rawArgs.all as boolean | undefined;
+          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;
+        }
+
+        // Track whether the parsed command has no action (for default help in execute phase)
+        if (helpText === undefined) {
+          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 !== undefined) return { args: undefined as any, argsResult: { value: undefined } as any };
+      return next();
+    },
+    execute(ctx, next) {
+      if (helpText !== undefined) 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 targetCommand = targetPath ? findCommandInTree(targetPath, rootCommand) : undefined;
+          const sourceCmd = targetCommand ?? rootCommand;
+
+          ctx.runtime.error(er.error.message);
+
+          if (er.error.suggestions.length > 0) {
+            const visibleCommands = (sourceCmd.commands ?? []).filter((c: AnyPadroneCommand) => !c.hidden && c.name);
+            if (visibleCommands.length > 0) {
+              for (const cmd of visibleCommands) resolveCommand(cmd);
+              const cmdList = visibleCommands.map((c: AnyPadroneCommand) => 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) : undefined;
+          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 ────────────────────────────────────────────────────────────
+
+/**
+ * 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())
+ * ```
+ */
+export function padroneHelp(): <T extends CommandTypesBase>(builder: T) => WithHelp<T> {
+  return ((builder: AnyPadroneBuilder) =>
+    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(' ');
+            const targetCommand = commandName ? findCommandInTree(commandName, rootCommand) : rootCommand;
+            return generateHelp(rootCommand, targetCommand ?? rootCommand, {
+              detail: args.detail as HelpDetail,
+              format: (args.format as HelpFormat) ?? ctx.runtime.format,
+              theme: ctx.runtime.theme,
+              all: args.all,
+              terminal: ctx.runtime.terminal,
+              env: ctx.runtime.env(),
+            });
+          }),
+      )
+      .intercept(helpInterceptor)) as any;
+}

package/src/extension/index.ts

@@ -0,0 +1,43 @@
+export { padroneAutoOutput } from './auto-output.ts';
+export { padroneColor } from './color.ts';
+export type { WithCompletion } from './completion.ts';
+export { padroneCompletion } from './completion.ts';
+export type { PadroneConfigOptions } from './config.ts';
+export { padroneConfig } from './config.ts';
+export type { PadroneEnvOptions } from './env.ts';
+export { padroneEnv } from './env.ts';
+export type { HelpCommand, WithHelp } from './help.ts';
+export { padroneHelp } from './help.ts';
+export type { InkOptions } from './ink.ts';
+export { isReactElement, padroneInk } from './ink.ts';
+export { padroneInteractive } from './interactive.ts';
+export type { PadroneLogger, PadroneLoggerConfig, PadroneLogLevel, WithLogger } from './logger.ts';
+export { padroneLogger } from './logger.ts';
+export type { WithMan } from './man.ts';
+export { padroneMan } from './man.ts';
+export type { WithMcp } from './mcp.ts';
+export { padroneMcp } from './mcp.ts';
+export type {
+  PadroneProgressConfig,
+  PadroneProgressDefaults,
+  PadroneProgressMessage,
+  PadroneProgressMessages,
+  WithProgress,
+} from './progress.ts';
+export { padroneProgress } from './progress.ts';
+export type { PadroneProgressRenderer } from './progress-renderer.ts';
+export { createTerminalProgress } from './progress-renderer.ts';
+export type { WithRepl } from './repl.ts';
+export { padroneRepl } from './repl.ts';
+export type { WithServe } from './serve.ts';
+export { padroneServe } from './serve.ts';
+export { padroneSignalHandling } from './signal.ts';
+export { padroneStdin } from './stdin.ts';
+export { padroneSuggestions } from './suggestions.ts';
+export type { PadroneTimingOptions } from './timing.ts';
+export { padroneTiming } from './timing.ts';
+export type { OtelSpan, OtelTracer, OtelTracerProvider, PadroneTracer, PadroneTracingConfig, WithTracing } from './tracing.ts';
+export { padroneTracing } from './tracing.ts';
+export { padroneUpdateCheck } from './update-check.ts';
+export type { VersionCommand, WithVersion } from './version.ts';
+export { padroneVersion } from './version.ts';