padrone 1.5.0 → 1.7.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,44 @@
+export type { PadroneAutoOutputOptions } from './auto-output.ts';
+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;
+}