padrone 1.5.0 → 1.7.0

package/src/extension/repl.ts

@@ -0,0 +1,94 @@
+import { defineInterceptor } from '../core/interceptors.ts';
+import { parseCliInputToParts } from '../core/parse.ts';
+import { withDrain } from '../core/results.ts';
+import type {
+  AnyPadroneBuilder,
+  AnyPadroneCommand,
+  CommandTypesBase,
+  InterceptorStartContext,
+  PadroneCommand,
+  PadroneReplPreferences,
+} from '../types/index.ts';
+import type { PadroneSchema } from '../types/schema.ts';
+import type { WithCommand } from '../util/type-utils.ts';
+import { passthroughSchema } from './utils.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+type ReplArgs = { scope?: string };
+
+type ReplCommand = PadroneCommand<'repl', '', PadroneSchema<ReplArgs>, void, [], [], true>;
+
+export type WithRepl<T> = WithCommand<T, 'repl', ReplCommand>;
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds REPL support:
+ * - `repl` command that starts an interactive REPL
+ * - `--repl` flag that starts the REPL from any invocation
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneRepl())
+ * ```
+ */
+export function padroneRepl(
+  defaults?: PadroneReplPreferences & { disabled?: boolean },
+): <T extends CommandTypesBase>(builder: T) => WithRepl<T> {
+  const disabled = defaults?.disabled;
+  return ((builder: AnyPadroneBuilder) =>
+    builder
+      .command('repl', (c) =>
+        c
+          .configure({ description: 'Start an interactive REPL', hidden: true })
+          .arguments(passthroughSchema({ scope: 'string' }), { positional: ['scope'] })
+          .async()
+          .action(async (args, ctx) => {
+            const prefs: PadroneReplPreferences = { ...defaults, scope: args.scope ?? defaults?.scope };
+            const repl = ctx.program.repl(prefs);
+            const { value } = await repl.drain();
+            return value;
+          }),
+      )
+      .intercept(createReplInterceptor(defaults, disabled))) as any;
+}
+
+function createReplInterceptor(defaults?: PadroneReplPreferences, disabled?: boolean) {
+  return defineInterceptor({ id: 'padrone:repl', name: 'padrone:repl', order: -1000, disabled }, () => ({
+    start(ctx: InterceptorStartContext, next: () => unknown) {
+      const replInfo = checkReplFlag(ctx.input, ctx.command);
+      if (!replInfo) return next();
+
+      const program = ctx.program;
+      if (!program?.repl) return next();
+
+      const prefs: PadroneReplPreferences = { ...defaults, scope: replInfo.scope ?? defaults?.scope };
+
+      // Return a Promise so the pipeline awaits the REPL result
+      return program
+        .repl(prefs)
+        .drain()
+        .then((r: any) => withDrain({ command: ctx.command, args: undefined, result: r.value }));
+    },
+  }));
+}
+
+/** Check for --repl flag in input. */
+function checkReplFlag(input: string | undefined, rootCommand: AnyPadroneCommand): { scope?: string } | null {
+  if (!input) return null;
+
+  const parts = parseCliInputToParts(input);
+  const terms = parts.filter((p) => p.type === 'term').map((p) => p.value);
+  const args = parts.filter((p) => p.type === 'named');
+  const keyIs = (key: string[], name: string) => key.length === 1 && key[0] === name;
+
+  const hasReplFlag = args.some((p) => p.type === 'named' && keyIs(p.key, 'repl'));
+  if (!hasReplFlag) return null;
+
+  const normalizedTerms = [...terms];
+  if (normalizedTerms[0] === rootCommand.name) normalizedTerms.shift();
+
+  const scope = normalizedTerms.length > 0 ? normalizedTerms.join(' ') : undefined;
+  return { scope };
+}

package/src/extension/serve.ts

@@ -0,0 +1,48 @@
+import { resolveAllCommands } from '../core/commands.ts';
+import type { PadroneServePreferences } from '../feature/serve.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 ServeArgs = { port?: string; host?: string; basePath?: string };
+
+type ServeCommand = PadroneCommand<'serve', '', PadroneSchema<ServeArgs>, void, [], [], true>;
+
+export type WithServe<T> = WithCommand<T, 'serve', ServeCommand>;
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds the `serve` command for starting a REST HTTP server.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneServe())
+ * ```
+ */
+export function padroneServe(defaults?: PadroneServePreferences): <T extends CommandTypesBase>(builder: T) => WithServe<T> {
+  return ((builder: AnyPadroneBuilder) =>
+    builder.command('serve', (c) =>
+      c
+        .configure({ description: 'Start a REST HTTP server', hidden: true })
+        .arguments(passthroughSchema({ port: 'string', host: 'string', 'base-path': 'string' }))
+        .async()
+        .action(async (args, ctx) => {
+          const rootCommand = getRootCommand(ctx.command);
+          resolveAllCommands(rootCommand);
+          const { startServeServer } = await import('../feature/serve.ts');
+          const port = args.port ? parseInt(args.port, 10) : undefined;
+          const prefs: PadroneServePreferences = {
+            ...defaults,
+            port: port && !Number.isNaN(port) ? port : defaults?.port,
+            host: args.host ?? defaults?.host,
+            basePath: args['base-path'] ?? defaults?.basePath,
+          };
+          await startServeServer(ctx.program, rootCommand, ctx.program.eval, prefs);
+        }),
+    )) as any;
+}

package/src/extension/signal.ts

@@ -0,0 +1,87 @@
+import { SignalError, signalExitCode } from '../core/errors.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import { thenMaybe } from '../core/results.ts';
+import type { PadroneSignal } from '../core/runtime.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const signalMeta = { id: 'padrone:signal', name: 'padrone:signal', order: -2000 } as const;
+
+const signalInterceptor = defineInterceptor(signalMeta, () => {
+  const abortController = new AbortController();
+  let receivedSignal: PadroneSignal | undefined;
+  let lastSigintTime = 0;
+  let unsubscribe: (() => void) | undefined;
+  const DOUBLE_SIGINT_MS = 2000;
+
+  const cleanup = () => {
+    unsubscribe?.();
+    unsubscribe = undefined;
+  };
+
+  const attachSignalInfo = <T>(result: T): T => {
+    if (receivedSignal && result && typeof result === 'object') {
+      (result as any).signal = receivedSignal;
+      (result as any).exitCode = signalExitCode(receivedSignal);
+    }
+    return result;
+  };
+
+  return {
+    start(ctx, next) {
+      const runtimeExit = ctx.runtime.exit;
+      unsubscribe = ctx.runtime.onSignal?.((sig) => {
+        if (abortController.signal.aborted) {
+          if (sig === 'SIGINT') {
+            const elapsed = Date.now() - lastSigintTime;
+            if (elapsed > 0 && elapsed < DOUBLE_SIGINT_MS) {
+              runtimeExit?.(signalExitCode(sig));
+            }
+            lastSigintTime = Date.now();
+          }
+          return;
+        }
+        if (sig === 'SIGINT') lastSigintTime = Date.now();
+        receivedSignal = sig;
+        abortController.abort(sig);
+      });
+
+      const result = next({ signal: abortController.signal });
+      return thenMaybe(result, (r) => {
+        cleanup();
+        return attachSignalInfo(r);
+      });
+    },
+    error(_ctx, next) {
+      return thenMaybe(next(), (er) => {
+        if (receivedSignal && er.error instanceof Error) {
+          er.error = new SignalError(receivedSignal, { cause: er.error });
+        }
+        return er;
+      });
+    },
+    shutdown(_ctx, next) {
+      cleanup();
+      return next();
+    },
+  };
+});
+
+// ── Extension ───────────────────────────────────────────────────────────
+
+/**
+ * Extension that wires process signal handling (SIGINT, SIGTERM, SIGHUP) into the interceptor lifecycle.
+ *
+ * - Creates an `AbortController` whose signal is propagated to all downstream phases.
+ * - Subscribes to `runtime.onSignal` to forward OS signals to the abort controller.
+ * - Implements SIGINT double-tap: two SIGINTs within 2 seconds force-exits the process.
+ * - Attaches `signal` and `exitCode` to results and errors when interrupted.
+ * - Cleans up the signal subscription on completion or failure.
+ *
+ * Included in the default extensions. Runs at order `-2000` (outermost).
+ */
+export function padroneSignalHandling(options?: { disabled?: boolean }): <T extends CommandTypesBase>(builder: T) => T {
+  const interceptor = options?.disabled ? defineInterceptor({ ...signalMeta, disabled: true }, () => ({})) : signalInterceptor;
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
+}

package/src/extension/stdin.ts

@@ -0,0 +1,62 @@
+import { applyValues, isArrayField, isAsyncStreamField } from '../core/args.ts';
+import { resolveStdin, resolveStdinAlways } from '../core/default-runtime.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
+import { createStdinStream } from '../util/stream.ts';
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const stdinInterceptor = defineInterceptor({ id: 'padrone:stdin', name: 'padrone:stdin', order: -1001 }, () => ({
+  validate(ctx: InterceptorValidateContext, next) {
+    const stdinField = ctx.command.meta?.stdin;
+    if (!stdinField) return next();
+
+    // Skip if the field was already provided via CLI flags
+    if (stdinField in ctx.rawArgs && ctx.rawArgs[stdinField] !== undefined) return next();
+
+    const streamInfo = isAsyncStreamField(ctx.command.argsSchema, stdinField);
+    if (streamInfo) {
+      const stdinForStream = resolveStdinAlways(ctx.runtime as any);
+      const mergedRawArgs = applyValues(ctx.rawArgs, { [stdinField]: createStdinStream(stdinForStream, streamInfo.itemSchema) });
+      return next({ rawArgs: mergedRawArgs });
+    }
+
+    const stdin = resolveStdin(ctx.runtime as any);
+    if (!stdin) return next();
+
+    if (isArrayField(ctx.command.argsSchema, stdinField)) {
+      return (async () => {
+        const lines: string[] = [];
+        for await (const line of stdin.lines()) {
+          lines.push(line);
+        }
+        const mergedRawArgs = applyValues(ctx.rawArgs, { [stdinField]: lines });
+        return next({ rawArgs: mergedRawArgs });
+      })();
+    }
+
+    return stdin.text().then((text) => {
+      if (!text) return next();
+      const mergedRawArgs = applyValues(ctx.rawArgs, { [stdinField]: text });
+      return next({ rawArgs: mergedRawArgs });
+    });
+  },
+}));
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that reads stdin data into the argument field specified by `meta.stdin`.
+ * Included by default via `createPadrone()`.
+ *
+ * Read mode is inferred from the schema type:
+ * - `string` field → reads all stdin as a single string
+ * - `string[]` field → reads stdin line-by-line into an array
+ * - `AsyncIterable` field → returns a stream for line-by-line async consumption
+ *
+ * Stdin is only read when piped (not a TTY) and the field wasn't already provided via CLI flags.
+ */
+export function padroneStdin(options?: { disabled?: boolean }): <T extends CommandTypesBase>(builder: T) => T {
+  const interceptor = options?.disabled ? defineInterceptor({ ...stdinInterceptor, disabled: true }, () => ({})) : stdinInterceptor;
+  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
+}

package/src/extension/suggestions.ts

@@ -0,0 +1,114 @@
+import { resolveCommand, suggestSimilar } from '../core/commands.ts';
+import { RoutingError } from '../core/errors.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import { thenMaybe } from '../core/results.ts';
+import { getKnownOptionNames } from '../core/validate.ts';
+import type { AnyPadroneBuilder, AnyPadroneCommand, CommandTypesBase } from '../types/index.ts';
+
+function formatSuggestions(names: string[], prefix = ''): string {
+  if (names.length === 0) return '';
+  const quoted = names.map((n) => `"${prefix}${n}"`);
+  if (quoted.length === 1) return `Did you mean ${quoted[0]}?`;
+  return `Did you mean ${quoted.slice(0, -1).join(', ')} or ${quoted.at(-1)}?`;
+}
+
+function findSourceCommand(commandPath: string | undefined, root: AnyPadroneCommand): AnyPadroneCommand {
+  if (!commandPath || commandPath === root.name || commandPath === root.path) return root;
+  const parts = commandPath.split(' ');
+  let current = root;
+  for (const part of parts) {
+    const found = current.commands?.find((c) => {
+      resolveCommand(c);
+      return c.name === part || c.aliases?.includes(part);
+    });
+    if (found) current = found;
+    else break;
+  }
+  return current;
+}
+
+function enrichRoutingError(err: unknown, rootCommand: AnyPadroneCommand): unknown {
+  if (!(err instanceof RoutingError)) return err;
+
+  const unknownMatch = err.message.match(/^Unknown command: (\S+)/);
+  const unexpectedMatch = err.message.match(/^Unexpected arguments for '[^']+': (\S+)/);
+  const term = unknownMatch?.[1] ?? unexpectedMatch?.[1];
+  if (!term) return err;
+
+  const sourceCmd = findSourceCommand(err.command, rootCommand);
+
+  const candidateNames: string[] = [];
+  if (sourceCmd.commands) {
+    for (const cmd of sourceCmd.commands) {
+      resolveCommand(cmd);
+      if (!cmd.hidden) {
+        candidateNames.push(cmd.name);
+        if (cmd.aliases) candidateNames.push(...cmd.aliases);
+      }
+    }
+  }
+
+  const similar = suggestSimilar(term, candidateNames);
+  const suggestionText = formatSuggestions(similar);
+  if (!suggestionText) return err;
+
+  const suggestions = [suggestionText];
+  const enrichedMsg = `${err.message}\n\n  ${suggestionText}`;
+  return new RoutingError(enrichedMsg, { suggestions, command: err.command });
+}
+
+function enrichIssuesWithSuggestions(
+  issues: readonly { path?: readonly unknown[]; message: string }[],
+  knownOptions: () => string[],
+): typeof issues {
+  return issues.map((i: any) => {
+    // Handle direct unknown option detection (from checkUnknownArgs)
+    const unknownMatch = i.message?.match(/^Unknown option: "([^"]+)"$/);
+    if (unknownMatch) {
+      const similar = suggestSimilar(unknownMatch[1], knownOptions());
+      if (similar.length) {
+        const hint = formatSuggestions(similar, '--');
+        return { ...i, message: `${i.message} ${hint}` };
+      }
+      return i;
+    }
+
+    // Handle Zod strict schema errors (Unrecognized key(s) in object: "foo")
+    const keys: string[] | undefined = i.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^"]*"([^"]+)"/)?.slice(1);
+    if (!keys?.length) return i;
+    const hints = keys.flatMap((k: string) => {
+      const similar = suggestSimilar(k, knownOptions());
+      return similar.length ? [formatSuggestions(similar, '--')] : [];
+    });
+    if (!hints.length) return i;
+    return { ...i, message: `${i.message} ${hints.join(' ')}` };
+  });
+}
+
+const suggestionsInterceptor = defineInterceptor({ id: 'padrone:suggestions', name: 'padrone:suggestions', order: -500 }, () => ({
+  parse(ctx, next) {
+    try {
+      const result = next();
+      if (result instanceof Promise) {
+        return result.catch((err: unknown) => {
+          throw enrichRoutingError(err, ctx.command);
+        });
+      }
+      return result;
+    } catch (err) {
+      throw enrichRoutingError(err, ctx.command);
+    }
+  },
+  validate(ctx, next) {
+    const result = next();
+    return thenMaybe(result, (v) => {
+      if (!v.argsResult?.issues?.length) return v;
+      const enriched = enrichIssuesWithSuggestions(v.argsResult.issues, () => getKnownOptionNames(ctx.command));
+      return { ...v, argsResult: { ...v.argsResult, issues: enriched } } as typeof v;
+    });
+  },
+}));
+
+export function padroneSuggestions(): <T extends CommandTypesBase>(builder: T) => T {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(suggestionsInterceptor)) as any;
+}

package/src/extension/timing.ts

@@ -0,0 +1,81 @@
+import { defineInterceptor } from '../core/interceptors.ts';
+import { thenMaybe } from '../core/results.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms.toFixed(0)}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(2)}s`;
+  const mins = Math.floor(ms / 60_000);
+  const secs = ((ms % 60_000) / 1000).toFixed(2);
+  return `${mins}m ${secs}s`;
+}
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const timingMeta = { id: 'padrone:timing', name: 'padrone:timing', order: -1002 } as const;
+
+function createTimingInterceptor(enabledByDefault: boolean) {
+  return defineInterceptor(timingMeta, () => {
+    let enabled = enabledByDefault;
+    let startTime = 0;
+
+    return {
+      parse(_ctx, next) {
+        return thenMaybe(next(), (res) => {
+          if ('timing' in res.rawArgs) {
+            enabled = res.rawArgs.timing !== false;
+            delete res.rawArgs.timing;
+          }
+          if ('time' in res.rawArgs) {
+            enabled = res.rawArgs.time !== false;
+            delete res.rawArgs.time;
+          }
+          return res;
+        });
+      },
+      start(_ctx, next) {
+        startTime = performance.now();
+        return next();
+      },
+      shutdown(ctx, next) {
+        return thenMaybe(next(), (res) => {
+          if (enabled) {
+            const elapsed = performance.now() - startTime;
+            ctx.runtime.error(`\nDone in ${formatDuration(elapsed)}`);
+          }
+          return res;
+        });
+      },
+    };
+  });
+}
+
+// ── Extension ───────────────────────────────────────────────────────────
+
+export interface PadroneTimingOptions {
+  /** Enable timing by default without requiring `--time` flag. Default: `false`. */
+  enabled?: boolean;
+}
+
+/**
+ * Extension that tracks command execution time.
+ *
+ * - `--time` / `--timing` → enables timing output
+ * - `--no-time` / `--no-timing` → disables timing output
+ *
+ * Pass `{ enabled: true }` to enable timing by default (can be disabled via `--no-time`).
+ *
+ * Usage:
+ * ```ts
+ * // Opt-in via flag
+ * createPadrone('my-cli').extend(padroneTiming())
+ *
+ * // Always on, opt-out via --no-time
+ * createPadrone('my-cli').extend(padroneTiming({ enabled: true }))
+ * ```
+ */
+export function padroneTiming(options?: PadroneTimingOptions): <T extends CommandTypesBase>(builder: T) => T {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(createTimingInterceptor(options?.enabled ?? false))) as any;
+}

package/src/extension/tracing.ts

@@ -0,0 +1,175 @@
+import { defineInterceptor } from '#src/core/interceptors.ts';
+import { thenMaybe } from '#src/core/results.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '#src/types/index.ts';
+import type { WithInterceptor } from '#src/util/type-utils.ts';
+
+// ---------------------------------------------------------------------------
+// Types — minimal OTEL-compatible interfaces so we don't hard-depend on
+// `@opentelemetry/api`. Users pass their real Tracer / Span instances.
+// ---------------------------------------------------------------------------
+
+/** Minimal subset of OTEL `SpanStatusCode`. */
+type SpanStatusCode = 0 | 1 | 2;
+
+/** Minimal subset of OTEL `SpanStatus`. */
+type SpanStatus = { code: SpanStatusCode; message?: string };
+
+/** Minimal subset of OTEL `Span`. */
+export interface OtelSpan {
+  setAttribute(key: string, value: string | number | boolean): this;
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+  setStatus(status: SpanStatus): this;
+  recordException(error: unknown): this;
+  end(): void;
+  spanContext(): { traceId: string; spanId: string };
+}
+
+/** Minimal subset of OTEL `Tracer`. */
+export interface OtelTracer {
+  startSpan(name: string): OtelSpan;
+}
+
+/** Minimal subset of OTEL `TracerProvider`. */
+export interface OtelTracerProvider {
+  getTracer(name: string, version?: string): OtelTracer;
+}
+
+/** Tracing handle injected into the command context. */
+export type PadroneTracer = {
+  /** The underlying OTEL tracer. */
+  tracer: OtelTracer;
+  /** Root span covering the full command execution. */
+  rootSpan: OtelSpan;
+  /** Run `fn` inside a child span that is automatically ended when `fn` returns (or rejects). */
+  span: <T>(name: string, fn: (span: OtelSpan) => T) => T;
+};
+
+/** Configuration for the tracing extension. */
+export type PadroneTracingConfig = {
+  /** OTEL `TracerProvider`. Required — there is no global fallback. */
+  provider: OtelTracerProvider;
+  /** Service / tracer name. Defaults to the CLI program name. */
+  serviceName?: string;
+};
+
+/** Builder/program type after applying `padroneTracing()`. Adds `{ tracing: PadroneTracer }` to the command context. */
+export type WithTracing<T> = WithInterceptor<T, { tracing: PadroneTracer }>;
+
+// ---------------------------------------------------------------------------
+// Interceptor
+// ---------------------------------------------------------------------------
+
+const OTEL_ERROR: SpanStatusCode = 2;
+
+type ResolvedTracingConfig = { provider: OtelTracerProvider; serviceName: string | undefined };
+
+function tracingInterceptor(config: ResolvedTracingConfig) {
+  return defineInterceptor({ id: 'padrone:tracing', name: 'padrone:tracing', order: -1 }, () => {
+    let rootSpan: OtelSpan;
+    let tracer: OtelTracer;
+
+    return {
+      start(ctx, next) {
+        tracer = config.provider.getTracer(config.serviceName ?? ctx.command.name);
+        return next();
+      },
+
+      execute(ctx, next) {
+        rootSpan = tracer.startSpan(`cli ${ctx.command.name}`);
+
+        const padroneTracer: PadroneTracer = {
+          tracer,
+          rootSpan,
+          span(name, fn) {
+            const child = tracer.startSpan(name);
+            try {
+              const result = fn(child);
+              if (result != null && typeof (result as any).then === 'function') {
+                return (result as any).then(
+                  (v: any) => {
+                    child.end();
+                    return v;
+                  },
+                  (err: unknown) => {
+                    child.recordException(err);
+                    child.setStatus({ code: OTEL_ERROR });
+                    child.end();
+                    throw err;
+                  },
+                );
+              }
+              child.end();
+              return result;
+            } catch (err) {
+              child.recordException(err);
+              child.setStatus({ code: OTEL_ERROR });
+              child.end();
+              throw err;
+            }
+          },
+        };
+
+        return next({ context: { ...(ctx.context as any), tracing: padroneTracer } });
+      },
+
+      error(ctx, next) {
+        rootSpan?.recordException(ctx.error);
+        rootSpan?.setStatus({ code: OTEL_ERROR });
+        return next();
+      },
+
+      shutdown(_ctx, next) {
+        return thenMaybe(next(), (res) => {
+          rootSpan?.end();
+          return res;
+        });
+      },
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+/**
+ * Extension that adds OpenTelemetry tracing to command execution.
+ *
+ * Creates a root span for each command invocation and provides a `PadroneTracer`
+ * on the command context for creating child spans in action handlers.
+ *
+ * When used with `padroneLogger()`, the logger automatically emits span events
+ * for each log call — no extra configuration needed. The logger detects the
+ * tracing context and bridges log output to span events.
+ *
+ * Uses minimal OTEL-compatible interfaces — pass any `TracerProvider` that
+ * implements `getTracer()`. Works with `@opentelemetry/api` or compatible
+ * libraries.
+ *
+ * Provides `{ tracing: PadroneTracer }` on the command context.
+ * Access it in action handlers as `ctx.context.tracing`.
+ *
+ * Usage:
+ * ```ts
+ * import { trace } from '@opentelemetry/api';
+ *
+ * createPadrone('my-cli')
+ *   .extend(padroneTracing({ provider: trace.getTracerProvider() }))
+ *   .extend(padroneLogger())
+ *   .command('deploy', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('deploying');  // also emits a span event
+ *       ctx.context.tracing.span('build', (span) => {
+ *         span.setAttribute('target', 'production');
+ *       });
+ *     })
+ *   )
+ * ```
+ */
+export function padroneTracing<T extends CommandTypesBase>(config: PadroneTracingConfig): (builder: T) => WithTracing<T> {
+  const resolved: ResolvedTracingConfig = {
+    provider: config.provider,
+    serviceName: config.serviceName,
+  };
+  return ((builder: AnyPadroneBuilder) => builder.intercept(tracingInterceptor(resolved))) as any;
+}