padrone 1.9.0 → 2.0.0

package/dist/output/formatter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.mjs","names":[],"sources":["../../src/output/formatter.ts"],"sourcesContent":["import { camelToKebab } from '../util/shell-utils.ts';\nimport type { ColorConfig, ColorTheme } from './colorizer.ts';\nimport {\n  createAnsiStyler,\n  createConsoleStyler,\n  createHtmlLayout,\n  createHtmlStyler,\n  createMarkdownLayout,\n  createMarkdownStyler,\n  createTextLayout,\n  createTextStyler,\n  DEFAULT_TERMINAL_WIDTH,\n  type LayoutConfig,\n  type Styler,\n  shouldUseAnsi,\n  wrapText,\n} from './styling.ts';\n\nexport type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';\nexport type HelpDetail = 'minimal' | 'standard' | 'full';\n\n// ============================================================================\n// Help Info Types (shared with help.ts)\n// ============================================================================\n\n/**\n * Information about a single positional argument.\n */\nexport type HelpPositionalInfo = {\n  name: string;\n  description?: string;\n  optional: boolean;\n  default?: unknown;\n  type?: string;\n  enum?: string[];\n};\n\n/**\n * Information about a single argument/flag.\n */\nexport type HelpArgumentInfo = {\n  name: string;\n  description?: string;\n  optional: boolean;\n  default?: unknown;\n  type?: string;\n  enum?: string[];\n  /** Single-character short flags (shown as `-v`) */\n  flags?: string[];\n  /** Multi-character alternative long names (shown as `--dry-run`) */\n  aliases?: string[];\n  deprecated?: boolean | string;\n  hidden?: boolean;\n  examples?: unknown[];\n  /** Environment variable(s) this arg can be set from */\n  env?: string | string[];\n  /** Whether this arg is an array type (shown as <type...>) */\n  variadic?: boolean;\n  /** Whether this arg is a boolean (shown as --[no-]arg) */\n  negatable?: boolean;\n  /** Custom negative keyword(s) that set this arg to false (e.g. `['remote']` for `--remote`) */\n  negative?: string[];\n  /** Config file key that maps to this arg */\n  configKey?: string;\n  /** Group name for organizing this option under a labeled section in help output */\n  group?: string;\n};\n\n/**\n * Information about a subcommand (minimal info for listing).\n */\nexport type HelpSubcommandInfo = {\n  name: string;\n  title?: string;\n  description?: string;\n  aliases?: string[];\n  deprecated?: boolean | string;\n  hidden?: boolean;\n  hasSubcommands?: boolean;\n  /** Group name for organizing this command under a labeled section in help output */\n  group?: string;\n};\n\n/**\n * Information about a built-in command/flag entry.\n */\nexport type HelpBuiltinInfo = {\n  name: string;\n  description?: string;\n  sub?: { name: string; description?: string }[];\n};\n\n/**\n * Comprehensive JSON structure for help information.\n * This is the single source of truth that all formatters use.\n */\nexport type HelpInfo = {\n  /** The full command name (e.g., \"cli serve\" or \"<root>\") */\n  name: string;\n  /** Short title for the command */\n  title?: string;\n  /** Command description */\n  description?: string;\n  /** Alternative names/aliases for this command */\n  aliases?: string[];\n  /** Whether the command is deprecated */\n  deprecated?: boolean | string;\n  /** Whether the command is hidden */\n  hidden?: boolean;\n  /** Usage string parts for flexible formatting */\n  usage: {\n    command: string;\n    hasSubcommands: boolean;\n    hasPositionals: boolean;\n    hasArguments: boolean;\n    /** The name of the field that reads from stdin, if any. Shown as `[stdin > field]` in usage. */\n    stdinField?: string;\n  };\n  /** List of subcommands */\n  subcommands?: HelpSubcommandInfo[];\n  /** Positional arguments */\n  positionals?: HelpPositionalInfo[];\n  /** Arguments/flags (only visible ones, hidden filtered out) */\n  arguments?: HelpArgumentInfo[];\n  /** Built-in commands and flags (shown only for root command) */\n  builtins?: HelpBuiltinInfo[];\n  /** Command-level usage examples (shown in help output) */\n  examples?: string[];\n  /** Full help info for nested commands (used in 'full' detail mode) */\n  nestedCommands?: HelpInfo[];\n};\n\n// ============================================================================\n// Formatter Interface\n// ============================================================================\n\n/**\n * A formatter that takes the entire HelpInfo structure and produces formatted output.\n */\nexport type Formatter = {\n  /** Format the entire help info structure into a string */\n  format: (info: HelpInfo) => string;\n};\n\n// ============================================================================\n// Generic Formatter Implementation\n// ============================================================================\n\n/**\n * Creates a formatter that uses the given styler and layout configuration.\n */\nfunction createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBuiltins?: boolean, terminalWidth?: number): Formatter {\n  const { newline, indent, join, wrapDocument } = layout;\n\n  function formatUsageSection(info: HelpInfo): string[] {\n    const usageParts: string[] = [styler.command(info.usage.command), info.usage.hasSubcommands ? styler.meta('[command]') : ''];\n    // Show actual positional argument names in usage line\n    if (info.positionals && info.positionals.length > 0) {\n      for (const arg of info.positionals) {\n        const name = arg.name.startsWith('...') ? `${arg.name}` : arg.name;\n        usageParts.push(styler.meta(arg.optional ? `[${name}]` : `<${name}>`));\n      }\n    }\n    if (info.usage.hasArguments) usageParts.push(styler.meta('[options]'));\n    return [`${styler.label('Usage:')} ${join(usageParts)}`];\n  }\n\n  function formatSubcommandsSection(info: HelpInfo): string[] {\n    const lines: string[] = [];\n    const subcommands = info.subcommands!;\n\n    const subcommandSuffix = (c: HelpSubcommandInfo) => (c.hasSubcommands ? ' <subcommand>' : '');\n    const formatAliasParts = (c: HelpSubcommandInfo) => {\n      if (!c.aliases?.length) return { plain: '', styled: '' };\n      const realAliases = c.aliases.filter((a) => a !== '[default]');\n      const hasDefault = c.aliases.some((a) => a === '[default]');\n      const parts: string[] = [];\n      const styledParts: string[] = [];\n      if (realAliases.length) {\n        parts.push(`(${realAliases.join(', ')})`);\n        styledParts.push(`(${realAliases.join(', ')})`);\n      }\n      if (hasDefault) {\n        parts.push('[default]');\n        styledParts.push(styler.meta('[default]'));\n      }\n      return { plain: parts.length ? ` ${parts.join(' ')}` : '', styled: styledParts.length ? ` ${styledParts.join(' ')}` : '' };\n    };\n    // Column width is computed across all subcommands for consistent alignment\n    const maxNameLength = Math.max(\n      ...subcommands.map((c) => {\n        return (c.name + subcommandSuffix(c) + formatAliasParts(c).plain).length;\n      }),\n    );\n\n    const grouped = Object.groupBy(subcommands, (c) => c.group ?? '');\n\n    const renderSubcommands = (cmds: HelpSubcommandInfo[]) => {\n      for (const subCmd of cmds) {\n        const aliasParts = formatAliasParts(subCmd);\n        const suffix = subcommandSuffix(subCmd);\n        const commandDisplay = subCmd.name + suffix + aliasParts.plain;\n        const padding = ' '.repeat(Math.max(0, maxNameLength - commandDisplay.length + 2));\n        const isDeprecated = !!subCmd.deprecated;\n        const isDefaultEntry = subCmd.name === '[default]';\n        const commandName = isDeprecated\n          ? styler.deprecated(commandDisplay)\n          : (isDefaultEntry ? styler.meta(subCmd.name) : styler.command(subCmd.name)) +\n            (suffix ? styler.meta(suffix) : '') +\n            aliasParts.styled;\n        const lineParts: string[] = [commandName, padding];\n\n        // Use title if available, otherwise use description\n        const displayText = subCmd.title ?? subCmd.description;\n        if (displayText) {\n          lineParts.push(isDeprecated ? styler.deprecated(displayText) : styler.description(displayText));\n        }\n        if (isDeprecated) {\n          const deprecatedMeta =\n            typeof subCmd.deprecated === 'string' ? styler.meta(` (deprecated: ${subCmd.deprecated})`) : styler.meta(' (deprecated)');\n          lineParts.push(deprecatedMeta);\n        }\n        lines.push(indent(1) + lineParts.join(''));\n      }\n    };\n\n    for (const [key, items] of Object.entries(grouped)) {\n      if (lines.length > 0) lines.push('');\n      lines.push(styler.section(key ? `${key}:` : 'Commands:'));\n      renderSubcommands(items!);\n    }\n\n    // Skip hint when builtins are present — the builtins section shows a combined hint\n    if (!info.builtins?.length) {\n      lines.push('');\n      lines.push(styler.meta(`Run \"${info.name} [command] --help\" for more information on a command.`));\n    }\n\n    return lines;\n  }\n\n  function formatPositionalsSection(info: HelpInfo): string[] {\n    const lines: string[] = [];\n    const args = info.positionals!;\n\n    lines.push(styler.section('Arguments:'));\n\n    const maxNameLength = Math.min(32, Math.max(...args.map((a) => a.name.length)));\n    const descCol = 2 + maxNameLength + 2;\n    const posAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;\n    const descColPad = ' '.repeat(descCol);\n\n    for (const arg of args) {\n      const padding = ' '.repeat(Math.max(2, maxNameLength - arg.name.length + 2));\n      const prefix = indent(1) + styler.arg(arg.name) + padding;\n\n      const descPlain = arg.description ?? '';\n      const styledDesc = descPlain ? styler.description(descPlain) : '';\n\n      const metaParts: string[] = [];\n      const styledMetaParts: string[] = [];\n      if (info.usage.stdinField === arg.name) {\n        metaParts.push('(stdin)');\n        styledMetaParts.push(styler.meta('(stdin)'));\n      }\n      if (arg.enum) {\n        const text = `(choices: ${arg.enum.join(', ')})`;\n        metaParts.push(text);\n        styledMetaParts.push(styler.meta(text));\n      }\n      if (arg.default !== undefined) {\n        const text = `(default: ${String(arg.default)})`;\n        metaParts.push(text);\n        styledMetaParts.push(styler.meta(text));\n      }\n\n      const metaStyled = join(styledMetaParts);\n\n      if (posAvailWidth && posAvailWidth > 0) {\n        const metaPlain = metaParts.join(' ');\n        const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');\n        if (fullPlain.length <= posAvailWidth) {\n          lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));\n        } else if (!descPlain || descPlain.length <= posAvailWidth) {\n          lines.push(prefix + styledDesc);\n          if (metaStyled) lines.push(descColPad + metaStyled);\n        } else {\n          const wrapped = wrapText(descPlain, posAvailWidth);\n          lines.push(prefix + styler.description(wrapped[0]!));\n          for (const wline of wrapped.slice(1)) lines.push(descColPad + styler.description(wline));\n          if (metaStyled) lines.push(descColPad + metaStyled);\n        }\n      } else {\n        lines.push(prefix + join([styledDesc, metaStyled]));\n      }\n    }\n\n    return lines;\n  }\n\n  function formatArgumentsSection(info: HelpInfo): string[] {\n    const lines: string[] = [];\n    const argList = info.arguments || [];\n\n    // Helper to check if a default value is meaningful (not empty string/array)\n    const hasDefault = (value: unknown): boolean => {\n      if (value === undefined) return false;\n      if (value === '') return false;\n      if (Array.isArray(value) && value.length === 0) return false;\n      return true;\n    };\n\n    // Build columns: flags | names | type | description\n    const argColumns = argList.map((arg) => {\n      // Promote kebab-case alias to primary display name if it exists\n      const kebab = camelToKebab(arg.name);\n      const primaryName = kebab && arg.aliases?.includes(kebab) ? kebab : arg.name;\n      const remainingAliases = arg.aliases?.filter((a) => a !== primaryName);\n\n      const flagsPlain = arg.flags?.length ? arg.flags.map((f) => `-${f}`).join(', ') : '';\n      const negPlain = arg.negative?.length ? arg.negative.map((n) => `--${n}`).join(', ') : '';\n      const namesPlain = [`--${primaryName}`, ...(remainingAliases?.map((a) => `--${a}`) || []), ...(negPlain ? [negPlain] : [])].join(\n        ', ',\n      );\n      const typePlain = arg.type && arg.type !== 'boolean' ? (arg.optional ? `[${arg.type}]` : `<${arg.type}>`) : '';\n\n      const isDeprecated = !!arg.deprecated;\n\n      return { flagsPlain, namesPlain, typePlain, isDeprecated, arg };\n    });\n\n    // Column widths are computed across all args (regardless of group) for consistent alignment\n    const maxFlagsWidth = Math.min(12, Math.max(0, ...argColumns.map((c) => c.flagsPlain.length)));\n    const maxNamesWidth = Math.min(32, Math.max(0, ...argColumns.map((c) => c.namesPlain.length)));\n    const maxTypeWidth = Math.min(16, Math.max(0, ...argColumns.map((c) => c.typePlain.length)));\n    const hasAnyFlags = maxFlagsWidth > 0;\n    const descCol = 2 + (hasAnyFlags ? maxFlagsWidth + 2 : 0) + maxNamesWidth + 2 + (maxTypeWidth > 0 ? maxTypeWidth + 2 : 0);\n    const argAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;\n    const descColPad = ' '.repeat(descCol);\n\n    // Split into ordered groups: ungrouped first as \"Options:\", then each group in first-seen order\n    const grouped = Object.groupBy(argColumns, (c) => c.arg.group ?? '');\n\n    const renderArgColumns = (columns: typeof argColumns) => {\n      for (const { flagsPlain, namesPlain, typePlain, isDeprecated, arg } of columns) {\n        const parts: string[] = [];\n\n        // Flags column\n        if (hasAnyFlags) {\n          const styledFlags = isDeprecated ? (flagsPlain ? styler.deprecated(flagsPlain) : '') : flagsPlain ? styler.arg(flagsPlain) : '';\n          const flagsPadding = ' '.repeat(Math.max(0, maxFlagsWidth - flagsPlain.length));\n          const separator = flagsPlain ? ', ' : '  ';\n          parts.push(styledFlags + flagsPadding + separator);\n        }\n\n        // Names column\n        const styledNames = isDeprecated ? styler.deprecated(namesPlain) : styler.arg(namesPlain);\n        const namesPadding = ' '.repeat(Math.max(2, maxNamesWidth - namesPlain.length + 2));\n        parts.push(styledNames + namesPadding);\n\n        // Type column\n        if (maxTypeWidth > 0) {\n          const styledType = typePlain ? styler.type(typePlain) : '';\n          const typePadding = ' '.repeat(Math.max(2, maxTypeWidth - typePlain.length + 2));\n          parts.push(styledType + typePadding);\n        }\n\n        const prefix = indent(1) + parts.join('');\n        const contPad = argAvailWidth ? descColPad : indent(3);\n\n        // Build inline meta (deprecated no-reason, default, choices)\n        const inlineMeta: string[] = [];\n        const styledInlineMeta: string[] = [];\n        if (isDeprecated && typeof arg.deprecated !== 'string') {\n          inlineMeta.push('(deprecated)');\n          styledInlineMeta.push(styler.meta('(deprecated)'));\n        }\n        if (hasDefault(arg.default)) {\n          const text = `(default: ${String(arg.default)})`;\n          inlineMeta.push(text);\n          styledInlineMeta.push(styler.meta(text));\n        }\n        if (arg.enum) {\n          const text = `(choices: ${arg.enum.join(', ')})`;\n          inlineMeta.push(text);\n          styledInlineMeta.push(styler.meta(text));\n        }\n\n        const descPlain = arg.description ?? '';\n        const styledDesc = descPlain ? (isDeprecated ? styler.deprecated(descPlain) : styler.description(descPlain)) : '';\n        const metaStyled = join(styledInlineMeta);\n\n        if (argAvailWidth && argAvailWidth > 0) {\n          // Terminal-width-aware: try to fit description + meta on one line\n          const metaPlain = inlineMeta.join(' ');\n          const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');\n          if (fullPlain.length <= argAvailWidth) {\n            lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));\n          } else if (!descPlain || descPlain.length <= argAvailWidth) {\n            lines.push(prefix + styledDesc);\n            if (metaStyled) lines.push(descColPad + metaStyled);\n          } else {\n            const wrapped = wrapText(descPlain, argAvailWidth);\n            const styleFn = isDeprecated ? styler.deprecated : styler.description;\n            lines.push(prefix + styleFn(wrapped[0]!));\n            for (const wline of wrapped.slice(1)) lines.push(descColPad + styleFn(wline));\n            if (metaStyled) lines.push(descColPad + metaStyled);\n          }\n        } else {\n          // No terminal width (markdown/html): description on line 1, meta on line 2\n          const descParts: string[] = [];\n          if (styledDesc) descParts.push(styledDesc);\n          lines.push(prefix + join(descParts));\n          if (styledInlineMeta.length > 0) lines.push(indent(3) + metaStyled);\n        }\n\n        // Deprecated (with reason), examples — always on separate line\n        const line3Parts: string[] = [];\n        if (isDeprecated && typeof arg.deprecated === 'string') line3Parts.push(styler.meta(`(deprecated: ${arg.deprecated})`));\n        if (arg.examples && arg.examples.length > 0) {\n          const exampleValues = arg.examples.map((example) => (typeof example === 'string' ? example : JSON.stringify(example))).join(', ');\n          line3Parts.push(styler.example('Example:'), styler.exampleValue(exampleValues));\n        }\n        if (line3Parts.length > 0) lines.push(contPad + join(line3Parts));\n\n        // stdin, env, config — always on separate line\n        const line4Parts: string[] = [];\n        if (info.usage.stdinField === arg.name) line4Parts.push(styler.meta('(stdin)'));\n        if (arg.env) {\n          const envVars = typeof arg.env === 'string' ? [arg.env] : arg.env;\n          line4Parts.push(styler.example('Env:'), styler.exampleValue(envVars.join(', ')));\n        }\n        if (arg.configKey) {\n          line4Parts.push(styler.example('Config:'), styler.exampleValue(arg.configKey));\n        }\n        if (line4Parts.length > 0) lines.push(contPad + join(line4Parts));\n      }\n    };\n\n    for (const [key, items] of Object.entries(grouped)) {\n      if (lines.length > 0) lines.push('');\n      lines.push(styler.section(key ? `${key}:` : 'Options:'));\n      renderArgColumns(items!);\n    }\n\n    return lines;\n  }\n\n  function formatBuiltinsSection(info: HelpInfo): string[] {\n    const lines: string[] = [];\n    const builtins = info.builtins!;\n\n    if (!showAllBuiltins) {\n      // Collapsed summary: show selected builtins on a single line with a combined hint\n      const highlights = ['help [command]', 'version', '[command] --repl'];\n      lines.push(`${styler.label('Global:')} ${styler.meta(highlights.join(', '))}`);\n      const hint = info.usage.hasSubcommands\n        ? `Run \"${info.name} [command] --help\" for more information. Use \"--all\" for all global commands.`\n        : `Use \"${info.name} help --all\" for more information on global commands.`;\n      lines.push(styler.meta(hint));\n      return lines;\n    }\n\n    lines.push(styler.section('Global:'));\n\n    // Compute max effective name length for alignment across main and sub entries\n    const allLengths: number[] = [];\n    for (const entry of builtins) {\n      allLengths.push(entry.name.length);\n      if (entry.sub) {\n        for (const sub of entry.sub) {\n          // Sub entries get extra indent(2) - indent(1) = 2 chars\n          allLengths.push(sub.name.length + 2);\n        }\n      }\n    }\n    const maxLen = Math.max(...allLengths);\n\n    for (const entry of builtins) {\n      const padding = ' '.repeat(Math.max(2, maxLen - entry.name.length + 2));\n      const parts: string[] = [styler.command(entry.name)];\n      if (entry.description) parts.push(padding + styler.description(entry.description));\n      lines.push(indent(1) + parts.join(''));\n\n      if (entry.sub) {\n        for (const sub of entry.sub) {\n          const subPadding = ' '.repeat(Math.max(2, maxLen - sub.name.length));\n          const subParts: string[] = [styler.arg(sub.name)];\n          if (sub.description) subParts.push(subPadding + styler.description(sub.description));\n          lines.push(indent(2) + subParts.join(''));\n        }\n      }\n    }\n\n    return lines;\n  }\n\n  return {\n    format(info: HelpInfo): string {\n      const lines: string[] = [];\n\n      // Show deprecation warning at the top if command is deprecated\n      if (info.deprecated) {\n        const deprecationMessage =\n          typeof info.deprecated === 'string' ? `⚠️  This command is deprecated: ${info.deprecated}` : '⚠️  This command is deprecated';\n        lines.push(styler.deprecated(deprecationMessage));\n        lines.push('');\n      }\n\n      // Usage section\n      lines.push(...formatUsageSection(info));\n      lines.push('');\n\n      // Title section (if present, shows a short summary line)\n      if (info.title) {\n        lines.push(styler.label(info.title));\n        lines.push('');\n      }\n\n      // Aliases section (if present)\n      if (info.aliases && info.aliases.length > 0) {\n        lines.push(styler.meta(`Aliases: ${info.aliases.join(', ')}`));\n        lines.push('');\n      }\n\n      // Description section (if present)\n      if (info.description) {\n        lines.push(styler.description(info.description));\n        lines.push('');\n      }\n\n      // Examples section (if present)\n      if (info.examples && info.examples.length > 0) {\n        lines.push(styler.section('Examples:'));\n        for (const ex of info.examples) {\n          lines.push(indent(1) + styler.meta('$ ') + styler.exampleValue(ex));\n        }\n        lines.push('');\n      }\n\n      // Subcommands section\n      if (info.subcommands && info.subcommands.length > 0) {\n        lines.push(...formatSubcommandsSection(info));\n        lines.push('');\n      }\n\n      if (info.positionals && info.positionals.length > 0) {\n        lines.push(...formatPositionalsSection(info));\n        lines.push('');\n      }\n\n      if (info.arguments && info.arguments.length > 0) {\n        lines.push(...formatArgumentsSection(info));\n        lines.push('');\n      }\n\n      if (info.builtins && info.builtins.length > 0) {\n        lines.push(...formatBuiltinsSection(info));\n        lines.push('');\n      }\n\n      // Show --no- hint when there are negatable boolean options defaulting to true\n      if (info.arguments?.some((arg) => arg.negatable && arg.default === true)) {\n        lines.push(styler.meta('Boolean options can be negated with --no-<option>.'));\n        lines.push('');\n      }\n\n      // Nested commands section (full detail mode)\n      if (info.nestedCommands?.length) {\n        lines.push(styler.section('Subcommand Details:'));\n        lines.push('');\n        for (const nestedCmd of info.nestedCommands) {\n          lines.push(styler.meta('─'.repeat(60)));\n          lines.push(this.format(nestedCmd));\n        }\n      }\n\n      const result = lines.join(newline);\n      return wrapDocument ? wrapDocument(result) : result;\n    },\n  };\n}\n\n// ============================================================================\n// JSON Formatter\n// ============================================================================\n\nfunction createJsonFormatter(): Formatter {\n  return {\n    format(info: HelpInfo): string {\n      return JSON.stringify(info, null, 2);\n    },\n  };\n}\n\n// ============================================================================\n// Minimal Formatter\n// ============================================================================\n\n/**\n * Creates a minimal formatter that outputs just a single-line usage string.\n */\nfunction createMinimalFormatter(): Formatter {\n  return {\n    format(info: HelpInfo): string {\n      const parts: string[] = [info.usage.command];\n      if (info.usage.hasSubcommands) parts.push('[command]');\n      if (info.positionals && info.positionals.length > 0) {\n        for (const arg of info.positionals) {\n          const name = arg.name.startsWith('...') ? `${arg.name}` : arg.name;\n          parts.push(arg.optional ? `[${name}]` : `<${name}>`);\n        }\n      }\n      if (info.usage.hasArguments) parts.push('[options]');\n      return parts.join(' ');\n    },\n  };\n}\n\nexport function createFormatter(\n  format: HelpFormat | 'auto',\n  detail: HelpDetail = 'standard',\n  theme?: ColorTheme | ColorConfig,\n  all?: boolean,\n  width?: number,\n  terminal?: { columns?: number; isTTY?: boolean },\n  env?: Record<string, string | undefined>,\n): Formatter {\n  if (detail === 'minimal') return createMinimalFormatter();\n  if (format === 'json') return createJsonFormatter();\n  const tw = format === 'markdown' || format === 'html' ? undefined : (width ?? terminal?.columns ?? DEFAULT_TERMINAL_WIDTH);\n  if (format === 'ansi' || (format === 'auto' && shouldUseAnsi(env, terminal?.isTTY)))\n    return createGenericFormatter(createAnsiStyler(theme), createTextLayout(), all, tw);\n  if (format === 'console') return createGenericFormatter(createConsoleStyler(theme), createTextLayout(), all, tw);\n  if (format === 'markdown') return createGenericFormatter(createMarkdownStyler(), createMarkdownLayout(), all);\n  if (format === 'html') return createGenericFormatter(createHtmlStyler(), createHtmlLayout(), all);\n  return createGenericFormatter(createTextStyler(), createTextLayout(), all, tw);\n}\n"],"mappings":";;;;;;AAuJA,SAAS,uBAAuB,QAAgB,QAAsB,iBAA2B,eAAmC;CAClI,MAAM,EAAE,SAAS,QAAQ,MAAM,iBAAiB;CAEhD,SAAS,mBAAmB,MAA0B;EACpD,MAAM,aAAuB,CAAC,OAAO,QAAQ,KAAK,MAAM,OAAO,GAAG,KAAK,MAAM,iBAAiB,OAAO,KAAK,WAAW,IAAI,EAAE;EAE3H,IAAI,KAAK,eAAe,KAAK,YAAY,SAAS,GAChD,KAAK,MAAM,OAAO,KAAK,aAAa;GAClC,MAAM,OAAO,IAAI,KAAK,WAAW,KAAK,IAAI,GAAG,IAAI,SAAS,IAAI;GAC9D,WAAW,KAAK,OAAO,KAAK,IAAI,WAAW,IAAI,KAAK,KAAK,IAAI,KAAK,EAAE,CAAC;EACvE;EAEF,IAAI,KAAK,MAAM,cAAc,WAAW,KAAK,OAAO,KAAK,WAAW,CAAC;EACrE,OAAO,CAAC,GAAG,OAAO,MAAM,QAAQ,EAAE,GAAG,KAAK,UAAU,GAAG;CACzD;CAEA,SAAS,yBAAyB,MAA0B;EAC1D,MAAM,QAAkB,CAAC;EACzB,MAAM,cAAc,KAAK;EAEzB,MAAM,oBAAoB,MAA2B,EAAE,iBAAiB,kBAAkB;EAC1F,MAAM,oBAAoB,MAA0B;GAClD,IAAI,CAAC,EAAE,SAAS,QAAQ,OAAO;IAAE,OAAO;IAAI,QAAQ;GAAG;GACvD,MAAM,cAAc,EAAE,QAAQ,QAAQ,MAAM,MAAM,WAAW;GAC7D,MAAM,aAAa,EAAE,QAAQ,MAAM,MAAM,MAAM,WAAW;GAC1D,MAAM,QAAkB,CAAC;GACzB,MAAM,cAAwB,CAAC;GAC/B,IAAI,YAAY,QAAQ;IACtB,MAAM,KAAK,IAAI,YAAY,KAAK,IAAI,EAAE,EAAE;IACxC,YAAY,KAAK,IAAI,YAAY,KAAK,IAAI,EAAE,EAAE;GAChD;GACA,IAAI,YAAY;IACd,MAAM,KAAK,WAAW;IACtB,YAAY,KAAK,OAAO,KAAK,WAAW,CAAC;GAC3C;GACA,OAAO;IAAE,OAAO,MAAM,SAAS,IAAI,MAAM,KAAK,GAAG,MAAM;IAAI,QAAQ,YAAY,SAAS,IAAI,YAAY,KAAK,GAAG,MAAM;GAAG;EAC3H;EAEA,MAAM,gBAAgB,KAAK,IACzB,GAAG,YAAY,KAAK,MAAM;GACxB,QAAQ,EAAE,OAAO,iBAAiB,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,MAAA,CAAO;EACpE,CAAC,CACH;EAEA,MAAM,UAAU,OAAO,QAAQ,cAAc,MAAM,EAAE,SAAS,EAAE;EAEhE,MAAM,qBAAqB,SAA+B;GACxD,KAAK,MAAM,UAAU,MAAM;IACzB,MAAM,aAAa,iBAAiB,MAAM;IAC1C,MAAM,SAAS,iBAAiB,MAAM;IACtC,MAAM,iBAAiB,OAAO,OAAO,SAAS,WAAW;IACzD,MAAM,UAAU,IAAI,OAAO,KAAK,IAAI,GAAG,gBAAgB,eAAe,SAAS,CAAC,CAAC;IACjF,MAAM,eAAe,CAAC,CAAC,OAAO;IAC9B,MAAM,iBAAiB,OAAO,SAAS;IAMvC,MAAM,YAAsB,CALR,eAChB,OAAO,WAAW,cAAc,KAC/B,iBAAiB,OAAO,KAAK,OAAO,IAAI,IAAI,OAAO,QAAQ,OAAO,IAAI,MACtE,SAAS,OAAO,KAAK,MAAM,IAAI,MAChC,WAAW,QAC2B,OAAO;IAGjD,MAAM,cAAc,OAAO,SAAS,OAAO;IAC3C,IAAI,aACF,UAAU,KAAK,eAAe,OAAO,WAAW,WAAW,IAAI,OAAO,YAAY,WAAW,CAAC;IAEhG,IAAI,cAAc;KAChB,MAAM,iBACJ,OAAO,OAAO,eAAe,WAAW,OAAO,KAAK,iBAAiB,OAAO,WAAW,EAAE,IAAI,OAAO,KAAK,eAAe;KAC1H,UAAU,KAAK,cAAc;IAC/B;IACA,MAAM,KAAK,OAAO,CAAC,IAAI,UAAU,KAAK,EAAE,CAAC;GAC3C;EACF;EAEA,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAAG;GAClD,IAAI,MAAM,SAAS,GAAG,MAAM,KAAK,EAAE;GACnC,MAAM,KAAK,OAAO,QAAQ,MAAM,GAAG,IAAI,KAAK,WAAW,CAAC;GACxD,kBAAkB,KAAM;EAC1B;EAGA,IAAI,CAAC,KAAK,UAAU,QAAQ;GAC1B,MAAM,KAAK,EAAE;GACb,MAAM,KAAK,OAAO,KAAK,QAAQ,KAAK,KAAK,sDAAsD,CAAC;EAClG;EAEA,OAAO;CACT;CAEA,SAAS,yBAAyB,MAA0B;EAC1D,MAAM,QAAkB,CAAC;EACzB,MAAM,OAAO,KAAK;EAElB,MAAM,KAAK,OAAO,QAAQ,YAAY,CAAC;EAEvC,MAAM,gBAAgB,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,KAAK,KAAK,MAAM,EAAE,KAAK,MAAM,CAAC,CAAC;EAC9E,MAAM,UAAU,IAAI,gBAAgB;EACpC,MAAM,gBAAgB,gBAAgB,gBAAgB,UAAU,KAAA;EAChE,MAAM,aAAa,IAAI,OAAO,OAAO;EAErC,KAAK,MAAM,OAAO,MAAM;GACtB,MAAM,UAAU,IAAI,OAAO,KAAK,IAAI,GAAG,gBAAgB,IAAI,KAAK,SAAS,CAAC,CAAC;GAC3E,MAAM,SAAS,OAAO,CAAC,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI;GAElD,MAAM,YAAY,IAAI,eAAe;GACrC,MAAM,aAAa,YAAY,OAAO,YAAY,SAAS,IAAI;GAE/D,MAAM,YAAsB,CAAC;GAC7B,MAAM,kBAA4B,CAAC;GACnC,IAAI,KAAK,MAAM,eAAe,IAAI,MAAM;IACtC,UAAU,KAAK,SAAS;IACxB,gBAAgB,KAAK,OAAO,KAAK,SAAS,CAAC;GAC7C;GACA,IAAI,IAAI,MAAM;IACZ,MAAM,OAAO,aAAa,IAAI,KAAK,KAAK,IAAI,EAAE;IAC9C,UAAU,KAAK,IAAI;IACnB,gBAAgB,KAAK,OAAO,KAAK,IAAI,CAAC;GACxC;GACA,IAAI,IAAI,YAAY,KAAA,GAAW;IAC7B,MAAM,OAAO,aAAa,OAAO,IAAI,OAAO,EAAE;IAC9C,UAAU,KAAK,IAAI;IACnB,gBAAgB,KAAK,OAAO,KAAK,IAAI,CAAC;GACxC;GAEA,MAAM,aAAa,KAAK,eAAe;GAEvC,IAAI,iBAAiB,gBAAgB,GAGnC,IADkB,CAAC,WADD,UAAU,KAAK,GACK,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,GAClD,CAAC,CAAC,UAAU,eACtB,MAAM,KAAK,SAAS,CAAC,YAAY,UAAU,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC;QACjE,IAAI,CAAC,aAAa,UAAU,UAAU,eAAe;IAC1D,MAAM,KAAK,SAAS,UAAU;IAC9B,IAAI,YAAY,MAAM,KAAK,aAAa,UAAU;GACpD,OAAO;IACL,MAAM,UAAU,SAAS,WAAW,aAAa;IACjD,MAAM,KAAK,SAAS,OAAO,YAAY,QAAQ,EAAG,CAAC;IACnD,KAAK,MAAM,SAAS,QAAQ,MAAM,CAAC,GAAG,MAAM,KAAK,aAAa,OAAO,YAAY,KAAK,CAAC;IACvF,IAAI,YAAY,MAAM,KAAK,aAAa,UAAU;GACpD;QAEA,MAAM,KAAK,SAAS,KAAK,CAAC,YAAY,UAAU,CAAC,CAAC;EAEtD;EAEA,OAAO;CACT;CAEA,SAAS,uBAAuB,MAA0B;EACxD,MAAM,QAAkB,CAAC;EACzB,MAAM,UAAU,KAAK,aAAa,CAAC;EAGnC,MAAM,cAAc,UAA4B;GAC9C,IAAI,UAAU,KAAA,GAAW,OAAO;GAChC,IAAI,UAAU,IAAI,OAAO;GACzB,IAAI,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,GAAG,OAAO;GACvD,OAAO;EACT;EAGA,MAAM,aAAa,QAAQ,KAAK,QAAQ;GAEtC,MAAM,QAAQ,aAAa,IAAI,IAAI;GACnC,MAAM,cAAc,SAAS,IAAI,SAAS,SAAS,KAAK,IAAI,QAAQ,IAAI;GACxE,MAAM,mBAAmB,IAAI,SAAS,QAAQ,MAAM,MAAM,WAAW;GAErE,MAAM,aAAa,IAAI,OAAO,SAAS,IAAI,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,IAAI;GAClF,MAAM,WAAW,IAAI,UAAU,SAAS,IAAI,SAAS,KAAK,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,IAAI;GAQvF,OAAO;IAAE;IAAY,YAPF;KAAC,KAAK;KAAe,GAAI,kBAAkB,KAAK,MAAM,KAAK,GAAG,KAAK,CAAC;KAAI,GAAI,WAAW,CAAC,QAAQ,IAAI,CAAC;IAAE,CAAC,CAAC,KAC1H,IAM4B;IAAG,WAJf,IAAI,QAAQ,IAAI,SAAS,YAAa,IAAI,WAAW,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAM;IAIhE,cAAA,CAFtB,CAAC,IAAI;IAE+B;GAAI;EAChE,CAAC;EAGD,MAAM,gBAAgB,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,GAAG,WAAW,KAAK,MAAM,EAAE,WAAW,MAAM,CAAC,CAAC;EAC7F,MAAM,gBAAgB,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,GAAG,WAAW,KAAK,MAAM,EAAE,WAAW,MAAM,CAAC,CAAC;EAC7F,MAAM,eAAe,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,GAAG,WAAW,KAAK,MAAM,EAAE,UAAU,MAAM,CAAC,CAAC;EAC3F,MAAM,cAAc,gBAAgB;EACpC,MAAM,UAAU,KAAK,cAAc,gBAAgB,IAAI,KAAK,gBAAgB,KAAK,eAAe,IAAI,eAAe,IAAI;EACvH,MAAM,gBAAgB,gBAAgB,gBAAgB,UAAU,KAAA;EAChE,MAAM,aAAa,IAAI,OAAO,OAAO;EAGrC,MAAM,UAAU,OAAO,QAAQ,aAAa,MAAM,EAAE,IAAI,SAAS,EAAE;EAEnE,MAAM,oBAAoB,YAA+B;GACvD,KAAK,MAAM,EAAE,YAAY,YAAY,WAAW,cAAc,SAAS,SAAS;IAC9E,MAAM,QAAkB,CAAC;IAGzB,IAAI,aAAa;KACf,MAAM,cAAc,eAAgB,aAAa,OAAO,WAAW,UAAU,IAAI,KAAM,aAAa,OAAO,IAAI,UAAU,IAAI;KAC7H,MAAM,eAAe,IAAI,OAAO,KAAK,IAAI,GAAG,gBAAgB,WAAW,MAAM,CAAC;KAC9E,MAAM,YAAY,aAAa,OAAO;KACtC,MAAM,KAAK,cAAc,eAAe,SAAS;IACnD;IAGA,MAAM,cAAc,eAAe,OAAO,WAAW,UAAU,IAAI,OAAO,IAAI,UAAU;IACxF,MAAM,eAAe,IAAI,OAAO,KAAK,IAAI,GAAG,gBAAgB,WAAW,SAAS,CAAC,CAAC;IAClF,MAAM,KAAK,cAAc,YAAY;IAGrC,IAAI,eAAe,GAAG;KACpB,MAAM,aAAa,YAAY,OAAO,KAAK,SAAS,IAAI;KACxD,MAAM,cAAc,IAAI,OAAO,KAAK,IAAI,GAAG,eAAe,UAAU,SAAS,CAAC,CAAC;KAC/E,MAAM,KAAK,aAAa,WAAW;IACrC;IAEA,MAAM,SAAS,OAAO,CAAC,IAAI,MAAM,KAAK,EAAE;IACxC,MAAM,UAAU,gBAAgB,aAAa,OAAO,CAAC;IAGrD,MAAM,aAAuB,CAAC;IAC9B,MAAM,mBAA6B,CAAC;IACpC,IAAI,gBAAgB,OAAO,IAAI,eAAe,UAAU;KACtD,WAAW,KAAK,cAAc;KAC9B,iBAAiB,KAAK,OAAO,KAAK,cAAc,CAAC;IACnD;IACA,IAAI,WAAW,IAAI,OAAO,GAAG;KAC3B,MAAM,OAAO,aAAa,OAAO,IAAI,OAAO,EAAE;KAC9C,WAAW,KAAK,IAAI;KACpB,iBAAiB,KAAK,OAAO,KAAK,IAAI,CAAC;IACzC;IACA,IAAI,IAAI,MAAM;KACZ,MAAM,OAAO,aAAa,IAAI,KAAK,KAAK,IAAI,EAAE;KAC9C,WAAW,KAAK,IAAI;KACpB,iBAAiB,KAAK,OAAO,KAAK,IAAI,CAAC;IACzC;IAEA,MAAM,YAAY,IAAI,eAAe;IACrC,MAAM,aAAa,YAAa,eAAe,OAAO,WAAW,SAAS,IAAI,OAAO,YAAY,SAAS,IAAK;IAC/G,MAAM,aAAa,KAAK,gBAAgB;IAExC,IAAI,iBAAiB,gBAAgB,GAInC,IADkB,CAAC,WADD,WAAW,KAAK,GACI,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,GAClD,CAAC,CAAC,UAAU,eACtB,MAAM,KAAK,SAAS,CAAC,YAAY,UAAU,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC;SACjE,IAAI,CAAC,aAAa,UAAU,UAAU,eAAe;KAC1D,MAAM,KAAK,SAAS,UAAU;KAC9B,IAAI,YAAY,MAAM,KAAK,aAAa,UAAU;IACpD,OAAO;KACL,MAAM,UAAU,SAAS,WAAW,aAAa;KACjD,MAAM,UAAU,eAAe,OAAO,aAAa,OAAO;KAC1D,MAAM,KAAK,SAAS,QAAQ,QAAQ,EAAG,CAAC;KACxC,KAAK,MAAM,SAAS,QAAQ,MAAM,CAAC,GAAG,MAAM,KAAK,aAAa,QAAQ,KAAK,CAAC;KAC5E,IAAI,YAAY,MAAM,KAAK,aAAa,UAAU;IACpD;SACK;KAEL,MAAM,YAAsB,CAAC;KAC7B,IAAI,YAAY,UAAU,KAAK,UAAU;KACzC,MAAM,KAAK,SAAS,KAAK,SAAS,CAAC;KACnC,IAAI,iBAAiB,SAAS,GAAG,MAAM,KAAK,OAAO,CAAC,IAAI,UAAU;IACpE;IAGA,MAAM,aAAuB,CAAC;IAC9B,IAAI,gBAAgB,OAAO,IAAI,eAAe,UAAU,WAAW,KAAK,OAAO,KAAK,gBAAgB,IAAI,WAAW,EAAE,CAAC;IACtH,IAAI,IAAI,YAAY,IAAI,SAAS,SAAS,GAAG;KAC3C,MAAM,gBAAgB,IAAI,SAAS,KAAK,YAAa,OAAO,YAAY,WAAW,UAAU,KAAK,UAAU,OAAO,CAAE,CAAC,CAAC,KAAK,IAAI;KAChI,WAAW,KAAK,OAAO,QAAQ,UAAU,GAAG,OAAO,aAAa,aAAa,CAAC;IAChF;IACA,IAAI,WAAW,SAAS,GAAG,MAAM,KAAK,UAAU,KAAK,UAAU,CAAC;IAGhE,MAAM,aAAuB,CAAC;IAC9B,IAAI,KAAK,MAAM,eAAe,IAAI,MAAM,WAAW,KAAK,OAAO,KAAK,SAAS,CAAC;IAC9E,IAAI,IAAI,KAAK;KACX,MAAM,UAAU,OAAO,IAAI,QAAQ,WAAW,CAAC,IAAI,GAAG,IAAI,IAAI;KAC9D,WAAW,KAAK,OAAO,QAAQ,MAAM,GAAG,OAAO,aAAa,QAAQ,KAAK,IAAI,CAAC,CAAC;IACjF;IACA,IAAI,IAAI,WACN,WAAW,KAAK,OAAO,QAAQ,SAAS,GAAG,OAAO,aAAa,IAAI,SAAS,CAAC;IAE/E,IAAI,WAAW,SAAS,GAAG,MAAM,KAAK,UAAU,KAAK,UAAU,CAAC;GAClE;EACF;EAEA,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAAG;GAClD,IAAI,MAAM,SAAS,GAAG,MAAM,KAAK,EAAE;GACnC,MAAM,KAAK,OAAO,QAAQ,MAAM,GAAG,IAAI,KAAK,UAAU,CAAC;GACvD,iBAAiB,KAAM;EACzB;EAEA,OAAO;CACT;CAEA,SAAS,sBAAsB,MAA0B;EACvD,MAAM,QAAkB,CAAC;EACzB,MAAM,WAAW,KAAK;EAEtB,IAAI,CAAC,iBAAiB;GAGpB,MAAM,KAAK,GAAG,OAAO,MAAM,SAAS,EAAE,GAAG,OAAO,KAAK;IADjC;IAAkB;IAAW;GACa,CAAC,CAAC,KAAK,IAAI,CAAC,GAAG;GAC7E,MAAM,OAAO,KAAK,MAAM,iBACpB,QAAQ,KAAK,KAAK,iFAClB,QAAQ,KAAK,KAAK;GACtB,MAAM,KAAK,OAAO,KAAK,IAAI,CAAC;GAC5B,OAAO;EACT;EAEA,MAAM,KAAK,OAAO,QAAQ,SAAS,CAAC;EAGpC,MAAM,aAAuB,CAAC;EAC9B,KAAK,MAAM,SAAS,UAAU;GAC5B,WAAW,KAAK,MAAM,KAAK,MAAM;GACjC,IAAI,MAAM,KACR,KAAK,MAAM,OAAO,MAAM,KAEtB,WAAW,KAAK,IAAI,KAAK,SAAS,CAAC;EAGzC;EACA,MAAM,SAAS,KAAK,IAAI,GAAG,UAAU;EAErC,KAAK,MAAM,SAAS,UAAU;GAC5B,MAAM,UAAU,IAAI,OAAO,KAAK,IAAI,GAAG,SAAS,MAAM,KAAK,SAAS,CAAC,CAAC;GACtE,MAAM,QAAkB,CAAC,OAAO,QAAQ,MAAM,IAAI,CAAC;GACnD,IAAI,MAAM,aAAa,MAAM,KAAK,UAAU,OAAO,YAAY,MAAM,WAAW,CAAC;GACjF,MAAM,KAAK,OAAO,CAAC,IAAI,MAAM,KAAK,EAAE,CAAC;GAErC,IAAI,MAAM,KACR,KAAK,MAAM,OAAO,MAAM,KAAK;IAC3B,MAAM,aAAa,IAAI,OAAO,KAAK,IAAI,GAAG,SAAS,IAAI,KAAK,MAAM,CAAC;IACnE,MAAM,WAAqB,CAAC,OAAO,IAAI,IAAI,IAAI,CAAC;IAChD,IAAI,IAAI,aAAa,SAAS,KAAK,aAAa,OAAO,YAAY,IAAI,WAAW,CAAC;IACnF,MAAM,KAAK,OAAO,CAAC,IAAI,SAAS,KAAK,EAAE,CAAC;GAC1C;EAEJ;EAEA,OAAO;CACT;CAEA,OAAO,EACL,OAAO,MAAwB;EAC7B,MAAM,QAAkB,CAAC;EAGzB,IAAI,KAAK,YAAY;GACnB,MAAM,qBACJ,OAAO,KAAK,eAAe,WAAW,mCAAmC,KAAK,eAAe;GAC/F,MAAM,KAAK,OAAO,WAAW,kBAAkB,CAAC;GAChD,MAAM,KAAK,EAAE;EACf;EAGA,MAAM,KAAK,GAAG,mBAAmB,IAAI,CAAC;EACtC,MAAM,KAAK,EAAE;EAGb,IAAI,KAAK,OAAO;GACd,MAAM,KAAK,OAAO,MAAM,KAAK,KAAK,CAAC;GACnC,MAAM,KAAK,EAAE;EACf;EAGA,IAAI,KAAK,WAAW,KAAK,QAAQ,SAAS,GAAG;GAC3C,MAAM,KAAK,OAAO,KAAK,YAAY,KAAK,QAAQ,KAAK,IAAI,GAAG,CAAC;GAC7D,MAAM,KAAK,EAAE;EACf;EAGA,IAAI,KAAK,aAAa;GACpB,MAAM,KAAK,OAAO,YAAY,KAAK,WAAW,CAAC;GAC/C,MAAM,KAAK,EAAE;EACf;EAGA,IAAI,KAAK,YAAY,KAAK,SAAS,SAAS,GAAG;GAC7C,MAAM,KAAK,OAAO,QAAQ,WAAW,CAAC;GACtC,KAAK,MAAM,MAAM,KAAK,UACpB,MAAM,KAAK,OAAO,CAAC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,aAAa,EAAE,CAAC;GAEpE,MAAM,KAAK,EAAE;EACf;EAGA,IAAI,KAAK,eAAe,KAAK,YAAY,SAAS,GAAG;GACnD,MAAM,KAAK,GAAG,yBAAyB,IAAI,CAAC;GAC5C,MAAM,KAAK,EAAE;EACf;EAEA,IAAI,KAAK,eAAe,KAAK,YAAY,SAAS,GAAG;GACnD,MAAM,KAAK,GAAG,yBAAyB,IAAI,CAAC;GAC5C,MAAM,KAAK,EAAE;EACf;EAEA,IAAI,KAAK,aAAa,KAAK,UAAU,SAAS,GAAG;GAC/C,MAAM,KAAK,GAAG,uBAAuB,IAAI,CAAC;GAC1C,MAAM,KAAK,EAAE;EACf;EAEA,IAAI,KAAK,YAAY,KAAK,SAAS,SAAS,GAAG;GAC7C,MAAM,KAAK,GAAG,sBAAsB,IAAI,CAAC;GACzC,MAAM,KAAK,EAAE;EACf;EAGA,IAAI,KAAK,WAAW,MAAM,QAAQ,IAAI,aAAa,IAAI,YAAY,IAAI,GAAG;GACxE,MAAM,KAAK,OAAO,KAAK,oDAAoD,CAAC;GAC5E,MAAM,KAAK,EAAE;EACf;EAGA,IAAI,KAAK,gBAAgB,QAAQ;GAC/B,MAAM,KAAK,OAAO,QAAQ,qBAAqB,CAAC;GAChD,MAAM,KAAK,EAAE;GACb,KAAK,MAAM,aAAa,KAAK,gBAAgB;IAC3C,MAAM,KAAK,OAAO,KAAK,IAAI,OAAO,EAAE,CAAC,CAAC;IACtC,MAAM,KAAK,KAAK,OAAO,SAAS,CAAC;GACnC;EACF;EAEA,MAAM,SAAS,MAAM,KAAK,OAAO;EACjC,OAAO,eAAe,aAAa,MAAM,IAAI;CAC/C,EACF;AACF;AAMA,SAAS,sBAAiC;CACxC,OAAO,EACL,OAAO,MAAwB;EAC7B,OAAO,KAAK,UAAU,MAAM,MAAM,CAAC;CACrC,EACF;AACF;;;;AASA,SAAS,yBAAoC;CAC3C,OAAO,EACL,OAAO,MAAwB;EAC7B,MAAM,QAAkB,CAAC,KAAK,MAAM,OAAO;EAC3C,IAAI,KAAK,MAAM,gBAAgB,MAAM,KAAK,WAAW;EACrD,IAAI,KAAK,eAAe,KAAK,YAAY,SAAS,GAChD,KAAK,MAAM,OAAO,KAAK,aAAa;GAClC,MAAM,OAAO,IAAI,KAAK,WAAW,KAAK,IAAI,GAAG,IAAI,SAAS,IAAI;GAC9D,MAAM,KAAK,IAAI,WAAW,IAAI,KAAK,KAAK,IAAI,KAAK,EAAE;EACrD;EAEF,IAAI,KAAK,MAAM,cAAc,MAAM,KAAK,WAAW;EACnD,OAAO,MAAM,KAAK,GAAG;CACvB,EACF;AACF;AAEA,SAAgB,gBACd,QACA,SAAqB,YACrB,OACA,KACA,OACA,UACA,KACW;CACX,IAAI,WAAW,WAAW,OAAO,uBAAuB;CACxD,IAAI,WAAW,QAAQ,OAAO,oBAAoB;CAClD,MAAM,KAAK,WAAW,cAAc,WAAW,SAAS,KAAA,IAAa,SAAS,UAAU,WAAA;CACxF,IAAI,WAAW,UAAW,WAAW,UAAU,cAAc,KAAK,UAAU,KAAK,GAC/E,OAAO,uBAAuB,iBAAiB,KAAK,GAAG,iBAAiB,GAAG,KAAK,EAAE;CACpF,IAAI,WAAW,WAAW,OAAO,uBAAuB,oBAAoB,KAAK,GAAG,iBAAiB,GAAG,KAAK,EAAE;CAC/G,IAAI,WAAW,YAAY,OAAO,uBAAuB,qBAAqB,GAAG,qBAAqB,GAAG,GAAG;CAC5G,IAAI,WAAW,QAAQ,OAAO,uBAAuB,iBAAiB,GAAG,iBAAiB,GAAG,GAAG;CAChG,OAAO,uBAAuB,iBAAiB,GAAG,iBAAiB,GAAG,KAAK,EAAE;AAC/E"}

package/dist/output/help.d.mts

@@ -0,0 +1,18 @@
+import { ColorConfig, ColorTheme } from "./colorizer.mjs";
+import { HelpDetail, HelpFormat } from "./formatter.mjs";
+//#region src/output/help.d.ts
+type HelpPreferences = {
+  format?: HelpFormat | 'auto';
+  detail?: HelpDetail;
+  theme?: ColorTheme | ColorConfig; /** Show all global commands and flags in full detail */
+  all?: boolean; /** Terminal width for text wrapping. Defaults to terminal columns or 80. */
+  width?: number; /** Terminal capabilities for auto-detection of ANSI and width. */
+  terminal?: {
+    columns?: number;
+    isTTY?: boolean;
+  }; /** Environment variables for auto-detection (e.g., NO_COLOR, CI). */
+  env?: Record<string, string | undefined>;
+};
+//#endregion
+export { HelpPreferences };
+//# sourceMappingURL=help.d.mts.map

package/dist/output/help.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.mts","names":[],"sources":["../../src/output/help.ts"],"mappings":";;;KAgBY,eAAA;EACV,MAAA,GAAS,UAAA;EACT,MAAA,GAAS,UAAA;EACT,KAAA,GAAQ,UAAA,GAAa,WAAA;EAErB,GAAA,YAHS;EAKT,KAAA,WAJqB;EAMrB,QAAA;IAAa,OAAA;IAAkB,KAAA;EAAA,GARtB;EAUT,GAAA,GAAM,MAAA;AAAA"}

package/dist/output/help.mjs

@@ -0,0 +1,267 @@
+import { extractSchemaMetadata, getJsonSchema, parsePositionalConfig } from "../core/args.mjs";
+import { findCommandByName } from "../core/commands.mjs";
+import { getRootCommand } from "../util/utils.mjs";
+import { createFormatter } from "./formatter.mjs";
+//#region src/output/help.ts
+/**
+* Extract positional arguments info from schema based on meta.positional config.
+*/
+function extractPositionalArgsInfo(schema, meta) {
+	const args = [];
+	const positionalNames = /* @__PURE__ */ new Set();
+	if (!schema || !meta?.positional || meta.positional.length === 0) return {
+		args,
+		positionalNames
+	};
+	const positionalConfig = parsePositionalConfig(meta.positional);
+	try {
+		const jsonSchema = getJsonSchema(schema);
+		if (jsonSchema.type === "object" && jsonSchema.properties) {
+			const properties = jsonSchema.properties;
+			const required = jsonSchema.required || [];
+			for (const { name, variadic } of positionalConfig) {
+				const prop = properties[name];
+				if (!prop) continue;
+				positionalNames.add(name);
+				const optMeta = meta.fields?.[name];
+				args.push({
+					name: variadic ? `...${name}` : name,
+					description: optMeta?.description ?? prop.description,
+					optional: !required.includes(name),
+					default: prop.default,
+					type: variadic ? `array<${prop.items?.type || "string"}>` : prop.type,
+					enum: prop.enum ?? prop.items?.enum
+				});
+			}
+		}
+	} catch {}
+	return {
+		args,
+		positionalNames
+	};
+}
+function extractArgsInfo(schema, meta, positionalNames) {
+	const result = [];
+	if (!schema) return result;
+	if (!schema["~standard"].vendor.includes("zod")) return result;
+	const argsMeta = meta?.fields;
+	try {
+		const jsonSchema = getJsonSchema(schema);
+		if (jsonSchema.type === "object" && jsonSchema.properties) {
+			const properties = jsonSchema.properties;
+			const required = jsonSchema.required || [];
+			const propertyNames = new Set(Object.keys(properties));
+			const hasExplicitNegation = (key) => {
+				const camelNegated = `no${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+				if (propertyNames.has(camelNegated)) return true;
+				const kebabNegated = `no-${key}`;
+				if (propertyNames.has(kebabNegated)) return true;
+				return false;
+			};
+			const isNegationOf = (key) => {
+				if (key.startsWith("no") && key.length > 2 && key[2] === key[2]?.toUpperCase()) {
+					const positiveKey = key.charAt(2).toLowerCase() + key.slice(3);
+					if (propertyNames.has(positiveKey)) return true;
+				}
+				if (key.startsWith("no-")) {
+					const positiveKey = key.slice(3);
+					if (propertyNames.has(positiveKey)) return true;
+				}
+				return false;
+			};
+			for (const [key, prop] of Object.entries(properties)) {
+				if (positionalNames?.has(key)) continue;
+				const isOptional = !required.includes(key);
+				const enumValues = prop.enum ?? prop.items?.enum;
+				const optMeta = argsMeta?.[key];
+				const propType = prop.type;
+				const rawNegative = optMeta?.negative ?? prop?.negative;
+				const hasCustomNegative = rawNegative !== void 0;
+				const negativeList = hasCustomNegative ? typeof rawNegative === "string" ? rawNegative ? [rawNegative] : [] : Array.from(rawNegative).filter(Boolean) : void 0;
+				const isNegatable = propType === "boolean" && !hasCustomNegative && !hasExplicitNegation(key) && !isNegationOf(key);
+				result.push({
+					name: key,
+					description: optMeta?.description ?? prop.description,
+					optional: isOptional,
+					default: prop.default,
+					type: propType === "array" ? `${prop.items?.type || "string"}[]` : propType,
+					enum: enumValues,
+					deprecated: optMeta?.deprecated ?? prop?.deprecated,
+					hidden: optMeta?.hidden ?? prop?.hidden,
+					examples: optMeta?.examples ?? prop?.examples,
+					variadic: propType === "array",
+					negatable: isNegatable,
+					negative: negativeList?.length ? negativeList : void 0,
+					group: optMeta?.group
+				});
+			}
+		}
+	} catch {}
+	return result;
+}
+/**
+* Builds a comprehensive HelpInfo structure from a command.
+* This is the single source of truth that all formatters use.
+* @param cmd - The command to build help info for
+* @param detail - The level of detail ('minimal', 'standard', or 'full')
+*/
+function getHelpInfo(cmd, detail = "standard", all) {
+	const rootCmd = getRootCommand(cmd);
+	const isDefaultCommand = cmd.parent && (!cmd.name || cmd.aliases?.includes(""));
+	const nonEmptyAliases = cmd.aliases?.filter(Boolean);
+	const commandName = cmd.path || cmd.name || nonEmptyAliases?.[0] || (cmd.parent ? "[default]" : "program");
+	const remainingAliases = !cmd.name && nonEmptyAliases?.length ? nonEmptyAliases.slice(1) : nonEmptyAliases ?? [];
+	const displayAliases = isDefaultCommand ? [...remainingAliases, "[default]"] : nonEmptyAliases;
+	const { args: positionalArgs, positionalNames } = cmd.argsSchema ? extractPositionalArgsInfo(cmd.argsSchema, cmd.meta) : {
+		args: [],
+		positionalNames: /* @__PURE__ */ new Set()
+	};
+	const hasPositionals = positionalArgs.length > 0;
+	const helpInfo = {
+		name: commandName,
+		title: cmd.title,
+		description: cmd.description,
+		examples: cmd.examples,
+		aliases: displayAliases,
+		deprecated: cmd.deprecated,
+		hidden: cmd.hidden,
+		usage: {
+			command: rootCmd === cmd ? commandName : `${rootCmd.name} ${commandName}`,
+			hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),
+			hasPositionals,
+			hasArguments: false,
+			stdinField: cmd.meta?.stdin
+		}
+	};
+	if (cmd.commands && cmd.commands.length > 0) {
+		const visibleCommands = detail === "full" ? cmd.commands : cmd.commands.filter((c) => !c.hidden);
+		helpInfo.subcommands = [...cmd.action ? [{
+			name: "[default]",
+			title: cmd.title,
+			description: cmd.description
+		}] : [], ...visibleCommands.flatMap((c) => {
+			const isDefault = !c.name || c.aliases?.includes("");
+			const nonEmptyAliases = c.aliases?.filter(Boolean);
+			const displayName = c.name || nonEmptyAliases?.[0] || "[default]";
+			const remainingAliases = !c.name && nonEmptyAliases?.length ? nonEmptyAliases.slice(1) : nonEmptyAliases ?? [];
+			const displayAliases = isDefault && displayName !== "[default]" ? [...remainingAliases, "[default]"] : isDefault ? remainingAliases : nonEmptyAliases;
+			const hasSubcommands = !!(c.commands && c.commands.length > 0);
+			const hasDefaultHandler = c.action || c.commands?.some((sub) => !sub.name || sub.aliases?.includes(""));
+			if (hasSubcommands && hasDefaultHandler) {
+				const defaultSub = !c.action ? c.commands?.find((sub) => !sub.name || sub.aliases?.includes("")) : void 0;
+				const hasDefaultSubInfo = defaultSub && (defaultSub.title || defaultSub.description);
+				return [{
+					name: displayName,
+					title: hasDefaultSubInfo ? defaultSub.title : c.title,
+					description: hasDefaultSubInfo ? defaultSub.description : c.description,
+					aliases: displayAliases?.length ? displayAliases : void 0,
+					deprecated: c.deprecated,
+					hidden: c.hidden,
+					group: c.group
+				}, {
+					name: displayName,
+					title: c.title,
+					description: c.description,
+					deprecated: c.deprecated,
+					hidden: c.hidden,
+					hasSubcommands: true,
+					group: c.group
+				}];
+			}
+			return [{
+				name: displayName,
+				title: c.title,
+				description: c.description,
+				aliases: displayAliases?.length ? displayAliases : void 0,
+				deprecated: c.deprecated,
+				hidden: c.hidden,
+				hasSubcommands,
+				group: c.group
+			}];
+		})];
+		if (detail === "full") helpInfo.nestedCommands = visibleCommands.map((c) => getHelpInfo(c, "full"));
+	}
+	if (hasPositionals) helpInfo.positionals = positionalArgs;
+	if (cmd.argsSchema) {
+		const argsInfo = extractArgsInfo(cmd.argsSchema, cmd.meta, positionalNames);
+		const argMap = Object.fromEntries(argsInfo.map((arg) => [arg.name, arg]));
+		const { flags, aliases } = extractSchemaMetadata(cmd.argsSchema, cmd.meta?.fields, cmd.meta?.autoAlias);
+		for (const [flag, name] of Object.entries(flags)) {
+			const arg = argMap[name];
+			if (!arg) continue;
+			arg.flags = [...arg.flags || [], flag];
+		}
+		for (const [alias, name] of Object.entries(aliases)) {
+			const arg = argMap[name];
+			if (!arg) continue;
+			arg.aliases = [...arg.aliases || [], alias];
+		}
+		const visibleArgs = argsInfo.filter((arg) => !arg.hidden);
+		if (visibleArgs.length > 0) {
+			helpInfo.arguments = visibleArgs;
+			helpInfo.usage.hasArguments = true;
+		}
+	}
+	if (!cmd.parent || all) {
+		const builtins = [];
+		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", rootCmd.commands)) builtins.push({
+			name: "version, -v, --version",
+			description: "Show version information"
+		});
+		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;
+	}
+	return helpInfo;
+}
+function generateHelp(rootCommand, commandObj = rootCommand, prefs) {
+	const helpInfo = getHelpInfo(commandObj, prefs?.detail, prefs?.all);
+	return createFormatter(prefs?.format ?? "auto", prefs?.detail, prefs?.theme, prefs?.all, prefs?.width, prefs?.terminal, prefs?.env).format(helpInfo);
+}
+//#endregion
+export { generateHelp, getHelpInfo };
+
+//# sourceMappingURL=help.mjs.map

package/dist/output/help.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.mjs","names":[],"sources":["../../src/output/help.ts"],"sourcesContent":["import type { StandardJSONSchemaV1 } from '@standard-schema/spec';\nimport { extractSchemaMetadata, getJsonSchema, type PadroneArgsSchemaMeta, parsePositionalConfig } from '../core/args.ts';\nimport { findCommandByName } from '../core/commands.ts';\nimport type { AnyPadroneCommand } from '../types/index.ts';\nimport { getRootCommand } from '../util/utils.ts';\nimport type { ColorConfig, ColorTheme } from './colorizer.ts';\nimport {\n  createFormatter,\n  type HelpArgumentInfo,\n  type HelpDetail,\n  type HelpFormat,\n  type HelpInfo,\n  type HelpPositionalInfo,\n  type HelpSubcommandInfo,\n} from './formatter.ts';\n\nexport type HelpPreferences = {\n  format?: HelpFormat | 'auto';\n  detail?: HelpDetail;\n  theme?: ColorTheme | ColorConfig;\n  /** Show all global commands and flags in full detail */\n  all?: boolean;\n  /** Terminal width for text wrapping. Defaults to terminal columns or 80. */\n  width?: number;\n  /** Terminal capabilities for auto-detection of ANSI and width. */\n  terminal?: { columns?: number; isTTY?: boolean };\n  /** Environment variables for auto-detection (e.g., NO_COLOR, CI). */\n  env?: Record<string, string | undefined>;\n};\n\n/**\n * Extract positional arguments info from schema based on meta.positional config.\n */\nfunction extractPositionalArgsInfo(\n  schema: StandardJSONSchemaV1,\n  meta?: PadroneArgsSchemaMeta,\n): { args: HelpPositionalInfo[]; positionalNames: Set<string> } {\n  const args: HelpPositionalInfo[] = [];\n  const positionalNames = new Set<string>();\n\n  if (!schema || !meta?.positional || meta.positional.length === 0) {\n    return { args, positionalNames };\n  }\n\n  const positionalConfig = parsePositionalConfig(meta.positional);\n\n  try {\n    const jsonSchema = getJsonSchema(schema) as Record<string, any>;\n\n    if (jsonSchema.type === 'object' && jsonSchema.properties) {\n      const properties = jsonSchema.properties as Record<string, any>;\n      const required = (jsonSchema.required as string[]) || [];\n\n      for (const { name, variadic } of positionalConfig) {\n        const prop = properties[name];\n        if (!prop) continue;\n\n        positionalNames.add(name);\n        const optMeta = meta.fields?.[name];\n\n        args.push({\n          name: variadic ? `...${name}` : name,\n          description: optMeta?.description ?? prop.description,\n          optional: !required.includes(name),\n          default: prop.default,\n          type: variadic ? `array<${prop.items?.type || 'string'}>` : prop.type,\n          enum: (prop.enum ?? prop.items?.enum) as string[] | undefined,\n        });\n      }\n    }\n  } catch {\n    // Fallback to empty result if toJSONSchema fails\n  }\n\n  return { args, positionalNames };\n}\n\nfunction extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaMeta, positionalNames?: Set<string>) {\n  const result: HelpArgumentInfo[] = [];\n  if (!schema) return result;\n\n  const vendor = schema['~standard'].vendor;\n  if (!vendor.includes('zod')) return result;\n\n  const argsMeta = meta?.fields;\n\n  try {\n    const jsonSchema = getJsonSchema(schema) as Record<string, any>;\n\n    // Handle object: z.object({ key: z.string(), ... })\n    if (jsonSchema.type === 'object' && jsonSchema.properties) {\n      const properties = jsonSchema.properties as Record<string, any>;\n      const required = (jsonSchema.required as string[]) || [];\n      const propertyNames = new Set(Object.keys(properties));\n\n      // Helper to check if a negated version of an arg exists\n      const hasExplicitNegation = (key: string): boolean => {\n        // Check for noVerbose style (camelCase)\n        const camelNegated = `no${key.charAt(0).toUpperCase()}${key.slice(1)}`;\n        if (propertyNames.has(camelNegated)) return true;\n        // Check for no-verbose style (kebab-case, though rare in JS)\n        const kebabNegated = `no-${key}`;\n        if (propertyNames.has(kebabNegated)) return true;\n        return false;\n      };\n\n      // Helper to check if this arg is itself a negation of another arg\n      const isNegationOf = (key: string): boolean => {\n        // Check for noVerbose -> verbose (camelCase)\n        if (key.startsWith('no') && key.length > 2 && key[2] === key[2]?.toUpperCase()) {\n          const positiveKey = key.charAt(2).toLowerCase() + key.slice(3);\n          if (propertyNames.has(positiveKey)) return true;\n        }\n        // Check for no-verbose -> verbose (kebab-case)\n        if (key.startsWith('no-')) {\n          const positiveKey = key.slice(3);\n          if (propertyNames.has(positiveKey)) return true;\n        }\n        return false;\n      };\n\n      for (const [key, prop] of Object.entries(properties)) {\n        // Skip positional arguments - they are shown in arguments section\n        if (positionalNames?.has(key)) continue;\n\n        const isOptional = !required.includes(key);\n        const enumValues = (prop.enum ?? prop.items?.enum) as string[] | undefined;\n        const optMeta = argsMeta?.[key];\n        const propType = prop.type as string;\n\n        // Resolve custom negative keywords from meta or schema\n        const rawNegative = optMeta?.negative ?? prop?.negative;\n        const hasCustomNegative = rawNegative !== undefined;\n        const negativeList = hasCustomNegative\n          ? typeof rawNegative === 'string'\n            ? rawNegative\n              ? [rawNegative]\n              : []\n            : Array.from(rawNegative as readonly string[]).filter(Boolean)\n          : undefined;\n\n        // Booleans are negatable unless there's an explicit noArg property,\n        // this arg is itself a negation of another arg, or custom negative keywords are set\n        const isNegatable = propType === 'boolean' && !hasCustomNegative && !hasExplicitNegation(key) && !isNegationOf(key);\n\n        result.push({\n          name: key,\n          description: optMeta?.description ?? prop.description,\n          optional: isOptional,\n          default: prop.default,\n          type: propType === 'array' ? `${prop.items?.type || 'string'}[]` : propType,\n          enum: enumValues,\n          deprecated: optMeta?.deprecated ?? prop?.deprecated,\n          hidden: optMeta?.hidden ?? prop?.hidden,\n          examples: optMeta?.examples ?? prop?.examples,\n          variadic: propType === 'array',\n          negatable: isNegatable,\n          negative: negativeList?.length ? negativeList : undefined,\n          group: optMeta?.group,\n        });\n      }\n    }\n  } catch {\n    // Fallback to empty result if toJSONSchema fails\n  }\n\n  return result;\n}\n\n// ============================================================================\n// Core Help Info Builder\n// ============================================================================\n\n/**\n * Builds a comprehensive HelpInfo structure from a command.\n * This is the single source of truth that all formatters use.\n * @param cmd - The command to build help info for\n * @param detail - The level of detail ('minimal', 'standard', or 'full')\n */\nexport function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard', all?: boolean): HelpInfo {\n  const rootCmd = getRootCommand(cmd);\n  // A command is a \"default\" command if its name is '' or it has '' as an alias\n  const isDefaultCommand = cmd.parent && (!cmd.name || cmd.aliases?.includes(''));\n  // For commands with empty name, use the first non-empty alias as display name\n  const nonEmptyAliases = cmd.aliases?.filter(Boolean);\n  const commandName = cmd.path || cmd.name || nonEmptyAliases?.[0] || (cmd.parent ? '[default]' : 'program');\n  // Build display aliases: real aliases (excluding the one promoted to display name) + [default] marker\n  const remainingAliases = !cmd.name && nonEmptyAliases?.length ? nonEmptyAliases.slice(1) : (nonEmptyAliases ?? []);\n  const displayAliases = isDefaultCommand ? [...remainingAliases, '[default]'] : nonEmptyAliases;\n\n  // Extract positional args from schema based on meta.positional\n  const { args: positionalArgs, positionalNames } = cmd.argsSchema\n    ? extractPositionalArgsInfo(cmd.argsSchema, cmd.meta)\n    : { args: [], positionalNames: new Set<string>() };\n\n  const hasPositionals = positionalArgs.length > 0;\n\n  const helpInfo: HelpInfo = {\n    name: commandName,\n    title: cmd.title,\n    description: cmd.description,\n    examples: cmd.examples,\n    aliases: displayAliases,\n    deprecated: cmd.deprecated,\n    hidden: cmd.hidden,\n    usage: {\n      command: rootCmd === cmd ? commandName : `${rootCmd.name} ${commandName}`,\n      hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),\n      hasPositionals,\n      hasArguments: false, // updated below after extracting arguments\n      stdinField: cmd.meta?.stdin,\n    },\n  };\n\n  // Build subcommands info (filter out hidden commands unless showing full detail)\n  if (cmd.commands && cmd.commands.length > 0) {\n    const visibleCommands = detail === 'full' ? cmd.commands : cmd.commands.filter((c) => !c.hidden);\n    // If the command has both a handler and subcommands, show the handler as a \"[default]\" entry\n    const selfEntry: typeof helpInfo.subcommands = cmd.action\n      ? [{ name: '[default]', title: cmd.title, description: cmd.description }]\n      : [];\n\n    helpInfo.subcommands = [\n      ...selfEntry,\n      ...visibleCommands.flatMap((c): HelpSubcommandInfo[] => {\n        const isDefault = !c.name || c.aliases?.includes('');\n        const nonEmptyAliases = c.aliases?.filter(Boolean);\n        const displayName = c.name || nonEmptyAliases?.[0] || '[default]';\n        const remainingAliases = !c.name && nonEmptyAliases?.length ? nonEmptyAliases.slice(1) : (nonEmptyAliases ?? []);\n        // Only add [default] alias marker if it's not already the display name\n        const displayAliases =\n          isDefault && displayName !== '[default]' ? [...remainingAliases, '[default]'] : isDefault ? remainingAliases : nonEmptyAliases;\n        const hasSubcommands = !!(c.commands && c.commands.length > 0);\n\n        // If a command has subcommands AND a default handler (direct or '' subcommand),\n        // show two entries: one for the default action, one for the subcommand router\n        const hasDefaultHandler = c.action || c.commands?.some((sub) => !sub.name || sub.aliases?.includes(''));\n        if (hasSubcommands && hasDefaultHandler) {\n          const defaultSub = !c.action ? c.commands?.find((sub) => !sub.name || sub.aliases?.includes('')) : undefined;\n          const hasDefaultSubInfo = defaultSub && (defaultSub.title || defaultSub.description);\n          return [\n            {\n              name: displayName,\n              title: hasDefaultSubInfo ? defaultSub.title : c.title,\n              description: hasDefaultSubInfo ? defaultSub.description : c.description,\n              aliases: displayAliases?.length ? displayAliases : undefined,\n              deprecated: c.deprecated,\n              hidden: c.hidden,\n              group: c.group,\n            },\n            {\n              name: displayName,\n              title: c.title,\n              description: c.description,\n              deprecated: c.deprecated,\n              hidden: c.hidden,\n              hasSubcommands: true,\n              group: c.group,\n            },\n          ];\n        }\n\n        return [\n          {\n            name: displayName,\n            title: c.title,\n            description: c.description,\n            aliases: displayAliases?.length ? displayAliases : undefined,\n            deprecated: c.deprecated,\n            hidden: c.hidden,\n            hasSubcommands,\n            group: c.group,\n          },\n        ];\n      }),\n    ];\n\n    // In 'full' detail mode, recursively build help for all nested commands\n    if (detail === 'full') {\n      helpInfo.nestedCommands = visibleCommands.map((c) => getHelpInfo(c, 'full'));\n    }\n  }\n\n  // Build arguments info from positionals\n  if (hasPositionals) {\n    helpInfo.positionals = positionalArgs;\n  }\n\n  // Build arguments info with aliases (excluding positional args)\n  if (cmd.argsSchema) {\n    const argsInfo = extractArgsInfo(cmd.argsSchema, cmd.meta, positionalNames);\n    const argMap: Record<string, HelpArgumentInfo> = Object.fromEntries(argsInfo.map((arg) => [arg.name, arg]));\n\n    // Merge flags and aliases into arguments\n    const { flags, aliases } = extractSchemaMetadata(cmd.argsSchema, cmd.meta?.fields, cmd.meta?.autoAlias);\n    for (const [flag, name] of Object.entries(flags)) {\n      const arg = argMap[name];\n      if (!arg) continue;\n      arg.flags = [...(arg.flags || []), flag];\n    }\n    for (const [alias, name] of Object.entries(aliases)) {\n      const arg = argMap[name];\n      if (!arg) continue;\n      arg.aliases = [...(arg.aliases || []), alias];\n    }\n\n    // Filter out hidden arguments\n    const visibleArgs = argsInfo.filter((arg) => !arg.hidden);\n    if (visibleArgs.length > 0) {\n      helpInfo.arguments = visibleArgs;\n      helpInfo.usage.hasArguments = true;\n    }\n  }\n\n  // Add global commands/flags (root command by default, all commands when --all is passed)\n  if (!cmd.parent || all) {\n    const builtins: HelpInfo['builtins'] = [];\n\n    if (!findCommandByName('help', rootCmd.commands)) {\n      builtins.push({\n        name: 'help [command], -h, --help',\n        description: 'Show help for a command',\n        sub: [\n          { name: '--all', description: 'Show all global commands and flags' },\n          { name: '--detail <level>', description: 'Detail level (minimal, standard, full)' },\n          { name: '--format <format>', description: 'Output format (text, ansi, json, markdown, html)' },\n        ],\n      });\n    }\n\n    if (!findCommandByName('version', rootCmd.commands)) {\n      builtins.push({\n        name: 'version, -v, --version',\n        description: 'Show version information',\n      });\n    }\n\n    if (!findCommandByName('completion', rootCmd.commands)) {\n      builtins.push({\n        name: 'completion [shell]',\n        description: 'Generate shell completions (bash, zsh, fish, powershell)',\n      });\n    }\n\n    if (!findCommandByName('man', rootCmd.commands)) {\n      builtins.push({\n        name: 'man',\n        description: 'Show or install man pages (--setup to install, --remove to uninstall) (experimental)',\n      });\n    }\n\n    builtins.push({\n      name: '[command] --repl',\n      description: 'Start interactive REPL scoped to a command',\n    });\n\n    if (!findCommandByName('mcp', rootCmd.commands)) {\n      builtins.push({\n        name: 'mcp [http|stdio]',\n        description: 'Start a Model Context Protocol server to expose commands as AI tools (experimental)',\n        sub: [\n          { name: '--port <port>', description: 'HTTP port (default: 3000)' },\n          { name: '--host <host>', description: 'HTTP host (default: 127.0.0.1)' },\n        ],\n      });\n    }\n\n    builtins.push({\n      name: '--color [theme], --no-color',\n      description: 'Set color theme (default, ocean, warm, monochrome) or disable colors',\n    });\n\n    if (builtins.length > 0) {\n      helpInfo.builtins = builtins;\n    }\n  }\n\n  return helpInfo;\n}\n\n// ============================================================================\n// Main Entry Point\n// ============================================================================\n\nexport function generateHelp(rootCommand: AnyPadroneCommand, commandObj: AnyPadroneCommand = rootCommand, prefs?: HelpPreferences): string {\n  const helpInfo = getHelpInfo(commandObj, prefs?.detail, prefs?.all);\n  const formatter = createFormatter(\n    prefs?.format ?? 'auto',\n    prefs?.detail,\n    prefs?.theme,\n    prefs?.all,\n    prefs?.width,\n    prefs?.terminal,\n    prefs?.env,\n  );\n  return formatter.format(helpInfo);\n}\n"],"mappings":"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"}

package/dist/output/output-indicator.d.mts

@@ -0,0 +1,27 @@
+import { KeyValueOptions, ListItem, ListOptions, TableOptions, TreeNode, TreeOptions } from "./primitives.mjs";
+
+//#region src/output/output-indicator.d.ts
+/**
+ * Runtime output helper injected into action context as `ctx.context.output`.
+ * Provides format-aware output primitives (table, tree, list, key-value).
+ *
+ * Each method renders data using the resolved format (ANSI, text, JSON, markdown, HTML)
+ * and writes it to the runtime's output function.
+ */
+type PadroneOutputIndicator = {
+  /** Render data as a table. */table(data: Record<string, unknown>[], options?: TableOptions): void; /** Render data as a tree. */
+  tree(data: TreeNode | TreeNode[], options?: TreeOptions): void; /** Render data as a list. */
+  list(data: ListItem[], options?: ListOptions): void; /** Render data as aligned key-value pairs. */
+  kv(data: Record<string, unknown>, options?: KeyValueOptions): void; /** Write raw output (same as runtime.output but sets the "already called" flag). */
+  raw(...args: unknown[]): void; /** Whether any output method has been called. */
+  readonly called: boolean;
+};
+/** Declarative output configuration for a command. */
+type OutputPrimitiveType = 'table' | 'tree' | 'list' | 'kv' | 'json';
+type OutputConfig = OutputPrimitiveType | {
+  type: OutputPrimitiveType;
+  options?: TableOptions | TreeOptions | ListOptions | KeyValueOptions;
+};
+//#endregion
+export { OutputConfig, OutputPrimitiveType, PadroneOutputIndicator };
+//# sourceMappingURL=output-indicator.d.mts.map

package/dist/output/output-indicator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-indicator.d.mts","names":[],"sources":["../../src/output/output-indicator.ts"],"mappings":";;;;;AAWA;;;;;KAAY,sBAAA;EAIY,8BAFtB,KAAA,CAAM,IAAA,EAAM,MAAA,qBAA2B,OAAA,GAAU,YAAA,SAItC;EAFX,IAAA,CAAK,IAAA,EAAM,QAAA,GAAW,QAAA,IAAY,OAAA,GAAU,WAAA,SAInC;EAFT,IAAA,CAAK,IAAA,EAAM,QAAA,IAAY,OAAA,GAAU,WAAA,SAE0B;EAA3D,EAAA,CAAG,IAAA,EAAM,MAAA,mBAAyB,OAAA,GAAU,eAAA,SAN5C;EAQA,GAAA,IAAO,IAAA,oBARD;EAAA,SAUG,MAAA;AAAA;;KAIC,mBAAA;AAAA,KACA,YAAA,GACR,mBAAA;EACE,IAAA,EAAM,mBAAA;EAAqB,OAAA,GAAU,YAAA,GAAe,WAAA,GAAc,WAAA,GAAc,eAAA;AAAA"}

package/dist/output/output-indicator.mjs

@@ -0,0 +1,54 @@
+import { renderKeyValue, renderList, renderTable, renderTree } from "./primitives.mjs";
+//#region src/output/output-indicator.ts
+/** Create an output indicator that renders through the given output function and format context. */
+function createOutputIndicator(outputFn, ctx) {
+	let _called = false;
+	const emit = (rendered) => {
+		_called = true;
+		outputFn(rendered);
+	};
+	return {
+		table(data, options) {
+			emit(renderTable(data, options, ctx));
+		},
+		tree(data, options) {
+			emit(renderTree(data, options, ctx));
+		},
+		list(data, options) {
+			emit(renderList(data, options, ctx));
+		},
+		kv(data, options) {
+			emit(renderKeyValue(data, options, ctx));
+		},
+		raw(...args) {
+			_called = true;
+			outputFn(...args);
+		},
+		get called() {
+			return _called;
+		}
+	};
+}
+/** Format a return value using a declarative output config. */
+function formatDeclarativeOutput(value, config, ctx) {
+	const type = typeof config === "string" ? config : config.type;
+	const options = typeof config === "object" ? config.options : void 0;
+	switch (type) {
+		case "table":
+			if (!Array.isArray(value)) return void 0;
+			return renderTable(value, options, ctx);
+		case "tree": return renderTree(value, options, ctx);
+		case "list":
+			if (!Array.isArray(value)) return void 0;
+			return renderList(value, options, ctx);
+		case "kv":
+			if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+			return renderKeyValue(value, options, ctx);
+		case "json": return JSON.stringify(value, null, 2);
+		default: return;
+	}
+}
+//#endregion
+export { createOutputIndicator, formatDeclarativeOutput };
+
+//# sourceMappingURL=output-indicator.mjs.map

package/dist/output/output-indicator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-indicator.mjs","names":[],"sources":["../../src/output/output-indicator.ts"],"sourcesContent":["import type { KeyValueOptions, ListItem, ListOptions, TableOptions, TreeNode, TreeOptions } from './primitives.ts';\nimport { renderKeyValue, renderList, renderTable, renderTree } from './primitives.ts';\nimport type { OutputContext } from './styling.ts';\n\n/**\n * Runtime output helper injected into action context as `ctx.context.output`.\n * Provides format-aware output primitives (table, tree, list, key-value).\n *\n * Each method renders data using the resolved format (ANSI, text, JSON, markdown, HTML)\n * and writes it to the runtime's output function.\n */\nexport type PadroneOutputIndicator = {\n  /** Render data as a table. */\n  table(data: Record<string, unknown>[], options?: TableOptions): void;\n  /** Render data as a tree. */\n  tree(data: TreeNode | TreeNode[], options?: TreeOptions): void;\n  /** Render data as a list. */\n  list(data: ListItem[], options?: ListOptions): void;\n  /** Render data as aligned key-value pairs. */\n  kv(data: Record<string, unknown>, options?: KeyValueOptions): void;\n  /** Write raw output (same as runtime.output but sets the \"already called\" flag). */\n  raw(...args: unknown[]): void;\n  /** Whether any output method has been called. */\n  readonly called: boolean;\n};\n\n/** Declarative output configuration for a command. */\nexport type OutputPrimitiveType = 'table' | 'tree' | 'list' | 'kv' | 'json';\nexport type OutputConfig =\n  | OutputPrimitiveType\n  | { type: OutputPrimitiveType; options?: TableOptions | TreeOptions | ListOptions | KeyValueOptions };\n\n/** Create an output indicator that renders through the given output function and format context. */\nexport function createOutputIndicator(outputFn: (...args: unknown[]) => void, ctx: OutputContext): PadroneOutputIndicator {\n  let _called = false;\n\n  const emit = (rendered: string) => {\n    _called = true;\n    outputFn(rendered);\n  };\n\n  return {\n    table(data, options) {\n      emit(renderTable(data, options, ctx));\n    },\n    tree(data, options) {\n      emit(renderTree(data, options, ctx));\n    },\n    list(data, options) {\n      emit(renderList(data, options, ctx));\n    },\n    kv(data, options) {\n      emit(renderKeyValue(data, options, ctx));\n    },\n    raw(...args) {\n      _called = true;\n      outputFn(...args);\n    },\n    get called() {\n      return _called;\n    },\n  };\n}\n\n/** Format a return value using a declarative output config. */\nexport function formatDeclarativeOutput(value: unknown, config: OutputConfig, ctx: OutputContext): string | undefined {\n  const type = typeof config === 'string' ? config : config.type;\n  const options = typeof config === 'object' ? config.options : undefined;\n\n  switch (type) {\n    case 'table':\n      if (!Array.isArray(value)) return undefined;\n      return renderTable(value as Record<string, unknown>[], options as TableOptions | undefined, ctx);\n    case 'tree':\n      return renderTree(value as TreeNode | TreeNode[], options as TreeOptions | undefined, ctx);\n    case 'list':\n      if (!Array.isArray(value)) return undefined;\n      return renderList(value as ListItem[], options as ListOptions | undefined, ctx);\n    case 'kv':\n      if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;\n      return renderKeyValue(value as Record<string, unknown>, options as KeyValueOptions | undefined, ctx);\n    case 'json':\n      return JSON.stringify(value, null, 2);\n    default:\n      return undefined;\n  }\n}\n"],"mappings":";;;AAiCA,SAAgB,sBAAsB,UAAwC,KAA4C;CACxH,IAAI,UAAU;CAEd,MAAM,QAAQ,aAAqB;EACjC,UAAU;EACV,SAAS,QAAQ;CACnB;CAEA,OAAO;EACL,MAAM,MAAM,SAAS;GACnB,KAAK,YAAY,MAAM,SAAS,GAAG,CAAC;EACtC;EACA,KAAK,MAAM,SAAS;GAClB,KAAK,WAAW,MAAM,SAAS,GAAG,CAAC;EACrC;EACA,KAAK,MAAM,SAAS;GAClB,KAAK,WAAW,MAAM,SAAS,GAAG,CAAC;EACrC;EACA,GAAG,MAAM,SAAS;GAChB,KAAK,eAAe,MAAM,SAAS,GAAG,CAAC;EACzC;EACA,IAAI,GAAG,MAAM;GACX,UAAU;GACV,SAAS,GAAG,IAAI;EAClB;EACA,IAAI,SAAS;GACX,OAAO;EACT;CACF;AACF;;AAGA,SAAgB,wBAAwB,OAAgB,QAAsB,KAAwC;CACpH,MAAM,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO;CAC1D,MAAM,UAAU,OAAO,WAAW,WAAW,OAAO,UAAU,KAAA;CAE9D,QAAQ,MAAR;EACE,KAAK;GACH,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG,OAAO,KAAA;GAClC,OAAO,YAAY,OAAoC,SAAqC,GAAG;EACjG,KAAK,QACH,OAAO,WAAW,OAAgC,SAAoC,GAAG;EAC3F,KAAK;GACH,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG,OAAO,KAAA;GAClC,OAAO,WAAW,OAAqB,SAAoC,GAAG;EAChF,KAAK;GACH,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG,OAAO,KAAA;GAChF,OAAO,eAAe,OAAkC,SAAwC,GAAG;EACrG,KAAK,QACH,OAAO,KAAK,UAAU,OAAO,MAAM,CAAC;EACtC,SACE;CACJ;AACF"}

package/dist/output/primitives.d.mts

@@ -0,0 +1,33 @@
+//#region src/output/primitives.d.ts
+type TableOptions = {
+  /** Explicit column keys to display (default: infer from first row's keys). */columns?: string[]; /** Column key → display header name mapping. */
+  headers?: Record<string, string>; /** Column key → text alignment. */
+  align?: Record<string, 'left' | 'right' | 'center'>; /** Maximum column width before truncation. */
+  maxColumnWidth?: number; /** Show borders (default: true for ansi/text, false for others). */
+  border?: boolean;
+};
+type TreeNode = {
+  label: string;
+  children?: TreeNode[];
+};
+type TreeOptions = {
+  /** Characters per indent level (default: 2). */indent?: number; /** Show tree guide lines (default: true for ansi/text). */
+  guides?: boolean;
+};
+type ListItem = string | {
+  label: string;
+  description?: string;
+};
+type ListOptions = {
+  /** Bullet character (default: '•' for ansi, '-' for text). */bullet?: string; /** Use numbered list instead of bullets. */
+  numbered?: boolean; /** Indent level (default: 0). */
+  indent?: number;
+};
+type KeyValueOptions = {
+  /** Separator between key and value (default: ': '). */separator?: string; /** Align values by padding keys to the same width. */
+  align?: boolean; /** Key → display label mapping. */
+  labels?: Record<string, string>;
+};
+//#endregion
+export { KeyValueOptions, ListItem, ListOptions, TableOptions, TreeNode, TreeOptions };
+//# sourceMappingURL=primitives.d.mts.map

package/dist/output/primitives.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.mts","names":[],"sources":["../../src/output/primitives.ts"],"mappings":";KAIY,YAAA;gFAEV,OAAA,aAFsB;EAItB,OAAA,GAAU,MAAA,kBAEI;EAAd,KAAA,GAAQ,MAAM,uCAFd;EAIA,cAAA,WAFA;EAIA,MAAA;AAAA;AAAA,KA0IU,QAAA;EACV,KAAA;EACA,QAAA,GAAW,QAAQ;AAAA;AAAA,KAGT,WAAA;EAHS,gDAKnB,MAAA,WALA;EAOA,MAAM;AAAA;AAAA,KAyDI,QAAA;EAAsB,KAAA;EAAe,WAAW;AAAA;AAAA,KAEhD,WAAA;EAFA,8DAIV,MAAA;EAEA,QAAA,YAN0D;EAQ1D,MAAA;AAAA;AAAA,KA4DU,eAAA;EAhEV,uDAkEA,SAAA,WA9DA;EAgEA,KAAA,YAhEM;EAkEN,MAAA,GAAS,MAAM;AAAA"}