padrone 1.4.0 → 1.6.0

package/src/{formatter.ts → output/formatter.ts}

@@ -1,5 +1,24 @@
-import { camelToKebab } from './args.ts';
-import { createColorizer } from './colorizer.ts';
+import { camelToKebab } from '../util/shell-utils.ts';
+import { type ColorConfig, type ColorTheme, createColorizer } from './colorizer.ts';
+
+const DEFAULT_TERMINAL_WIDTH = 80;
+
+function wrapText(text: string, maxWidth: number): string[] {
+  if (maxWidth <= 0 || text.length <= maxWidth) return [text];
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let current = '';
+  for (const word of words) {
+    if (current && current.length + 1 + word.length > maxWidth) {
+      lines.push(current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.length > 0 ? lines : [text];
+}
 
 export type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';
 export type HelpDetail = 'minimal' | 'standard' | 'full';
@@ -45,6 +64,8 @@ export type HelpArgumentInfo = {
   negatable?: boolean;
   /** Config file key that maps to this arg */
   configKey?: string;
+  /** Group name for organizing this option under a labeled section in help output */
+  group?: string;
 };
 
 /**
@@ -58,6 +79,8 @@ export type HelpSubcommandInfo = {
   deprecated?: boolean | string;
   hidden?: boolean;
   hasSubcommands?: boolean;
+  /** Group name for organizing this command under a labeled section in help output */
+  group?: string;
 };
 
 /**
@@ -103,6 +126,8 @@ export type HelpInfo = {
   arguments?: HelpArgumentInfo[];
   /** Built-in commands and flags (shown only for root command) */
   builtins?: HelpBuiltinInfo[];
+  /** Command-level usage examples (shown in help output) */
+  examples?: string[];
   /** Full help info for nested commands (used in 'full' detail mode) */
   nestedCommands?: HelpInfo[];
 };
@@ -133,6 +158,7 @@ type Styler = {
   type: (text: string) => string;
   description: (text: string) => string;
   label: (text: string) => string;
+  section: (text: string) => string;
   meta: (text: string) => string;
   example: (text: string) => string;
   exampleValue: (text: string) => string;
@@ -147,7 +173,6 @@ type LayoutConfig = {
   indent: (level: number) => string;
   join: (parts: string[]) => string;
   wrapDocument?: (content: string) => string;
-  usageLabel: string;
 };
 
 // ============================================================================
@@ -161,6 +186,7 @@ function createTextStyler(): Styler {
     type: (text) => text,
     description: (text) => text,
     label: (text) => text,
+    section: (text) => text,
     meta: (text) => text,
     example: (text) => text,
     exampleValue: (text) => text,
@@ -168,14 +194,15 @@ function createTextStyler(): Styler {
   };
 }
 
-function createAnsiStyler(): Styler {
-  const colorizer = createColorizer();
+function createAnsiStyler(theme?: ColorTheme | ColorConfig): Styler {
+  const colorizer = createColorizer(theme);
   return {
     command: colorizer.command,
     arg: colorizer.arg,
     type: colorizer.type,
     description: colorizer.description,
     label: colorizer.label,
+    section: colorizer.label,
     meta: colorizer.meta,
     example: colorizer.example,
     exampleValue: colorizer.exampleValue,
@@ -183,30 +210,8 @@ function createAnsiStyler(): Styler {
   };
 }
 
-function createConsoleStyler(): Styler {
-  const colors = {
-    reset: '\x1b[0m',
-    bold: '\x1b[1m',
-    dim: '\x1b[2m',
-    italic: '\x1b[3m',
-    underline: '\x1b[4m',
-    strikethrough: '\x1b[9m',
-    cyan: '\x1b[36m',
-    green: '\x1b[32m',
-    yellow: '\x1b[33m',
-    gray: '\x1b[90m',
-  };
-  return {
-    command: (text) => `${colors.cyan}${colors.bold}${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}`,
-    meta: (text) => `${colors.gray}${text}${colors.reset}`,
-    example: (text) => `${colors.underline}${text}${colors.reset}`,
-    exampleValue: (text) => `${colors.italic}${text}${colors.reset}`,
-    deprecated: (text) => `${colors.strikethrough}${colors.gray}${text}${colors.reset}`,
-  };
+function createConsoleStyler(theme?: ColorTheme | ColorConfig): Styler {
+  return createAnsiStyler(theme);
 }
 
 function createMarkdownStyler(): Styler {
@@ -215,7 +220,8 @@ function createMarkdownStyler(): Styler {
     arg: (text) => `\`${text}\``,
     type: (text) => `\`${text}\``,
     description: (text) => text,
-    label: (text) => `### ${text}`,
+    label: (text) => `**${text}**`,
+    section: (text) => `### ${text}`,
     meta: (text) => `*${text}*`,
     example: (text) => `**${text}**`,
     exampleValue: (text) => `\`${text}\``,
@@ -233,7 +239,8 @@ function createHtmlStyler(): Styler {
     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>`,
+    label: (text) => `<strong>${escapeHtml(text)}</strong>`,
+    section: (text) => `<h3>${escapeHtml(text)}</h3>`,
     meta: (text) => `<span style="color: #999;">${escapeHtml(text)}</span>`,
     example: (text) => `<strong style="text-decoration: underline;">${escapeHtml(text)}</strong>`,
     exampleValue: (text) => `<em>${escapeHtml(text)}</em>`,
@@ -250,7 +257,6 @@ function createTextLayout(): LayoutConfig {
     newline: '\n',
     indent: (level) => '  '.repeat(level),
     join: (parts) => parts.filter(Boolean).join(' '),
-    usageLabel: 'Usage:',
   };
 }
 
@@ -263,7 +269,6 @@ function createMarkdownLayout(): LayoutConfig {
       return '    ';
     },
     join: (parts) => parts.filter(Boolean).join(' '),
-    usageLabel: 'Usage:',
   };
 }
 
@@ -273,7 +278,6 @@ function createHtmlLayout(): LayoutConfig {
     indent: (level) => '&nbsp;&nbsp;'.repeat(level),
     join: (parts) => parts.filter(Boolean).join(' '),
     wrapDocument: (content) => `<div style="font-family: monospace; line-height: 1.6;">${content}</div>`,
-    usageLabel: '<strong>Usage:</strong>',
   };
 }
 
@@ -284,8 +288,8 @@ function createHtmlLayout(): LayoutConfig {
 /**
  * Creates a formatter that uses the given styler and layout configuration.
  */
-function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter {
-  const { newline, indent, join, wrapDocument, usageLabel } = layout;
+function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBuiltins?: boolean, terminalWidth?: number): Formatter {
+  const { newline, indent, join, wrapDocument } = layout;
 
   function formatUsageSection(info: HelpInfo): string[] {
     const usageParts: string[] = [styler.command(info.usage.command), info.usage.hasSubcommands ? styler.meta('[command]') : ''];
@@ -297,15 +301,13 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
       }
     }
     if (info.usage.hasArguments) usageParts.push(styler.meta('[options]'));
-    return [`${usageLabel} ${join(usageParts)}`];
+    return [`${styler.label('Usage:')} ${join(usageParts)}`];
   }
 
   function formatSubcommandsSection(info: HelpInfo): string[] {
     const lines: string[] = [];
     const subcommands = info.subcommands!;
 
-    lines.push(styler.label('Commands:'));
-
     const subcommandSuffix = (c: HelpSubcommandInfo) => (c.hasSubcommands ? ' <subcommand>' : '');
     const formatAliasParts = (c: HelpSubcommandInfo) => {
       if (!c.aliases?.length) return { plain: '', styled: '' };
@@ -323,40 +325,55 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
       }
       return { plain: parts.length ? ` ${parts.join(' ')}` : '', styled: styledParts.length ? ` ${styledParts.join(' ')}` : '' };
     };
+    // Column width is computed across all subcommands for consistent alignment
     const maxNameLength = Math.max(
       ...subcommands.map((c) => {
         return (c.name + subcommandSuffix(c) + formatAliasParts(c).plain).length;
       }),
     );
-    for (const subCmd of subcommands) {
-      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 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
-      const displayText = subCmd.title ?? subCmd.description;
-      if (displayText) {
-        lineParts.push(isDeprecated ? styler.deprecated(displayText) : styler.description(displayText));
-      }
-      if (isDeprecated) {
-        const deprecatedMeta =
-          typeof subCmd.deprecated === 'string' ? styler.meta(` (deprecated: ${subCmd.deprecated})`) : styler.meta(' (deprecated)');
-        lineParts.push(deprecatedMeta);
+
+    const grouped = Object.groupBy(subcommands, (c) => c.group ?? '');
+
+    const renderSubcommands = (cmds: HelpSubcommandInfo[]) => {
+      for (const subCmd of cmds) {
+        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 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
+        const displayText = subCmd.title ?? subCmd.description;
+        if (displayText) {
+          lineParts.push(isDeprecated ? styler.deprecated(displayText) : styler.description(displayText));
+        }
+        if (isDeprecated) {
+          const deprecatedMeta =
+            typeof subCmd.deprecated === 'string' ? styler.meta(` (deprecated: ${subCmd.deprecated})`) : styler.meta(' (deprecated)');
+          lineParts.push(deprecatedMeta);
+        }
+        lines.push(indent(1) + lineParts.join(''));
       }
-      lines.push(indent(1) + lineParts.join(''));
+    };
+
+    for (const [key, items] of Object.entries(grouped)) {
+      if (lines.length > 0) lines.push('');
+      lines.push(styler.section(key ? `${key}:` : 'Commands:'));
+      renderSubcommands(items!);
     }
 
-    lines.push('');
-    lines.push(styler.meta(`Run "${info.name} [command] --help" for more information on a command.`));
+    // Skip hint when builtins are present — the builtins section shows a combined hint
+    if (!info.builtins?.length) {
+      lines.push('');
+      lines.push(styler.meta(`Run "${info.name} [command] --help" for more information on a command.`));
+    }
 
     return lines;
   }
@@ -365,18 +382,56 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
     const lines: string[] = [];
     const args = info.positionals!;
 
-    lines.push(styler.label('Arguments:'));
+    lines.push(styler.section('Arguments:'));
 
     const maxNameLength = Math.min(32, Math.max(...args.map((a) => a.name.length)));
+    const descCol = 2 + maxNameLength + 2;
+    const posAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;
+    const descColPad = ' '.repeat(descCol);
 
     for (const arg of args) {
       const padding = ' '.repeat(Math.max(2, maxNameLength - arg.name.length + 2));
-      const descParts: string[] = [];
-      if (arg.description) descParts.push(styler.description(arg.description));
-      if (info.usage.stdinField === arg.name) descParts.push(styler.meta('(stdin)'));
-      if (arg.enum) descParts.push(styler.meta(`(choices: ${arg.enum.join(', ')})`));
-      if (arg.default !== undefined) descParts.push(styler.meta(`(default: ${String(arg.default)})`));
-      lines.push(indent(1) + styler.arg(arg.name) + padding + join(descParts));
+      const prefix = indent(1) + styler.arg(arg.name) + padding;
+
+      const descPlain = arg.description ?? '';
+      const styledDesc = descPlain ? styler.description(descPlain) : '';
+
+      const metaParts: string[] = [];
+      const styledMetaParts: string[] = [];
+      if (info.usage.stdinField === arg.name) {
+        metaParts.push('(stdin)');
+        styledMetaParts.push(styler.meta('(stdin)'));
+      }
+      if (arg.enum) {
+        const text = `(choices: ${arg.enum.join(', ')})`;
+        metaParts.push(text);
+        styledMetaParts.push(styler.meta(text));
+      }
+      if (arg.default !== undefined) {
+        const text = `(default: ${String(arg.default)})`;
+        metaParts.push(text);
+        styledMetaParts.push(styler.meta(text));
+      }
+
+      const metaStyled = join(styledMetaParts);
+
+      if (posAvailWidth && posAvailWidth > 0) {
+        const metaPlain = metaParts.join(' ');
+        const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');
+        if (fullPlain.length <= posAvailWidth) {
+          lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));
+        } else if (!descPlain || descPlain.length <= posAvailWidth) {
+          lines.push(prefix + styledDesc);
+          if (metaStyled) lines.push(descColPad + metaStyled);
+        } else {
+          const wrapped = wrapText(descPlain, posAvailWidth);
+          lines.push(prefix + styler.description(wrapped[0]!));
+          for (const wline of wrapped.slice(1)) lines.push(descColPad + styler.description(wline));
+          if (metaStyled) lines.push(descColPad + metaStyled);
+        }
+      } else {
+        lines.push(prefix + join([styledDesc, metaStyled]));
+      }
     }
 
     return lines;
@@ -386,8 +441,6 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
     const lines: string[] = [];
     const argList = info.arguments || [];
 
-    lines.push(styler.label('Options:'));
-
     // Helper to check if a default value is meaningful (not empty string/array)
     const hasDefault = (value: unknown): boolean => {
       if (value === undefined) return false;
@@ -396,70 +449,134 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
       return true;
     };
 
-    // Build left column (signature) for each arg to compute alignment
-    const argColumns: { plain: string; styled: string; arg: HelpArgumentInfo }[] = argList.map((arg) => {
+    // Build columns: flags | names | type | description
+    const argColumns = argList.map((arg) => {
       // Promote kebab-case alias to primary display name if it exists
       const kebab = camelToKebab(arg.name);
       const primaryName = kebab && arg.aliases?.includes(kebab) ? kebab : arg.name;
       const remainingAliases = arg.aliases?.filter((a) => a !== primaryName);
-      const argName = `--${primaryName}`;
-      const flagNames = arg.flags?.length ? arg.flags.map((f) => `-${f}`).join(', ') : '';
-      const aliasNames = remainingAliases?.length ? remainingAliases.map((a) => `--${a}`).join(', ') : '';
-      const shortNames = [flagNames, aliasNames].filter(Boolean).join(', ');
-      const fullArgName = shortNames ? `${argName}, ${shortNames}` : argName;
-      const isDeprecated = !!arg.deprecated;
-      const formattedArgName = isDeprecated ? styler.deprecated(fullArgName) : styler.arg(fullArgName);
 
-      const plainParts: string[] = [fullArgName];
-      const styledParts: string[] = [formattedArgName];
+      const flagsPlain = arg.flags?.length ? arg.flags.map((f) => `-${f}`).join(', ') : '';
+      const namesPlain = [`--${primaryName}`, ...(remainingAliases?.map((a) => `--${a}`) || [])].join(', ');
+      const typePlain = arg.type && arg.type !== 'boolean' ? (arg.optional ? `[${arg.type}]` : `<${arg.type}>`) : '';
 
-      if (arg.type && arg.type !== 'boolean') {
-        const typePart = arg.optional ? `[${arg.type}]` : `<${arg.type}>`;
-        plainParts.push(typePart);
-        styledParts.push(styler.type(typePart));
-      }
-      if (isDeprecated) {
-        const deprecatedPart = typeof arg.deprecated === 'string' ? `(deprecated: ${arg.deprecated})` : '(deprecated)';
-        plainParts.push(deprecatedPart);
-        styledParts.push(styler.meta(deprecatedPart));
-      }
+      const isDeprecated = !!arg.deprecated;
 
-      return { plain: plainParts.join(' '), styled: join(styledParts), arg };
+      return { flagsPlain, namesPlain, typePlain, isDeprecated, arg };
     });
 
-    const maxColumnWidth = Math.min(32, Math.max(...argColumns.map((c) => c.plain.length)));
+    // Column widths are computed across all args (regardless of group) for consistent alignment
+    const maxFlagsWidth = Math.min(12, Math.max(0, ...argColumns.map((c) => c.flagsPlain.length)));
+    const maxNamesWidth = Math.min(32, Math.max(0, ...argColumns.map((c) => c.namesPlain.length)));
+    const maxTypeWidth = Math.min(16, Math.max(0, ...argColumns.map((c) => c.typePlain.length)));
+    const hasAnyFlags = maxFlagsWidth > 0;
+    const descCol = 2 + (hasAnyFlags ? maxFlagsWidth + 2 : 0) + maxNamesWidth + 2 + (maxTypeWidth > 0 ? maxTypeWidth + 2 : 0);
+    const argAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;
+    const descColPad = ' '.repeat(descCol);
+
+    // Split into ordered groups: ungrouped first as "Options:", then each group in first-seen order
+    const grouped = Object.groupBy(argColumns, (c) => c.arg.group ?? '');
+
+    const renderArgColumns = (columns: typeof argColumns) => {
+      for (const { flagsPlain, namesPlain, typePlain, isDeprecated, arg } of columns) {
+        const parts: string[] = [];
+
+        // Flags column
+        if (hasAnyFlags) {
+          const styledFlags = isDeprecated ? (flagsPlain ? styler.deprecated(flagsPlain) : '') : flagsPlain ? styler.arg(flagsPlain) : '';
+          const flagsPadding = ' '.repeat(Math.max(0, maxFlagsWidth - flagsPlain.length));
+          const separator = flagsPlain ? ', ' : '  ';
+          parts.push(styledFlags + flagsPadding + separator);
+        }
 
-    for (const { plain, styled, arg } of argColumns) {
-      const padding = ' '.repeat(Math.max(2, maxColumnWidth - plain.length + 2));
+        // Names column
+        const styledNames = isDeprecated ? styler.deprecated(namesPlain) : styler.arg(namesPlain);
+        const namesPadding = ' '.repeat(Math.max(2, maxNamesWidth - namesPlain.length + 2));
+        parts.push(styledNames + namesPadding);
 
-      // Description followed by metadata (choices, default)
-      const descParts: string[] = [];
-      if (arg.description) descParts.push(styler.description(arg.description));
-      if (info.usage.stdinField === arg.name) descParts.push(styler.meta('(stdin)'));
-      if (arg.enum) descParts.push(styler.meta(`(choices: ${arg.enum.join(', ')})`));
-      if (hasDefault(arg.default)) descParts.push(styler.meta(`(default: ${String(arg.default)})`));
+        // Type column
+        if (maxTypeWidth > 0) {
+          const styledType = typePlain ? styler.type(typePlain) : '';
+          const typePadding = ' '.repeat(Math.max(2, maxTypeWidth - typePlain.length + 2));
+          parts.push(styledType + typePadding);
+        }
 
-      lines.push(indent(1) + styled + padding + join(descParts));
+        const prefix = indent(1) + parts.join('');
+        const contPad = argAvailWidth ? descColPad : indent(3);
 
-      // Environment variable line
-      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));
-      }
+        // Build inline meta (deprecated no-reason, default, choices)
+        const inlineMeta: string[] = [];
+        const styledInlineMeta: string[] = [];
+        if (isDeprecated && typeof arg.deprecated !== 'string') {
+          inlineMeta.push('(deprecated)');
+          styledInlineMeta.push(styler.meta('(deprecated)'));
+        }
+        if (hasDefault(arg.default)) {
+          const text = `(default: ${String(arg.default)})`;
+          inlineMeta.push(text);
+          styledInlineMeta.push(styler.meta(text));
+        }
+        if (arg.enum) {
+          const text = `(choices: ${arg.enum.join(', ')})`;
+          inlineMeta.push(text);
+          styledInlineMeta.push(styler.meta(text));
+        }
 
-      // Config key line
-      if (arg.configKey) {
-        const configParts: string[] = [styler.example('Config:'), styler.exampleValue(arg.configKey)];
-        lines.push(indent(3) + join(configParts));
-      }
+        const descPlain = arg.description ?? '';
+        const styledDesc = descPlain ? (isDeprecated ? styler.deprecated(descPlain) : styler.description(descPlain)) : '';
+        const metaStyled = join(styledInlineMeta);
+
+        if (argAvailWidth && argAvailWidth > 0) {
+          // Terminal-width-aware: try to fit description + meta on one line
+          const metaPlain = inlineMeta.join(' ');
+          const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');
+          if (fullPlain.length <= argAvailWidth) {
+            lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));
+          } else if (!descPlain || descPlain.length <= argAvailWidth) {
+            lines.push(prefix + styledDesc);
+            if (metaStyled) lines.push(descColPad + metaStyled);
+          } else {
+            const wrapped = wrapText(descPlain, argAvailWidth);
+            const styleFn = isDeprecated ? styler.deprecated : styler.description;
+            lines.push(prefix + styleFn(wrapped[0]!));
+            for (const wline of wrapped.slice(1)) lines.push(descColPad + styleFn(wline));
+            if (metaStyled) lines.push(descColPad + metaStyled);
+          }
+        } else {
+          // No terminal width (markdown/html): description on line 1, meta on line 2
+          const descParts: string[] = [];
+          if (styledDesc) descParts.push(styledDesc);
+          lines.push(prefix + join(descParts));
+          if (styledInlineMeta.length > 0) lines.push(indent(3) + metaStyled);
+        }
 
-      // Examples line
-      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));
+        // Deprecated (with reason), examples — always on separate line
+        const line3Parts: string[] = [];
+        if (isDeprecated && typeof arg.deprecated === 'string') line3Parts.push(styler.meta(`(deprecated: ${arg.deprecated})`));
+        if (arg.examples && arg.examples.length > 0) {
+          const exampleValues = arg.examples.map((example) => (typeof example === 'string' ? example : JSON.stringify(example))).join(', ');
+          line3Parts.push(styler.example('Example:'), styler.exampleValue(exampleValues));
+        }
+        if (line3Parts.length > 0) lines.push(contPad + join(line3Parts));
+
+        // stdin, env, config — always on separate line
+        const line4Parts: string[] = [];
+        if (info.usage.stdinField === arg.name) line4Parts.push(styler.meta('(stdin)'));
+        if (arg.env) {
+          const envVars = typeof arg.env === 'string' ? [arg.env] : arg.env;
+          line4Parts.push(styler.example('Env:'), styler.exampleValue(envVars.join(', ')));
+        }
+        if (arg.configKey) {
+          line4Parts.push(styler.example('Config:'), styler.exampleValue(arg.configKey));
+        }
+        if (line4Parts.length > 0) lines.push(contPad + join(line4Parts));
       }
+    };
+
+    for (const [key, items] of Object.entries(grouped)) {
+      if (lines.length > 0) lines.push('');
+      lines.push(styler.section(key ? `${key}:` : 'Options:'));
+      renderArgColumns(items!);
     }
 
     return lines;
@@ -469,7 +586,18 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
     const lines: string[] = [];
     const builtins = info.builtins!;
 
-    lines.push(styler.label('Built-in:'));
+    if (!showAllBuiltins) {
+      // Collapsed summary: show selected builtins on a single line with a combined hint
+      const highlights = ['help [command]', 'version', '[command] --repl'];
+      lines.push(`${styler.label('Global:')} ${styler.meta(highlights.join(', '))}`);
+      const hint = info.usage.hasSubcommands
+        ? `Run "${info.name} [command] --help" for more information. Use "--all" for all global commands.`
+        : `Use "${info.name} help --all" for more information on global commands.`;
+      lines.push(styler.meta(hint));
+      return lines;
+    }
+
+    lines.push(styler.section('Global:'));
 
     // Compute max effective name length for alignment across main and sub entries
     const allLengths: number[] = [];
@@ -537,6 +665,15 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
         lines.push('');
       }
 
+      // Examples section (if present)
+      if (info.examples && info.examples.length > 0) {
+        lines.push(styler.section('Examples:'));
+        for (const ex of info.examples) {
+          lines.push(indent(1) + styler.meta('$ ') + styler.exampleValue(ex));
+        }
+        lines.push('');
+      }
+
       // Subcommands section
       if (info.subcommands && info.subcommands.length > 0) {
         lines.push(...formatSubcommandsSection(info));
@@ -566,7 +703,7 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig): Formatter
 
       // Nested commands section (full detail mode)
       if (info.nestedCommands?.length) {
-        lines.push(styler.label('Subcommand Details:'));
+        lines.push(styler.section('Subcommand Details:'));
         lines.push('');
         for (const nestedCmd of info.nestedCommands) {
           lines.push(styler.meta('─'.repeat(60)));
@@ -596,11 +733,10 @@ function createJsonFormatter(): Formatter {
 // Formatter Factory
 // ============================================================================
 
-function shouldUseAnsi(): boolean {
-  if (typeof process === 'undefined') return false;
-  if (process.env.NO_COLOR) return false;
-  if (process.env.CI) return false;
-  if (process.stdout && typeof process.stdout.isTTY === 'boolean') return process.stdout.isTTY;
+function shouldUseAnsi(env?: Record<string, string | undefined>, isTTY?: boolean): boolean {
+  if (env?.NO_COLOR) return false;
+  if (env?.CI) return false;
+  if (typeof isTTY === 'boolean') return isTTY;
   return false;
 }
 
@@ -628,12 +764,22 @@ function createMinimalFormatter(): Formatter {
   };
 }
 
-export function createFormatter(format: HelpFormat | 'auto', detail: HelpDetail = 'standard'): Formatter {
+export function createFormatter(
+  format: HelpFormat | 'auto',
+  detail: HelpDetail = 'standard',
+  theme?: ColorTheme | ColorConfig,
+  all?: boolean,
+  width?: number,
+  terminal?: { columns?: number; isTTY?: boolean },
+  env?: Record<string, string | undefined>,
+): Formatter {
   if (detail === 'minimal') return createMinimalFormatter();
   if (format === 'json') return createJsonFormatter();
-  if (format === 'ansi' || (format === 'auto' && shouldUseAnsi())) return createGenericFormatter(createAnsiStyler(), createTextLayout());
-  if (format === 'console') return createGenericFormatter(createConsoleStyler(), createTextLayout());
-  if (format === 'markdown') return createGenericFormatter(createMarkdownStyler(), createMarkdownLayout());
-  if (format === 'html') return createGenericFormatter(createHtmlStyler(), createHtmlLayout());
-  return createGenericFormatter(createTextStyler(), createTextLayout());
+  const tw = format === 'markdown' || format === 'html' ? undefined : (width ?? terminal?.columns ?? DEFAULT_TERMINAL_WIDTH);
+  if (format === 'ansi' || (format === 'auto' && shouldUseAnsi(env, terminal?.isTTY)))
+    return createGenericFormatter(createAnsiStyler(theme), createTextLayout(), all, tw);
+  if (format === 'console') return createGenericFormatter(createConsoleStyler(theme), createTextLayout(), all, tw);
+  if (format === 'markdown') return createGenericFormatter(createMarkdownStyler(), createMarkdownLayout(), all);
+  if (format === 'html') return createGenericFormatter(createHtmlStyler(), createHtmlLayout(), all);
+  return createGenericFormatter(createTextStyler(), createTextLayout(), all, tw);
 }