padrone 1.4.0 → 1.5.0

package/src/formatter.ts

@@ -1,5 +1,5 @@
 import { camelToKebab } from './args.ts';
-import { createColorizer } from './colorizer.ts';
+import { type ColorConfig, type ColorTheme, createColorizer } from './colorizer.ts';
 
 export type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';
 export type HelpDetail = 'minimal' | 'standard' | 'full';
@@ -45,6 +45,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 +60,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 +107,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 +139,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 +154,6 @@ type LayoutConfig = {
   indent: (level: number) => string;
   join: (parts: string[]) => string;
   wrapDocument?: (content: string) => string;
-  usageLabel: string;
 };
 
 // ============================================================================
@@ -161,6 +167,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 +175,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 +191,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 +201,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 +220,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 +238,6 @@ function createTextLayout(): LayoutConfig {
     newline: '\n',
     indent: (level) => '  '.repeat(level),
     join: (parts) => parts.filter(Boolean).join(' '),
-    usageLabel: 'Usage:',
   };
 }
 
@@ -263,7 +250,6 @@ function createMarkdownLayout(): LayoutConfig {
       return '    ';
     },
     join: (parts) => parts.filter(Boolean).join(' '),
-    usageLabel: 'Usage:',
   };
 }
 
@@ -273,7 +259,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 +269,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): 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 +282,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 +306,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,7 +363,7 @@ 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)));
 
@@ -386,8 +384,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 +392,94 @@ 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)));
-
-    for (const { plain, styled, arg } of argColumns) {
-      const padding = ' '.repeat(Math.max(2, maxColumnWidth - plain.length + 2));
-
-      // 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)})`));
+    // 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;
+
+    // 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);
+        }
 
-      lines.push(indent(1) + styled + padding + join(descParts));
+        // 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);
 
-      // 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));
-      }
+        // 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);
+        }
 
-      // Config key line
-      if (arg.configKey) {
-        const configParts: string[] = [styler.example('Config:'), styler.exampleValue(arg.configKey)];
-        lines.push(indent(3) + join(configParts));
+        // Line 1: description
+        const descParts: string[] = [];
+        if (arg.description) descParts.push(isDeprecated ? styler.deprecated(arg.description) : styler.description(arg.description));
+        lines.push(indent(1) + parts.join('') + join(descParts));
+
+        // Line 2: deprecated (no reason), default, choices
+        const line2Parts: string[] = [];
+        if (isDeprecated && typeof arg.deprecated !== 'string') line2Parts.push(styler.meta('(deprecated)'));
+        if (hasDefault(arg.default)) line2Parts.push(styler.meta(`(default: ${String(arg.default)})`));
+        if (arg.enum) line2Parts.push(styler.meta(`(choices: ${arg.enum.join(', ')})`));
+        if (line2Parts.length > 0) lines.push(indent(3) + join(line2Parts));
+
+        // Line 3: deprecated (with reason), examples
+        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(indent(3) + join(line3Parts));
+
+        // Line 4: stdin, env, config
+        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(indent(3) + join(line4Parts));
       }
+    };
 
-      // 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));
-      }
+    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 +489,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 +568,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 +606,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)));
@@ -628,12 +668,18 @@ 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,
+): 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());
+  if (format === 'ansi' || (format === 'auto' && shouldUseAnsi()))
+    return createGenericFormatter(createAnsiStyler(theme), createTextLayout(), all);
+  if (format === 'console') return createGenericFormatter(createConsoleStyler(theme), createTextLayout(), all);
+  if (format === 'markdown') return createGenericFormatter(createMarkdownStyler(), createMarkdownLayout(), all);
+  if (format === 'html') return createGenericFormatter(createHtmlStyler(), createHtmlLayout(), all);
+  return createGenericFormatter(createTextStyler(), createTextLayout(), all);
 }

package/src/help.ts

@@ -1,5 +1,6 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
-import { extractSchemaMetadata, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
+import { extractSchemaMetadata, JSON_SCHEMA_OPTS, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
+import type { ColorConfig, ColorTheme } from './colorizer.ts';
 import { findCommandByName } from './command-utils.ts';
 import {
   createFormatter,
@@ -16,6 +17,9 @@ import { getRootCommand } from './utils.ts';
 export type HelpPreferences = {
   format?: HelpFormat | 'auto';
   detail?: HelpDetail;
+  theme?: ColorTheme | ColorConfig;
+  /** Show all global commands and flags in full detail */
+  all?: boolean;
 };
 
 /**
@@ -35,7 +39,7 @@ function extractPositionalArgsInfo(
   const positionalConfig = parsePositionalConfig(meta.positional);
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = schema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
 
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
       const properties = jsonSchema.properties as Record<string, any>;
@@ -75,7 +79,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
   const argsMeta = meta?.fields;
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = schema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
 
     // Handle object: z.object({ key: z.string(), ... })
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
@@ -134,6 +138,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
           examples: optMeta?.examples ?? prop?.examples,
           variadic: propType === 'array',
           negatable: isNegatable,
+          group: optMeta?.group,
         });
       }
     }
@@ -154,7 +159,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
  * @param cmd - The command to build help info for
  * @param detail - The level of detail ('minimal', 'standard', or 'full')
  */
-export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard'): HelpInfo {
+export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard', all?: boolean): HelpInfo {
   const rootCmd = getRootCommand(cmd);
   // A command is a "default" command if its name is '' or it has '' as an alias
   const isDefaultCommand = cmd.parent && (!cmd.name || cmd.aliases?.includes(''));
@@ -176,6 +181,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
     name: commandName,
     title: cmd.title,
     description: cmd.description,
+    examples: cmd.examples,
     aliases: displayAliases,
     deprecated: cmd.deprecated,
     hidden: cmd.hidden,
@@ -184,7 +190,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
       hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),
       hasPositionals,
       hasArguments: false, // updated below after extracting arguments
-      stdinField: cmd.meta?.stdin ? parseStdinConfig(cmd.meta.stdin).field : undefined,
+      stdinField: cmd.meta?.stdin ? parseStdinConfig(cmd.meta.stdin) : undefined,
     },
   };
 
@@ -222,6 +228,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
               aliases: displayAliases?.length ? displayAliases : undefined,
               deprecated: c.deprecated,
               hidden: c.hidden,
+              group: c.group,
             },
             {
               name: displayName,
@@ -230,6 +237,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
               deprecated: c.deprecated,
               hidden: c.hidden,
               hasSubcommands: true,
+              group: c.group,
             },
           ];
         }
@@ -243,6 +251,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
             deprecated: c.deprecated,
             hidden: c.hidden,
             hasSubcommands,
+            group: c.group,
           },
         ];
       }),
@@ -285,40 +294,64 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
     }
   }
 
-  // Add built-in commands/flags for root command only
-  if (!cmd.parent) {
+  // Add global commands/flags (root command by default, all commands when --all is passed)
+  if (!cmd.parent || all) {
     const builtins: HelpInfo['builtins'] = [];
 
-    if (!findCommandByName('help', cmd.commands)) {
+    if (!findCommandByName('help', rootCmd.commands)) {
       builtins.push({
         name: 'help [command], -h, --help',
         description: 'Show help for a command',
         sub: [
+          { name: '--all', description: 'Show all global commands and flags' },
           { name: '--detail <level>', description: 'Detail level (minimal, standard, full)' },
           { name: '--format <format>', description: 'Output format (text, ansi, json, markdown, html)' },
         ],
       });
     }
 
-    if (!findCommandByName('version', cmd.commands)) {
+    if (!findCommandByName('version', rootCmd.commands)) {
       builtins.push({
         name: 'version, -v, --version',
         description: 'Show version information',
       });
     }
 
-    if (!findCommandByName('completion', cmd.commands)) {
+    if (!findCommandByName('completion', rootCmd.commands)) {
       builtins.push({
         name: 'completion [shell]',
         description: 'Generate shell completions (bash, zsh, fish, powershell)',
       });
     }
 
+    if (!findCommandByName('man', rootCmd.commands)) {
+      builtins.push({
+        name: 'man',
+        description: 'Show or install man pages (--setup to install, --remove to uninstall) (experimental)',
+      });
+    }
+
     builtins.push({
       name: '[command] --repl',
       description: 'Start interactive REPL scoped to a command',
     });
 
+    if (!findCommandByName('mcp', rootCmd.commands)) {
+      builtins.push({
+        name: 'mcp [http|stdio]',
+        description: 'Start a Model Context Protocol server to expose commands as AI tools (experimental)',
+        sub: [
+          { name: '--port <port>', description: 'HTTP port (default: 3000)' },
+          { name: '--host <host>', description: 'HTTP host (default: 127.0.0.1)' },
+        ],
+      });
+    }
+
+    builtins.push({
+      name: '--color [theme], --no-color',
+      description: 'Set color theme (default, ocean, warm, monochrome) or disable colors',
+    });
+
     if (builtins.length > 0) {
       helpInfo.builtins = builtins;
     }
@@ -332,7 +365,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
 // ============================================================================
 
 export function generateHelp(rootCommand: AnyPadroneCommand, commandObj: AnyPadroneCommand = rootCommand, prefs?: HelpPreferences): string {
-  const helpInfo = getHelpInfo(commandObj, prefs?.detail);
-  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail);
+  const helpInfo = getHelpInfo(commandObj, prefs?.detail, prefs?.all);
+  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail, prefs?.theme, prefs?.all);
   return formatter.format(helpInfo);
 }