padrone 1.4.0 → 1.6.0

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

package/src/extension/update-check.ts

@@ -0,0 +1,77 @@
+import { thenMaybe } from '#src/core/results.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { UpdateCheckConfig } from '../feature/update-check.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+import { getVersion } from '../util/utils.ts';
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+function createUpdateCheckInterceptor(config: UpdateCheckConfig) {
+  return defineInterceptor({ id: 'padrone:update-check', name: 'padrone:update-check', order: 1000 }, () => {
+    let checkPromise: Promise<(() => void) | undefined> | undefined;
+    let suppressed = false;
+
+    return {
+      start(ctx, next) {
+        const rootCommand = ctx.command;
+        const runtime = ctx.runtime;
+
+        checkPromise = Promise.resolve(getVersion(rootCommand.version)).then((currentVersion) =>
+          import('../feature/update-check.ts').then(({ createUpdateChecker }) =>
+            createUpdateChecker(rootCommand.name, currentVersion, config, runtime),
+          ),
+        );
+
+        return next();
+      },
+      parse(_ctx, next) {
+        return thenMaybe(next(), (res) => {
+          if ('update-check' in res.rawArgs) {
+            if (res.rawArgs['update-check'] === false) suppressed = true;
+            delete res.rawArgs['update-check'];
+          }
+          return res;
+        });
+      },
+      shutdown(_ctx, next) {
+        const result = next();
+        if (suppressed || !checkPromise) return result;
+
+        // Try to show notification synchronously if the check already resolved
+        let resolved: (() => void) | undefined | null = null;
+        checkPromise.then(
+          (fn) => {
+            resolved = fn;
+          },
+          () => {
+            resolved = undefined;
+          },
+        );
+
+        if (resolved !== null) {
+          (resolved as (() => void) | undefined)?.();
+        }
+
+        return result;
+      },
+    };
+  });
+}
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds background update checking:
+ * - Checks for newer versions on npm (or custom registry) in the background
+ * - Shows an update notification after command execution
+ * - Respects `--no-update-check` flag to suppress
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneUpdateCheck({ packageName: 'my-cli' }))
+ * ```
+ */
+export function padroneUpdateCheck(config: UpdateCheckConfig = {}): <T extends CommandTypesBase>(builder: T) => T {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(createUpdateCheckInterceptor(config))) as any;
+}

package/src/extension/utils.ts

@@ -0,0 +1,51 @@
+import type { AnyPadroneCommand, PadroneSchema } from '../types/index.ts';
+
+type SchemaShape = Record<string, 'string' | 'string[]' | 'boolean'>;
+
+type InferPassthroughSchema<T extends SchemaShape> = {
+  [K in keyof T]: T[K] extends 'string' ? string : T[K] extends 'string[]' ? string[] : T[K] extends 'boolean' ? boolean : never;
+};
+
+/** Minimal Standard Schema that passes through known fields, ignoring unknown ones. */
+export function passthroughSchema<TShape extends SchemaShape>(fields: TShape): PadroneSchema<InferPassthroughSchema<TShape>> {
+  return {
+    '~standard': {
+      version: 1 as const,
+      vendor: 'padrone' as const,
+      jsonSchema: {
+        input: () => ({}),
+        output: () => ({}),
+      },
+      validate: (value) => {
+        const input = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+        const result: Record<string, unknown> = {};
+        for (const [name, type] of Object.entries(fields)) {
+          const v = input[name];
+          if (v === undefined) continue;
+          if (type === 'string[]') {
+            if (Array.isArray(v)) result[name] = v.map(String);
+            else if (typeof v === 'string') result[name] = [v];
+          } else if (type === 'string') {
+            if (typeof v === 'string') result[name] = v;
+            else if (Array.isArray(v) && v.length > 0) result[name] = String(v[0]);
+          } else if (type === 'boolean') {
+            result[name] = v === true || v === 'true';
+          }
+        }
+        return { value: result as InferPassthroughSchema<TShape> };
+      },
+    },
+  };
+}
+
+/** Find a command by space-separated name in the command tree. */
+export function findCommandInTree(name: string, rootCommand: AnyPadroneCommand): AnyPadroneCommand | undefined {
+  const parts = name.split(' ').filter(Boolean);
+  let current = rootCommand;
+  for (const part of parts) {
+    const found = current.commands?.find((c) => c.name === part || c.aliases?.includes(part));
+    if (!found) return undefined;
+    current = found;
+  }
+  return current;
+}

package/src/extension/version.ts

@@ -0,0 +1,63 @@
+import { thenMaybe } from '#src/core/results.ts';
+import { resolveCommand } from '../core/commands.ts';
+import { defineInterceptor } from '../core/interceptors.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, getVersion } from '../util/utils.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type VersionCommand = PadroneCommand<'version', '', PadroneSchema<void>, string, [], [], false>;
+
+export type WithVersion<T> = WithCommand<T, 'version', VersionCommand>;
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const versionInterceptor = defineInterceptor({ id: 'padrone:version', name: 'padrone:version', order: -1000 }, () => ({
+  parse(_ctx, next) {
+    return thenMaybe(next(), (res) => {
+      const hasVersionFlag = res.rawArgs.version || res.rawArgs.v || res.rawArgs.V;
+
+      // Only show version for root command (no subcommand matched)
+      if (hasVersionFlag && !res.command.parent) {
+        delete res.rawArgs.version;
+        delete res.rawArgs.v;
+        delete res.rawArgs.V;
+
+        // Route to the version command so its action handles the rest
+        const versionCmd = res.command.commands?.find((c) => c.name === 'version');
+        if (versionCmd) {
+          resolveCommand(versionCmd);
+          return { ...res, command: versionCmd, rawArgs: {}, positionalArgs: [] };
+        }
+      }
+
+      return res;
+    });
+  },
+}));
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds version support:
+ * - `version` command
+ * - `--version` / `-v` / `-V` flags (root command only)
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneVersion())
+ * ```
+ */
+export function padroneVersion(): <T extends CommandTypesBase>(builder: T) => WithVersion<T> {
+  return ((builder: AnyPadroneBuilder) =>
+    builder
+      .command('version', (c) =>
+        c.configure({ description: 'Display the version number', hidden: true }).action((_args, ctx) => {
+          const rootCommand = getRootCommand(ctx.command);
+          return getVersion(rootCommand.version);
+        }),
+      )
+      .intercept(versionInterceptor)) as any;
+}