padrone 1.4.0 → 1.6.0

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';

package/src/extension/ink.ts

@@ -0,0 +1,93 @@
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+import type { InterceptorExecuteResult } from '../types/interceptor.ts';
+
+// ── React element detection ─────────────────────────────────────────────
+
+const reactElement = Symbol.for('react.element');
+const reactTransitional = Symbol.for('react.transitional.element');
+
+/** Checks whether a value is a React element (JSX) by inspecting its `$$typeof` symbol. */
+export function isReactElement(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  const tag = (value as Record<string | symbol, unknown>).$$typeof;
+  return tag === reactElement || tag === reactTransitional;
+}
+
+// ── Types ───────────────────────────────────────────────────────────────
+
+export 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;
+};
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const inkMeta = { id: 'padrone:ink', name: 'padrone:ink', order: -1050 } as const;
+
+function createInkInterceptor(rawOptions?: InkOptions) {
+  return defineInterceptor(inkMeta)
+    .requires<{ inkConfig?: InkOptions }>()
+    .factory(() => ({
+      execute(ctx, next) {
+        const ctxCfg = (ctx.context as Record<string, unknown> | undefined)?.inkConfig as InkOptions | undefined;
+        const options: InkOptions = { ...ctxCfg, ...rawOptions };
+        const { waitUntilExit = true } = options;
+
+        const handleResult = async (e: InterceptorExecuteResult): Promise<InterceptorExecuteResult> => {
+          let value = e.result;
+          if (value instanceof Promise) value = await value;
+          if (!isReactElement(value)) return e;
+
+          const { render } = await import('ink');
+          const instance = render(value as import('react').ReactElement, options.render);
+
+          // Unmount on abort so Ink cleans up stdin/stdout
+          const onAbort = () => instance.unmount();
+          ctx.signal.addEventListener('abort', onAbort, { once: true });
+
+          if (waitUntilExit) {
+            try {
+              await instance.waitUntilExit();
+            } finally {
+              ctx.signal.removeEventListener('abort', onAbort);
+            }
+          }
+
+          // Return undefined so auto-output skips this result
+          return { result: undefined };
+        };
+
+        const executedOrPromise = next();
+        if (executedOrPromise instanceof Promise) return executedOrPromise.then(handleResult);
+        return handleResult(executedOrPromise);
+      },
+    }));
+}
+
+// ── Extension ───────────────────────────────────────────────────────────
+
+/**
+ * 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, padroneInk } from 'padrone';
+ *
+ * const program = createPadrone('my-tui')
+ *   .extend(padroneInk())
+ *   .command('dashboard', (c) =>
+ *     c.action(() => <Dashboard />)
+ *   );
+ * ```
+ */
+export function padroneInk(options?: InkOptions): <T extends CommandTypesBase>(builder: T) => T {
+  const interceptor = createInkInterceptor(options);
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
+}

package/src/extension/interactive.ts

@@ -0,0 +1,106 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { defineInterceptor } from '../core/interceptors.ts';
+import { hasInteractiveConfig, thenMaybe } from '../core/results.ts';
+import { buildCommandArgs, checkUnknownArgs } from '../core/validate.ts';
+import { promptInteractiveFields } from '../feature/interactive.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext, InterceptorValidateResult } from '../types/index.ts';
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const interactiveInterceptor = defineInterceptor({ id: 'padrone:interactive', name: 'padrone:interactive', order: -999 }, () => ({
+  validate(ctx: InterceptorValidateContext, next) {
+    // Extract --interactive / -i flags from rawArgs
+    let flagInteractive: boolean | undefined;
+    if (hasInteractiveConfig(ctx.command.meta)) {
+      if (ctx.rawArgs.interactive !== undefined) {
+        flagInteractive = ctx.rawArgs.interactive !== false && ctx.rawArgs.interactive !== 'false';
+        delete ctx.rawArgs.interactive;
+      }
+      if (ctx.rawArgs.i !== undefined) {
+        flagInteractive = ctx.rawArgs.i !== false && ctx.rawArgs.i !== 'false';
+        delete ctx.rawArgs.i;
+      }
+    }
+
+    // Resolve effective interactivity
+    const { runtime, command } = ctx;
+    const runtimeDefault: boolean | undefined =
+      runtime.interactive === 'forced' ? true : runtime.interactive === 'disabled' ? false : undefined;
+    const effectiveInteractive: boolean | undefined = flagInteractive ?? ctx.evalInteractive ?? runtimeDefault;
+    const commandUsesStdin = !!command.meta?.stdin;
+    const stdinIsPiped = commandUsesStdin && (runtime.stdin ? !runtime.stdin.isTTY : runtime.terminal?.isTTY !== true);
+    const interactivitySuppressed =
+      runtime.interactive === 'unsupported' || effectiveInteractive === false || (stdinIsPiped && effectiveInteractive !== true);
+    const forceInteractive = !interactivitySuppressed && effectiveInteractive === true;
+
+    const willPrompt = !interactivitySuppressed && runtime.prompt && hasInteractiveConfig(command.meta);
+    if (!willPrompt) return next();
+
+    // Preprocess args to determine what's missing
+    const preprocessedArgs = buildCommandArgs(command, ctx.rawArgs, ctx.positionalArgs);
+
+    // Check for unknown args before prompting
+    const unknowns = checkUnknownArgs(command, preprocessedArgs);
+    if (unknowns.length > 0) {
+      const issues: StandardSchemaV1.Issue[] = unknowns.map(({ key }) => ({
+        path: [key],
+        message: `Unknown option: "${key}"`,
+      }));
+      return { args: undefined, argsResult: { issues } } as any;
+    }
+
+    // Early-validate provided fields — fail fast on user-supplied errors before prompting
+    const earlyValidateAndPrompt = (): InterceptorValidateResult | Promise<InterceptorValidateResult> => {
+      if (command.argsSchema) {
+        const providedKeys = new Set(Object.keys(preprocessedArgs).filter((k) => preprocessedArgs[k] !== undefined));
+        const earlyCheck = command.argsSchema['~standard'].validate(preprocessedArgs);
+
+        const checkForProvidedFieldErrors = (result: StandardSchemaV1.Result<unknown>): InterceptorValidateResult | undefined => {
+          if (!result.issues) return undefined;
+          const providedFieldIssues = result.issues.filter((issue: StandardSchemaV1.Issue) => {
+            const rootKey = issue.path?.[0];
+            return rootKey !== undefined && providedKeys.has(String(rootKey));
+          });
+          if (providedFieldIssues.length > 0) return { args: undefined, argsResult: { issues: providedFieldIssues } as any };
+          return undefined;
+        };
+
+        const earlyResult = thenMaybe(earlyCheck, (result) => checkForProvidedFieldErrors(result) ?? undefined);
+        if (earlyResult instanceof Promise) {
+          return earlyResult.then((err) => (err ? err : doPrompt()));
+        }
+        if (earlyResult) return earlyResult;
+      }
+
+      return doPrompt();
+    };
+
+    // Prompt for missing fields, then pass filled args to downstream validation via next()
+    const doPrompt = (): InterceptorValidateResult | Promise<InterceptorValidateResult> => {
+      const afterInteractive = promptInteractiveFields(preprocessedArgs, command, runtime, forceInteractive || undefined);
+
+      return thenMaybe(afterInteractive, (filledArgs) => {
+        // Pass preprocessed+prompted args downstream with empty positionalArgs (already mapped)
+        return next({ rawArgs: filledArgs, positionalArgs: [] });
+      });
+    };
+
+    return earlyValidateAndPrompt();
+  },
+}));
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that handles interactive prompting for missing arguments.
+ * Extracts `--interactive` / `-i` flags, resolves effective interactivity,
+ * and prompts for missing fields before passing filled args to validation.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneInteractive())
+ * ```
+ */
+export function padroneInteractive(): <T extends CommandTypesBase>(builder: T) => T {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interactiveInterceptor)) as any;
+}

package/src/extension/logger.ts

@@ -0,0 +1,214 @@
+import { defineInterceptor } from '#src/core/interceptors.ts';
+import { thenMaybe } from '#src/core/results.ts';
+import type { ResolvedPadroneRuntime } from '#src/core/runtime.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '#src/types/index.ts';
+import type { WithInterceptor } from '#src/util/type-utils.ts';
+import type { PadroneTracer } from './tracing.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Log level values ordered by severity. */
+export type PadroneLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+/** Logger instance injected into the command context. */
+export type PadroneLogger = {
+  trace: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  /** The current effective log level. */
+  level: PadroneLogLevel;
+  /** Create a child logger with a prefix label. */
+  child: (label: string) => PadroneLogger;
+};
+
+/** Configuration for the logger extension. */
+export type PadroneLoggerConfig = {
+  /** Minimum log level to output. Defaults to `'info'`. */
+  level?: PadroneLogLevel;
+  /** Prefix prepended to every log message. */
+  prefix?: string;
+  /** Include timestamps in log output. Defaults to `false`. */
+  timestamps?: boolean;
+};
+
+/** Builder/program type after applying `padroneLogger()`. Adds `{ logger: PadroneLogger }` to the command context. */
+export type WithLogger<T> = WithInterceptor<T, { logger: PadroneLogger }>;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const LEVEL_ORDER: Record<PadroneLogLevel, number> = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, silent: 5 };
+const LEVEL_LABELS: Record<Exclude<PadroneLogLevel, 'silent'>, string> = {
+  trace: 'TRACE',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARN',
+  error: 'ERROR',
+};
+const VALID_LEVELS = new Set<string>(Object.keys(LEVEL_ORDER));
+
+function resolveCliLevel(rawArgs: Record<string, unknown>): PadroneLogLevel | undefined {
+  // --trace → trace level
+  if ('trace' in rawArgs) {
+    const t = rawArgs.trace;
+    delete rawArgs.trace;
+    if (t !== false) return 'trace';
+  }
+  // --verbose / --debug → debug level
+  if ('verbose' in rawArgs) {
+    const v = rawArgs.verbose;
+    delete rawArgs.verbose;
+    if (v !== false) return 'debug';
+  }
+  if ('debug' in rawArgs) {
+    const d = rawArgs.debug;
+    delete rawArgs.debug;
+    if (d !== false) return 'debug';
+  }
+  // --silent / --quiet → suppress all output
+  if ('silent' in rawArgs) {
+    const s = rawArgs.silent;
+    delete rawArgs.silent;
+    if (s !== false) return 'silent';
+  }
+  if ('quiet' in rawArgs) {
+    const q = rawArgs.quiet;
+    delete rawArgs.quiet;
+    if (q !== false) return 'silent';
+  }
+  // --log-level=<level> → explicit level (parser keeps kebab-case)
+  if ('log-level' in rawArgs) {
+    const val = rawArgs['log-level'];
+    delete rawArgs['log-level'];
+    if (typeof val === 'string' && VALID_LEVELS.has(val)) return val as PadroneLogLevel;
+  }
+  return undefined;
+}
+
+function createLogger(
+  runtime: ResolvedPadroneRuntime,
+  level: PadroneLogLevel,
+  config: ResolvedLoggerConfig,
+  tracing?: PadroneTracer,
+): PadroneLogger {
+  const threshold = LEVEL_ORDER[level];
+
+  function format(lvl: Exclude<PadroneLogLevel, 'silent'>, prefix: string, args: unknown[]): string {
+    const parts: string[] = [];
+    if (config.timestamps) parts.push(new Date().toISOString());
+    parts.push(`[${LEVEL_LABELS[lvl]}]`);
+    if (prefix) parts.push(prefix);
+    parts.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' '));
+    return parts.join(' ');
+  }
+
+  function makeLogger(prefix: string): PadroneLogger {
+    const emit = (lvl: Exclude<PadroneLogLevel, 'silent'>, args: unknown[]) => {
+      if (LEVEL_ORDER[lvl] < threshold) return;
+      const message = format(lvl, prefix, args);
+      tracing?.rootSpan.addEvent('log', {
+        'log.level': lvl,
+        'log.message': args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' '),
+      });
+      if (lvl === 'error' || lvl === 'warn') runtime.error(message);
+      else runtime.output(message);
+    };
+
+    return {
+      trace: (...args) => emit('trace', args),
+      debug: (...args) => emit('debug', args),
+      info: (...args) => emit('info', args),
+      warn: (...args) => emit('warn', args),
+      error: (...args) => emit('error', args),
+      level,
+      child: (label) => makeLogger(prefix ? `${prefix} [${label}]` : `[${label}]`),
+    };
+  }
+
+  return makeLogger(config.prefix);
+}
+
+// ---------------------------------------------------------------------------
+// Interceptor
+// ---------------------------------------------------------------------------
+
+type ResolvedLoggerConfig = { level: PadroneLogLevel; prefix: string; timestamps: boolean };
+
+function loggerInterceptor(rawConfig?: PadroneLoggerConfig) {
+  return defineInterceptor({ id: 'padrone:logger', name: 'padrone:logger' })
+    .requires<{ tracing?: PadroneTracer; loggerConfig?: PadroneLoggerConfig }>()
+    .factory(() => {
+      let cliLevel: PadroneLogLevel | undefined;
+
+      return {
+        parse(_ctx, next) {
+          return thenMaybe(next(), (res) => {
+            cliLevel = resolveCliLevel(res.rawArgs);
+            return res;
+          });
+        },
+
+        execute(ctx, next) {
+          const ctxCfg = (ctx.context as Record<string, unknown> | undefined)?.loggerConfig as PadroneLoggerConfig | undefined;
+          const resolved: ResolvedLoggerConfig = {
+            level: cliLevel ?? rawConfig?.level ?? ctxCfg?.level ?? 'info',
+            prefix: rawConfig?.prefix ?? '',
+            timestamps: rawConfig?.timestamps ?? ctxCfg?.timestamps ?? false,
+          };
+          const logger = createLogger(ctx.runtime, resolved.level, resolved, ctx.context?.tracing);
+          return next({ context: { ...ctx.context, logger } });
+        },
+      };
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+/**
+ * Extension that injects a structured logger into the command context.
+ *
+ * The logger respects a configurable log level threshold, supports prefixed
+ * child loggers, and routes output through the runtime's `output`/`error`
+ * functions so it works in any environment (terminal, test, web).
+ *
+ * Supports CLI flags for runtime level overrides:
+ * - `--trace` → sets level to `trace`
+ * - `--verbose` or `--debug` → sets level to `debug`
+ * - `--silent` or `--quiet` → sets level to `silent`
+ * - `--log-level=<level>` → sets an explicit level (`trace`, `debug`, `info`, `warn`, `error`, `silent`)
+ *
+ * CLI flags take precedence over the programmatic config.
+ *
+ * Provides `{ logger: PadroneLogger }` on the command context.
+ * Access it in action handlers as `ctx.context.logger`.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneLogger({ level: 'info' }))
+ *   .command('sync', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('starting sync');
+ *       const db = ctx.context.logger.child('db');
+ *       db.debug('connecting...');
+ *     })
+ *   )
+ * ```
+ *
+ * Then run:
+ * ```sh
+ * my-cli sync --verbose      # debug level
+ * my-cli sync --quiet        # silent
+ * my-cli sync --log-level=warn
+ * ```
+ */
+export function padroneLogger<T extends CommandTypesBase>(config?: PadroneLoggerConfig): (builder: T) => WithLogger<T> {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(loggerInterceptor(config))) as any;
+}