padrone 1.0.0 → 1.2.0

package/src/errors.ts

@@ -0,0 +1,131 @@
+/**
+ * Structured error hierarchy for Padrone CLI framework.
+ *
+ * All Padrone errors extend `PadroneError`, which carries an exit code,
+ * optional suggestions, and context about which command/phase produced the error.
+ * This allows callers to distinguish user errors (bad input) from bugs (unexpected throws)
+ * and to present formatted, actionable error messages.
+ */
+
+export type PadroneErrorOptions = {
+  /** Process exit code. Defaults to 1. */
+  exitCode?: number;
+  /** Actionable suggestions shown to the user (e.g. "Use --env production"). */
+  suggestions?: string[];
+  /** The command path that produced the error (e.g. "deploy staging"). */
+  command?: string;
+  /** The phase where the error occurred. */
+  phase?: 'parse' | 'validate' | 'execute' | 'config';
+  /** Original cause for error chaining. */
+  cause?: unknown;
+};
+
+/**
+ * Base error class for all Padrone errors.
+ * Carries structured metadata for user-friendly formatting and programmatic handling.
+ *
+ * @example
+ * ```ts
+ * throw new PadroneError('Something went wrong', {
+ *   exitCode: 1,
+ *   suggestions: ['Try --help for usage information'],
+ * });
+ * ```
+ */
+export class PadroneError extends Error {
+  readonly exitCode: number;
+  readonly suggestions: string[];
+  readonly command?: string;
+  readonly phase?: 'parse' | 'validate' | 'execute' | 'config';
+
+  constructor(message: string, options?: PadroneErrorOptions) {
+    super(message, options?.cause ? { cause: options.cause } : undefined);
+    this.name = 'PadroneError';
+    this.exitCode = options?.exitCode ?? 1;
+    this.suggestions = options?.suggestions ?? [];
+    this.command = options?.command;
+    this.phase = options?.phase;
+  }
+
+  /**
+   * Returns a serializable representation of the error,
+   * suitable for non-terminal runtimes (web UIs, APIs, etc.).
+   */
+  toJSON(): {
+    name: string;
+    message: string;
+    exitCode: number;
+    suggestions: string[];
+    command?: string;
+    phase?: string;
+  } {
+    return {
+      name: this.name,
+      message: this.message,
+      exitCode: this.exitCode,
+      suggestions: this.suggestions,
+      command: this.command,
+      phase: this.phase,
+    };
+  }
+}
+
+/**
+ * Thrown when command routing fails — unknown command, unexpected arguments, etc.
+ */
+export class RoutingError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions) {
+    super(message, { phase: 'parse', ...options });
+    this.name = 'RoutingError';
+  }
+}
+
+/**
+ * Thrown when argument or schema validation fails.
+ * Carries the structured issues from the schema validator.
+ */
+export class ValidationError extends PadroneError {
+  readonly issues: readonly { path?: PropertyKey[]; message: string }[];
+
+  constructor(message: string, issues: readonly { path?: PropertyKey[]; message: string }[], options?: PadroneErrorOptions) {
+    super(message, { phase: 'validate', ...options });
+    this.name = 'ValidationError';
+    this.issues = issues;
+  }
+
+  override toJSON() {
+    return {
+      ...super.toJSON(),
+      issues: this.issues.map((i) => ({ path: i.path?.map(String), message: i.message })),
+    };
+  }
+}
+
+/**
+ * Thrown when config file loading or validation fails.
+ */
+export class ConfigError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions) {
+    super(message, { phase: 'config', ...options });
+    this.name = 'ConfigError';
+  }
+}
+
+/**
+ * Thrown from user action handlers to surface structured errors with exit codes and suggestions.
+ * This is the primary error class users should throw from their command actions.
+ *
+ * @example
+ * ```ts
+ * throw new ActionError('Missing environment', {
+ *   exitCode: 1,
+ *   suggestions: ['Use --env production or --env staging'],
+ * });
+ * ```
+ */
+export class ActionError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions) {
+    super(message, { phase: 'execute', ...options });
+    this.name = 'ActionError';
+  }
+}

package/src/formatter.ts

@@ -10,7 +10,7 @@ export type HelpDetail = 'minimal' | 'standard' | 'full';
 /**
  * Information about a single positional argument.
  */
-export type HelpArgumentInfo = {
+export type HelpPositionalInfo = {
   name: string;
   description?: string;
   optional: boolean;
@@ -19,9 +19,9 @@ export type HelpArgumentInfo = {
 };
 
 /**
- * Information about a single option/flag.
+ * Information about a single argument/flag.
  */
-export type HelpOptionInfo = {
+export type HelpArgumentInfo = {
   name: string;
   description?: string;
   optional: boolean;
@@ -32,13 +32,13 @@ export type HelpOptionInfo = {
   deprecated?: boolean | string;
   hidden?: boolean;
   examples?: unknown[];
-  /** Environment variable(s) this option can be set from */
+  /** Environment variable(s) this arg can be set from */
   env?: string | string[];
-  /** Whether this option is an array type (shown as <type...>) */
+  /** Whether this arg is an array type (shown as <type...>) */
   variadic?: boolean;
-  /** Whether this option is a boolean (shown as --[no-]option) */
+  /** Whether this arg is a boolean (shown as --[no-]arg) */
   negatable?: boolean;
-  /** Config file key that maps to this option */
+  /** Config file key that maps to this arg */
   configKey?: string;
 };
 
@@ -52,6 +52,16 @@ export type HelpSubcommandInfo = {
   aliases?: string[];
   deprecated?: boolean | string;
   hidden?: boolean;
+  hasSubcommands?: boolean;
+};
+
+/**
+ * Information about a built-in command/flag entry.
+ */
+export type HelpBuiltinInfo = {
+  name: string;
+  description?: string;
+  sub?: { name: string; description?: string }[];
 };
 
 /**
@@ -75,15 +85,19 @@ export type HelpInfo = {
   usage: {
     command: string;
     hasSubcommands: boolean;
+    hasPositionals: boolean;
     hasArguments: boolean;
-    hasOptions: boolean;
+    /** The name of the field that reads from stdin, if any. Shown as `[stdin > field]` in usage. */
+    stdinField?: string;
   };
   /** List of subcommands */
   subcommands?: HelpSubcommandInfo[];
   /** Positional arguments */
+  positionals?: HelpPositionalInfo[];
+  /** Arguments/flags (only visible ones, hidden filtered out) */
   arguments?: HelpArgumentInfo[];
-  /** Options/flags (only visible ones, hidden filtered out) */
-  options?: HelpOptionInfo[];
+  /** Built-in commands and flags (shown only for root command) */
+  builtins?: HelpBuiltinInfo[];
   /** Full help info for nested commands (used in 'full' detail mode) */
   nestedCommands?: HelpInfo[];
 };
@@ -110,7 +124,7 @@ export type Formatter = {
  */
 type Styler = {
   command: (text: string) => string;
-  option: (text: string) => string;
+  arg: (text: string) => string;
   type: (text: string) => string;
   description: (text: string) => string;
   label: (text: string) => string;
@@ -138,7 +152,7 @@ type LayoutConfig = {
 function createTextStyler(): Styler {
   return {
     command: (text) => text,
-    option: (text) => text,
+    arg: (text) => text,
     type: (text) => text,
     description: (text) => text,
     label: (text) => text,
@@ -153,7 +167,7 @@ function createAnsiStyler(): Styler {
   const colorizer = createColorizer();
   return {
     command: colorizer.command,
-    option: colorizer.option,
+    arg: colorizer.arg,
     type: colorizer.type,
     description: colorizer.description,
     label: colorizer.label,
@@ -179,7 +193,7 @@ function createConsoleStyler(): Styler {
   };
   return {
     command: (text) => `${colors.cyan}${colors.bold}${text}${colors.reset}`,
-    option: (text) => `${colors.green}${text}${colors.reset}`,
+    arg: (text) => `${colors.green}${text}${colors.reset}`,
     type: (text) => `${colors.yellow}${text}${colors.reset}`,
     description: (text) => `${colors.dim}${text}${colors.reset}`,
     label: (text) => `${colors.bold}${text}${colors.reset}`,
@@ -193,7 +207,7 @@ function createConsoleStyler(): Styler {
 function createMarkdownStyler(): Styler {
   return {
     command: (text) => `**${text}**`,
-    option: (text) => `\`${text}\``,
+    arg: (text) => `\`${text}\``,
     type: (text) => `\`${text}\``,
     description: (text) => text,
     label: (text) => `### ${text}`,
@@ -211,7 +225,7 @@ function escapeHtml(text: string): string {
 function createHtmlStyler(): Styler {
   return {
     command: (text) => `<strong style="color: #00bcd4;">${escapeHtml(text)}</strong>`,
-    option: (text) => `<code style="color: #4caf50;">${escapeHtml(text)}</code>`,
+    arg: (text) => `<code style="color: #4caf50;">${escapeHtml(text)}</code>`,
     type: (text) => `<code style="color: #ff9800;">${escapeHtml(text)}</code>`,
     description: (text) => `<span style="color: #666;">${escapeHtml(text)}</span>`,
     label: (text) => `<h3>${escapeHtml(text)}</h3>`,
@@ -269,12 +283,16 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
   const { newline, indent, join, wrapDocument, usageLabel } = layout;
 
   function formatUsageSection(info: HelpInfo): string[] {
-    const usageParts: string[] = [
-      styler.command(info.usage.command),
-      info.usage.hasSubcommands ? styler.meta('[command]') : '',
-      info.usage.hasArguments ? styler.meta('[args...]') : '',
-      info.usage.hasOptions ? styler.meta('[options]') : '',
-    ];
+    const usageParts: string[] = [styler.command(info.usage.command), info.usage.hasSubcommands ? styler.meta('[command]') : ''];
+    // Show actual positional argument names in usage line
+    if (info.positionals && info.positionals.length > 0) {
+      for (const arg of info.positionals) {
+        const name = arg.name.startsWith('...') ? `${arg.name}` : arg.name;
+        usageParts.push(styler.meta(arg.optional ? `[${name}]` : `<${name}>`));
+      }
+    }
+    if (info.usage.hasArguments) usageParts.push(styler.meta('[options]'));
+    if (info.usage.stdinField) usageParts.push(styler.meta(`[stdin > ${info.usage.stdinField}]`));
     return [`${usageLabel} ${join(usageParts)}`];
   }
 
@@ -284,18 +302,40 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
 
     lines.push(styler.label('Commands:'));
 
+    const subcommandSuffix = (c: HelpSubcommandInfo) => (c.hasSubcommands ? ' <subcommand>' : '');
+    const formatAliasParts = (c: HelpSubcommandInfo) => {
+      if (!c.aliases?.length) return { plain: '', styled: '' };
+      const realAliases = c.aliases.filter((a) => a !== '[default]');
+      const hasDefault = c.aliases.some((a) => a === '[default]');
+      const parts: string[] = [];
+      const styledParts: string[] = [];
+      if (realAliases.length) {
+        parts.push(`(${realAliases.join(', ')})`);
+        styledParts.push(`(${realAliases.join(', ')})`);
+      }
+      if (hasDefault) {
+        parts.push('[default]');
+        styledParts.push(styler.meta('[default]'));
+      }
+      return { plain: parts.length ? ` ${parts.join(' ')}` : '', styled: styledParts.length ? ` ${styledParts.join(' ')}` : '' };
+    };
     const maxNameLength = Math.max(
       ...subcommands.map((c) => {
-        const aliases = c.aliases ? ` (${c.aliases.join(', ')})` : '';
-        return (c.name + aliases).length;
+        return (c.name + subcommandSuffix(c) + formatAliasParts(c).plain).length;
       }),
     );
     for (const subCmd of subcommands) {
-      const aliases = subCmd.aliases ? ` (${subCmd.aliases.join(', ')})` : '';
-      const commandDisplay = subCmd.name + aliases;
+      const aliasParts = formatAliasParts(subCmd);
+      const suffix = subcommandSuffix(subCmd);
+      const commandDisplay = subCmd.name + suffix + aliasParts.plain;
       const padding = ' '.repeat(Math.max(0, maxNameLength - commandDisplay.length + 2));
       const isDeprecated = !!subCmd.deprecated;
-      const commandName = isDeprecated ? styler.deprecated(commandDisplay) : styler.command(subCmd.name) + aliases;
+      const isDefaultEntry = subCmd.name === '[default]';
+      const commandName = isDeprecated
+        ? styler.deprecated(commandDisplay)
+        : (isDefaultEntry ? styler.meta(subCmd.name) : styler.command(subCmd.name)) +
+          (suffix ? styler.meta(suffix) : '') +
+          aliasParts.styled;
       const lineParts: string[] = [commandName, padding];
 
       // Use title if available, otherwise use description
@@ -317,14 +357,14 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
     return lines;
   }
 
-  function formatArgumentsSection(info: HelpInfo): string[] {
+  function formatPositionalsSection(info: HelpInfo): string[] {
     const lines: string[] = [];
-    const args = info.arguments!;
+    const args = info.positionals!;
 
     lines.push(styler.label('Arguments:'));
 
     for (const arg of args) {
-      const parts: string[] = [styler.option(arg.name)];
+      const parts: string[] = [styler.arg(arg.name)];
       if (arg.optional) parts.push(styler.meta('(optional)'));
       if (arg.default !== undefined) parts.push(styler.meta(`(default: ${String(arg.default)})`));
       lines.push(indent(1) + join(parts));
@@ -337,54 +377,54 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
     return lines;
   }
 
-  function formatOptionsSection(info: HelpInfo): string[] {
+  function formatArgumentsSection(info: HelpInfo): string[] {
     const lines: string[] = [];
-    const options = info.options!;
+    const argList = info.arguments || [];
 
     lines.push(styler.label('Options:'));
 
-    const maxNameLength = Math.max(...options.map((opt) => opt.name.length));
-
-    for (const opt of options) {
-      // Format option name: --[no-]option for booleans, --option otherwise
-      const optionName = opt.negatable ? `--[no-]${opt.name}` : `--${opt.name}`;
-      const aliasNames = opt.aliases && opt.aliases.length > 0 ? opt.aliases.map((a) => `-${a}`).join(', ') : '';
-      const fullOptionName = aliasNames ? `${optionName}, ${aliasNames}` : optionName;
-      const padding = ' '.repeat(Math.max(0, maxNameLength - opt.name.length + 2));
-      const isDeprecated = !!opt.deprecated;
-      const formattedOptionName = isDeprecated ? styler.deprecated(fullOptionName) : styler.option(fullOptionName);
-
-      const parts: string[] = [formattedOptionName];
-      if (opt.type) parts.push(styler.type(`<${opt.type}>`));
-      if (opt.optional && !opt.deprecated) parts.push(styler.meta('(optional)'));
-      if (opt.default !== undefined) parts.push(styler.meta(`(default: ${String(opt.default)})`));
-      if (opt.enum) parts.push(styler.meta(`(choices: ${opt.enum.join(', ')})`));
-      if (opt.variadic) parts.push(styler.meta('(repeatable)'));
+    const maxNameLength = Math.max(...argList.map((arg) => arg.name.length));
+
+    for (const arg of argList) {
+      // Format arg name: --[no-]arg for booleans, --arg otherwise
+      const argName = arg.negatable ? `--[no-]${arg.name}` : `--${arg.name}`;
+      const aliasNames = arg.aliases && arg.aliases.length > 0 ? arg.aliases.map((a) => `-${a}`).join(', ') : '';
+      const fullArgName = aliasNames ? `${argName}, ${aliasNames}` : argName;
+      const padding = ' '.repeat(Math.max(0, maxNameLength - arg.name.length + 2));
+      const isDeprecated = !!arg.deprecated;
+      const formattedArgName = isDeprecated ? styler.deprecated(fullArgName) : styler.arg(fullArgName);
+
+      const parts: string[] = [formattedArgName];
+      if (arg.type) parts.push(styler.type(`<${arg.type}>`));
+      if (arg.optional && !arg.deprecated) parts.push(styler.meta('(optional)'));
+      if (arg.default !== undefined) parts.push(styler.meta(`(default: ${String(arg.default)})`));
+      if (arg.enum) parts.push(styler.meta(`(choices: ${arg.enum.join(', ')})`));
+      if (arg.variadic) parts.push(styler.meta('(repeatable)'));
       if (isDeprecated) {
         const deprecatedMeta =
-          typeof opt.deprecated === 'string' ? styler.meta(`(deprecated: ${opt.deprecated})`) : styler.meta('(deprecated)');
+          typeof arg.deprecated === 'string' ? styler.meta(`(deprecated: ${arg.deprecated})`) : styler.meta('(deprecated)');
         parts.push(deprecatedMeta);
       }
 
-      const description = opt.description ? styler.description(opt.description) : '';
+      const description = arg.description ? styler.description(arg.description) : '';
       lines.push(indent(1) + join(parts) + padding + description);
 
       // Environment variable line
-      if (opt.env) {
-        const envVars = typeof opt.env === 'string' ? [opt.env] : opt.env;
+      if (arg.env) {
+        const envVars = typeof arg.env === 'string' ? [arg.env] : arg.env;
         const envParts: string[] = [styler.example('Env:'), styler.exampleValue(envVars.join(', '))];
         lines.push(indent(3) + join(envParts));
       }
 
       // Config key line
-      if (opt.configKey) {
-        const configParts: string[] = [styler.example('Config:'), styler.exampleValue(opt.configKey)];
+      if (arg.configKey) {
+        const configParts: string[] = [styler.example('Config:'), styler.exampleValue(arg.configKey)];
         lines.push(indent(3) + join(configParts));
       }
 
       // Examples line
-      if (opt.examples && opt.examples.length > 0) {
-        const exampleValues = opt.examples.map((example) => (typeof example === 'string' ? example : JSON.stringify(example))).join(', ');
+      if (arg.examples && arg.examples.length > 0) {
+        const exampleValues = arg.examples.map((example) => (typeof example === 'string' ? example : JSON.stringify(example))).join(', ');
         const exampleParts: string[] = [styler.example('Example:'), styler.exampleValue(exampleValues)];
         lines.push(indent(3) + join(exampleParts));
       }
@@ -393,6 +433,44 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
     return lines;
   }
 
+  function formatBuiltinsSection(info: HelpInfo): string[] {
+    const lines: string[] = [];
+    const builtins = info.builtins!;
+
+    lines.push(styler.label('Built-in:'));
+
+    // Compute max effective name length for alignment across main and sub entries
+    const allLengths: number[] = [];
+    for (const entry of builtins) {
+      allLengths.push(entry.name.length);
+      if (entry.sub) {
+        for (const sub of entry.sub) {
+          // Sub entries get extra indent(2) - indent(1) = 2 chars
+          allLengths.push(sub.name.length + 2);
+        }
+      }
+    }
+    const maxLen = Math.max(...allLengths);
+
+    for (const entry of builtins) {
+      const padding = ' '.repeat(Math.max(2, maxLen - entry.name.length + 2));
+      const parts: string[] = [styler.command(entry.name)];
+      if (entry.description) parts.push(padding + styler.description(entry.description));
+      lines.push(indent(1) + parts.join(''));
+
+      if (entry.sub) {
+        for (const sub of entry.sub) {
+          const subPadding = ' '.repeat(Math.max(2, maxLen - sub.name.length));
+          const subParts: string[] = [styler.arg(sub.name)];
+          if (sub.description) subParts.push(subPadding + styler.description(sub.description));
+          lines.push(indent(2) + subParts.join(''));
+        }
+      }
+    }
+
+    return lines;
+  }
+
   return {
     format(info: HelpInfo): string {
       const lines: string[] = [];
@@ -433,15 +511,18 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
         lines.push('');
       }
 
-      // Arguments section
+      if (info.positionals && info.positionals.length > 0) {
+        lines.push(...formatPositionalsSection(info));
+        lines.push('');
+      }
+
       if (info.arguments && info.arguments.length > 0) {
         lines.push(...formatArgumentsSection(info));
         lines.push('');
       }
 
-      // Options section
-      if (info.options && info.options.length > 0) {
-        lines.push(...formatOptionsSection(info));
+      if (info.builtins && info.builtins.length > 0) {
+        lines.push(...formatBuiltinsSection(info));
         lines.push('');
       }
 
@@ -497,8 +578,13 @@ function createMinimalFormatter(): Formatter {
     format(info: HelpInfo): string {
       const parts: string[] = [info.usage.command];
       if (info.usage.hasSubcommands) parts.push('[command]');
-      if (info.usage.hasArguments) parts.push('[args...]');
-      if (info.usage.hasOptions) parts.push('[options]');
+      if (info.positionals && info.positionals.length > 0) {
+        for (const arg of info.positionals) {
+          const name = arg.name.startsWith('...') ? `${arg.name}` : arg.name;
+          parts.push(arg.optional ? `[${name}]` : `<${name}>`);
+        }
+      }
+      if (info.usage.hasArguments) parts.push('[options]');
       return parts.join(' ');
     },
   };