padrone 1.4.0 → 1.6.0

package/src/extension/progress.ts

@@ -0,0 +1,299 @@
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { PadroneBarConfig, PadroneProgressIndicator, PadroneProgressOptions, PadroneSpinnerConfig } from '../core/runtime.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+import type { WithInterceptor } from '../util/type-utils.ts';
+import type { PadroneProgressRenderer } from './progress-renderer.ts';
+import { createTerminalProgress } from './progress-renderer.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A progress message value: a plain string, `null` to suppress, or an object with a message and custom indicator icon. */
+export type PadroneProgressMessage = string | null | { message?: string | null; indicator?: string };
+
+/** Per-phase message configuration for progress indicators. */
+export type PadroneProgressMessages<TRes = unknown> = {
+  /** Message shown during async validation. Defaults to `''` (spinner only). */
+  validation?: string;
+  /** Message shown while the command's action is running. */
+  progress?: string;
+  /** Message shown when the command succeeds. `null` to suppress. Defaults to the `progress` message. */
+  success?: PadroneProgressMessage | ((result: TRes) => PadroneProgressMessage);
+  /** Message shown when the command fails. `null` to suppress. Defaults to the error message. */
+  error?: PadroneProgressMessage | ((error: unknown) => PadroneProgressMessage);
+};
+
+/**
+ * Progress indicator configuration with messages, visual options, and renderer.
+ */
+export type PadroneProgressConfig<TRes = unknown> = {
+  /** Per-phase messages. A string sets the `progress` message; an object configures individual phases. */
+  message?: string | PadroneProgressMessages<TRes>;
+  /** Spinner configuration. Default `show` is `'auto'` (visible when bar is not shown). `true` forces spinner to always show (even alongside a bar). */
+  spinner?: PadroneSpinnerConfig;
+  /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'`. */
+  bar?: boolean | PadroneBarConfig;
+  /** Show elapsed time since the indicator started. Can also be started on demand via `update({ time: true })`. */
+  time?: boolean;
+  /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. */
+  eta?: boolean;
+  /**
+   * Custom renderer factory. Called to create the progress indicator.
+   * Defaults to the built-in terminal renderer (`createTerminalProgress`).
+   */
+  renderer?: PadroneProgressRenderer;
+};
+
+/**
+ * Shared progress defaults that can be provided via context instead of repeating
+ * at each call site. Per-instance message fields are excluded — those always come
+ * from the constructor argument.
+ *
+ * Provide via context as `{ progressConfig: PadroneProgressDefaults }`.
+ */
+export type PadroneProgressDefaults = Pick<PadroneProgressConfig, 'message' | 'spinner' | 'bar' | 'time' | 'eta' | 'renderer'>;
+
+/** Builder/program type after applying `padroneProgress()`. Adds `{ progress: PadroneProgressIndicator }` to the command context. */
+export type WithProgress<T> = WithInterceptor<T, { progress: PadroneProgressIndicator }>;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const noopIndicator: PadroneProgressIndicator = {
+  update() {},
+  succeed() {},
+  fail() {},
+  stop() {},
+  pause() {},
+  resume() {},
+};
+
+function resolveMessage(field: unknown, value: unknown, fallback?: string): { message: string | null | undefined; indicator?: string } {
+  const raw = typeof field === 'function' ? (field as (v: unknown) => unknown)(value) : field;
+  if (raw === undefined) return { message: fallback };
+  if (raw === null || typeof raw === 'string') return { message: raw };
+  if (typeof raw === 'object' && raw !== null) {
+    const obj = raw as { message?: string | null; indicator?: string };
+    return { message: obj.message, indicator: obj.indicator };
+  }
+  return { message: fallback };
+}
+
+function cleanup(
+  indicator: PadroneProgressIndicator,
+  successConfig: unknown,
+  errorConfig: unknown,
+  error: unknown,
+  result: unknown,
+  isError: boolean,
+) {
+  if (isError) {
+    const fallback = error instanceof Error ? error.message : String(error);
+    const { message: errorMsg, indicator: errorIcon } = resolveMessage(errorConfig, error, fallback);
+    indicator.fail(errorMsg, errorIcon !== undefined ? { indicator: errorIcon } : undefined);
+  } else {
+    const { message: successMsg, indicator: successIcon } = resolveMessage(successConfig, result);
+    indicator.succeed(successMsg, successIcon !== undefined ? { indicator: successIcon } : undefined);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Interceptor
+// ---------------------------------------------------------------------------
+
+function resolveMessages(raw: string | PadroneProgressMessages | undefined): {
+  progress: string;
+  validation: string;
+  success: unknown;
+  error: unknown;
+} {
+  if (!raw || typeof raw === 'string') {
+    return { progress: raw || 'Working...', validation: '', success: undefined, error: undefined };
+  }
+  return {
+    progress: raw.progress ?? 'Working...',
+    validation: raw.validation ?? '',
+    success: raw.success,
+    error: raw.error,
+  };
+}
+
+function mergeMessages(
+  cmd: ReturnType<typeof resolveMessages>,
+  ctx: ReturnType<typeof resolveMessages>,
+  cmdRaw: string | PadroneProgressMessages | undefined,
+): ReturnType<typeof resolveMessages> {
+  // String shorthand: all fields come from the string, no context fallback for individual fields
+  if (typeof cmdRaw === 'string') return cmd;
+  // Object: per-field fallback to context
+  const obj = (typeof cmdRaw === 'object' ? cmdRaw : undefined) as PadroneProgressMessages | undefined;
+  return {
+    progress: obj?.progress !== undefined ? cmd.progress : (ctx.progress ?? cmd.progress),
+    validation: obj?.validation !== undefined ? cmd.validation : ctx.validation || cmd.validation,
+    success: obj?.success !== undefined ? cmd.success : (ctx.success ?? cmd.success),
+    error: obj?.error !== undefined ? cmd.error : (ctx.error ?? cmd.error),
+  };
+}
+
+function progressInterceptor(config: string | PadroneProgressConfig) {
+  const isObj = typeof config === 'object';
+  const rawMessage = typeof config === 'string' ? config : isObj ? config.message : undefined;
+  // Raw constructor values — undefined means "not set by caller"
+  const rawSpinner = isObj ? config.spinner : undefined;
+  const rawBar = isObj ? config.bar : undefined;
+  const rawRenderer = isObj ? config.renderer : undefined;
+  const rawTime = isObj ? config.time : undefined;
+  const rawEta = isObj ? config.eta : undefined;
+
+  return defineInterceptor({ id: 'padrone:progress', name: 'padrone:progress' })
+    .requires<{ progressConfig?: PadroneProgressDefaults }>()
+    .factory(() => {
+      let indicator: PadroneProgressIndicator | undefined;
+      let restoreOutput: (() => void) | undefined;
+      // Lazily resolved from context + constructor args
+      let resolvedRenderer: PadroneProgressRenderer | undefined;
+      let resolvedOptions: PadroneProgressOptions | undefined;
+      let msgs: ReturnType<typeof resolveMessages> | undefined;
+
+      function resolve(ctx: { context?: { progressConfig?: PadroneProgressDefaults } }) {
+        if (resolvedRenderer) return;
+        const ctxCfg = (ctx.context as Record<string, unknown> | undefined)?.progressConfig as PadroneProgressDefaults | undefined;
+        const spinner = rawSpinner ?? ctxCfg?.spinner;
+        const bar = rawBar ?? ctxCfg?.bar;
+        const time = rawTime ?? ctxCfg?.time;
+        const eta = rawEta ?? ctxCfg?.eta;
+        resolvedRenderer = rawRenderer ?? ctxCfg?.renderer ?? createTerminalProgress;
+        resolvedOptions =
+          spinner !== undefined || bar !== undefined || time !== undefined || eta !== undefined ? { spinner, bar, time, eta } : undefined;
+        msgs = mergeMessages(resolveMessages(rawMessage), resolveMessages(ctxCfg?.message), rawMessage);
+      }
+
+      const teardown = () => {
+        restoreOutput?.();
+        indicator = undefined;
+        restoreOutput = undefined;
+      };
+
+      return {
+        validate(ctx, next) {
+          resolve(ctx);
+          indicator = resolvedRenderer!(msgs!.validation || msgs!.progress, resolvedOptions);
+
+          const originalOutput = ctx.runtime.output;
+          const originalError = ctx.runtime.error;
+          ctx.runtime.output = (...args: unknown[]) => {
+            indicator!.pause();
+            originalOutput(...args);
+            indicator!.resume();
+          };
+          ctx.runtime.error = (text: string) => {
+            indicator!.pause();
+            originalError(text);
+            indicator!.resume();
+          };
+          restoreOutput = () => {
+            ctx.runtime.output = originalOutput;
+            ctx.runtime.error = originalError;
+          };
+
+          return next();
+        },
+
+        execute(ctx, next) {
+          // Transition from validation message to progress message
+          if (indicator && msgs!.validation) indicator.update(msgs!.progress);
+
+          const effectiveIndicator = indicator ?? noopIndicator;
+
+          const onSuccess = (value: unknown) => {
+            cleanup(effectiveIndicator, msgs!.success, msgs!.error, undefined, value, false);
+            teardown();
+          };
+          const onError = (err: unknown) => {
+            if (indicator) {
+              cleanup(indicator, msgs!.success, msgs!.error, err, undefined, true);
+              teardown();
+            }
+            throw err;
+          };
+
+          let result: any;
+          try {
+            result = next({ context: { ...(ctx.context as any), progress: effectiveIndicator } });
+          } catch (err) {
+            onError(err);
+          }
+          if (result instanceof Promise) {
+            return result.then(
+              (r) => {
+                if (r.result instanceof Promise) {
+                  return {
+                    result: r.result.then(
+                      (value: unknown) => {
+                        onSuccess(value);
+                        return value;
+                      },
+                      (err: unknown) => onError(err),
+                    ),
+                  };
+                }
+                onSuccess(r.result);
+                return r;
+              },
+              (err: unknown) => onError(err),
+            );
+          }
+          if (result!.result instanceof Promise) {
+            return {
+              result: result!.result.then(
+                (value: unknown) => {
+                  onSuccess(value);
+                  return value;
+                },
+                (err: unknown) => onError(err),
+              ),
+            };
+          }
+          onSuccess(result!.result);
+          return result;
+        },
+      };
+    })
+    .provides<{ progress: PadroneProgressIndicator }>();
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+/**
+ * Extension that adds an auto-managed progress indicator to the command pipeline.
+ *
+ * - `string` — a single message used for all states.
+ * - `PadroneProgressConfig` — separate messages for validation, progress, success, and error.
+ *
+ * The indicator is automatically started before validation, updated at each phase transition,
+ * and stopped on success (`.succeed()`) or failure (`.fail()`).
+ *
+ * Provides `{ progress: PadroneProgressIndicator }` on the command context.
+ * Access it in action handlers as `ctx.context.progress`.
+ *
+ * Uses the built-in terminal renderer by default. Pass a custom `renderer` for non-terminal
+ * environments (web UIs, testing, etc).
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .command('sync', (c) =>
+ *     c.extend(padroneProgress('Syncing...'))
+ *       .action((_args, ctx) => {
+ *         ctx.context.progress.update('halfway');
+ *       })
+ *   )
+ * ```
+ */
+export function padroneProgress<T extends CommandTypesBase>(config?: string | PadroneProgressConfig): (builder: T) => WithProgress<T> {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(progressInterceptor(config ?? 'Working...'))) as any;
+}

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