padrone 1.5.0 → 1.7.0

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

@@ -1,5 +1,20 @@
-import { camelToKebab } from './args.ts';
-import { type ColorConfig, type ColorTheme, createColorizer } from './colorizer.ts';
+import { camelToKebab } from '../util/shell-utils.ts';
+import type { ColorConfig, ColorTheme } from './colorizer.ts';
+import {
+  createAnsiStyler,
+  createConsoleStyler,
+  createHtmlLayout,
+  createHtmlStyler,
+  createMarkdownLayout,
+  createMarkdownStyler,
+  createTextLayout,
+  createTextStyler,
+  DEFAULT_TERMINAL_WIDTH,
+  type LayoutConfig,
+  type Styler,
+  shouldUseAnsi,
+  wrapText,
+} from './styling.ts';
 
 export type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';
 export type HelpDetail = 'minimal' | 'standard' | 'full';
@@ -125,143 +140,6 @@ export type Formatter = {
   format: (info: HelpInfo) => string;
 };
 
-// ============================================================================
-// Internal Styling Types
-// ============================================================================
-
-/**
- * Internal styling functions used by formatters.
- * These handle the visual styling of individual text elements.
- */
-type Styler = {
-  command: (text: string) => string;
-  arg: (text: string) => string;
-  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;
-  deprecated: (text: string) => string;
-};
-
-/**
- * Layout configuration for formatters.
- */
-type LayoutConfig = {
-  newline: string;
-  indent: (level: number) => string;
-  join: (parts: string[]) => string;
-  wrapDocument?: (content: string) => string;
-};
-
-// ============================================================================
-// Styler Factories
-// ============================================================================
-
-function createTextStyler(): Styler {
-  return {
-    command: (text) => text,
-    arg: (text) => text,
-    type: (text) => text,
-    description: (text) => text,
-    label: (text) => text,
-    section: (text) => text,
-    meta: (text) => text,
-    example: (text) => text,
-    exampleValue: (text) => text,
-    deprecated: (text) => text,
-  };
-}
-
-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,
-    deprecated: colorizer.deprecated,
-  };
-}
-
-function createConsoleStyler(theme?: ColorTheme | ColorConfig): Styler {
-  return createAnsiStyler(theme);
-}
-
-function createMarkdownStyler(): Styler {
-  return {
-    command: (text) => `**${text}**`,
-    arg: (text) => `\`${text}\``,
-    type: (text) => `\`${text}\``,
-    description: (text) => text,
-    label: (text) => `**${text}**`,
-    section: (text) => `### ${text}`,
-    meta: (text) => `*${text}*`,
-    example: (text) => `**${text}**`,
-    exampleValue: (text) => `\`${text}\``,
-    deprecated: (text) => `~~${text}~~`,
-  };
-}
-
-function escapeHtml(text: string): string {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#039;');
-}
-
-function createHtmlStyler(): Styler {
-  return {
-    command: (text) => `<strong style="color: #00bcd4;">${escapeHtml(text)}</strong>`,
-    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) => `<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>`,
-    deprecated: (text) => `<del style="color: #999;">${escapeHtml(text)}</del>`,
-  };
-}
-
-// ============================================================================
-// Layout Configurations
-// ============================================================================
-
-function createTextLayout(): LayoutConfig {
-  return {
-    newline: '\n',
-    indent: (level) => '  '.repeat(level),
-    join: (parts) => parts.filter(Boolean).join(' '),
-  };
-}
-
-function createMarkdownLayout(): LayoutConfig {
-  return {
-    newline: '\n\n',
-    indent: (level) => {
-      if (level === 0) return '';
-      if (level === 1) return '  ';
-      return '    ';
-    },
-    join: (parts) => parts.filter(Boolean).join(' '),
-  };
-}
-
-function createHtmlLayout(): LayoutConfig {
-  return {
-    newline: '<br>',
-    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>`,
-  };
-}
-
 // ============================================================================
 // Generic Formatter Implementation
 // ============================================================================
@@ -269,7 +147,7 @@ function createHtmlLayout(): LayoutConfig {
 /**
  * Creates a formatter that uses the given styler and layout configuration.
  */
-function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBuiltins?: boolean): Formatter {
+function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBuiltins?: boolean, terminalWidth?: number): Formatter {
   const { newline, indent, join, wrapDocument } = layout;
 
   function formatUsageSection(info: HelpInfo): string[] {
@@ -366,15 +244,53 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBui
     lines.push(styler.section('Arguments:'));
 
     const maxNameLength = Math.min(32, Math.max(...args.map((a) => a.name.length)));
+    const descCol = 2 + maxNameLength + 2;
+    const posAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;
+    const descColPad = ' '.repeat(descCol);
 
     for (const arg of args) {
       const padding = ' '.repeat(Math.max(2, maxNameLength - arg.name.length + 2));
-      const descParts: string[] = [];
-      if (arg.description) descParts.push(styler.description(arg.description));
-      if (info.usage.stdinField === arg.name) descParts.push(styler.meta('(stdin)'));
-      if (arg.enum) descParts.push(styler.meta(`(choices: ${arg.enum.join(', ')})`));
-      if (arg.default !== undefined) descParts.push(styler.meta(`(default: ${String(arg.default)})`));
-      lines.push(indent(1) + styler.arg(arg.name) + padding + join(descParts));
+      const prefix = indent(1) + styler.arg(arg.name) + padding;
+
+      const descPlain = arg.description ?? '';
+      const styledDesc = descPlain ? styler.description(descPlain) : '';
+
+      const metaParts: string[] = [];
+      const styledMetaParts: string[] = [];
+      if (info.usage.stdinField === arg.name) {
+        metaParts.push('(stdin)');
+        styledMetaParts.push(styler.meta('(stdin)'));
+      }
+      if (arg.enum) {
+        const text = `(choices: ${arg.enum.join(', ')})`;
+        metaParts.push(text);
+        styledMetaParts.push(styler.meta(text));
+      }
+      if (arg.default !== undefined) {
+        const text = `(default: ${String(arg.default)})`;
+        metaParts.push(text);
+        styledMetaParts.push(styler.meta(text));
+      }
+
+      const metaStyled = join(styledMetaParts);
+
+      if (posAvailWidth && posAvailWidth > 0) {
+        const metaPlain = metaParts.join(' ');
+        const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');
+        if (fullPlain.length <= posAvailWidth) {
+          lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));
+        } else if (!descPlain || descPlain.length <= posAvailWidth) {
+          lines.push(prefix + styledDesc);
+          if (metaStyled) lines.push(descColPad + metaStyled);
+        } else {
+          const wrapped = wrapText(descPlain, posAvailWidth);
+          lines.push(prefix + styler.description(wrapped[0]!));
+          for (const wline of wrapped.slice(1)) lines.push(descColPad + styler.description(wline));
+          if (metaStyled) lines.push(descColPad + metaStyled);
+        }
+      } else {
+        lines.push(prefix + join([styledDesc, metaStyled]));
+      }
     }
 
     return lines;
@@ -413,6 +329,9 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBui
     const maxNamesWidth = Math.min(32, Math.max(0, ...argColumns.map((c) => c.namesPlain.length)));
     const maxTypeWidth = Math.min(16, Math.max(0, ...argColumns.map((c) => c.typePlain.length)));
     const hasAnyFlags = maxFlagsWidth > 0;
+    const descCol = 2 + (hasAnyFlags ? maxFlagsWidth + 2 : 0) + maxNamesWidth + 2 + (maxTypeWidth > 0 ? maxTypeWidth + 2 : 0);
+    const argAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;
+    const descColPad = ' '.repeat(descCol);
 
     // Split into ordered groups: ungrouped first as "Options:", then each group in first-seen order
     const grouped = Object.groupBy(argColumns, (c) => c.arg.group ?? '');
@@ -441,28 +360,65 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBui
           parts.push(styledType + typePadding);
         }
 
-        // 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));
+        const prefix = indent(1) + parts.join('');
+        const contPad = argAvailWidth ? descColPad : indent(3);
 
-        // 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));
+        // Build inline meta (deprecated no-reason, default, choices)
+        const inlineMeta: string[] = [];
+        const styledInlineMeta: string[] = [];
+        if (isDeprecated && typeof arg.deprecated !== 'string') {
+          inlineMeta.push('(deprecated)');
+          styledInlineMeta.push(styler.meta('(deprecated)'));
+        }
+        if (hasDefault(arg.default)) {
+          const text = `(default: ${String(arg.default)})`;
+          inlineMeta.push(text);
+          styledInlineMeta.push(styler.meta(text));
+        }
+        if (arg.enum) {
+          const text = `(choices: ${arg.enum.join(', ')})`;
+          inlineMeta.push(text);
+          styledInlineMeta.push(styler.meta(text));
+        }
+
+        const descPlain = arg.description ?? '';
+        const styledDesc = descPlain ? (isDeprecated ? styler.deprecated(descPlain) : styler.description(descPlain)) : '';
+        const metaStyled = join(styledInlineMeta);
+
+        if (argAvailWidth && argAvailWidth > 0) {
+          // Terminal-width-aware: try to fit description + meta on one line
+          const metaPlain = inlineMeta.join(' ');
+          const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');
+          if (fullPlain.length <= argAvailWidth) {
+            lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));
+          } else if (!descPlain || descPlain.length <= argAvailWidth) {
+            lines.push(prefix + styledDesc);
+            if (metaStyled) lines.push(descColPad + metaStyled);
+          } else {
+            const wrapped = wrapText(descPlain, argAvailWidth);
+            const styleFn = isDeprecated ? styler.deprecated : styler.description;
+            lines.push(prefix + styleFn(wrapped[0]!));
+            for (const wline of wrapped.slice(1)) lines.push(descColPad + styleFn(wline));
+            if (metaStyled) lines.push(descColPad + metaStyled);
+          }
+        } else {
+          // No terminal width (markdown/html): description on line 1, meta on line 2
+          const descParts: string[] = [];
+          if (styledDesc) descParts.push(styledDesc);
+          lines.push(prefix + join(descParts));
+          if (styledInlineMeta.length > 0) lines.push(indent(3) + metaStyled);
+        }
 
-        // Line 3: deprecated (with reason), examples
+        // Deprecated (with reason), examples — always on separate line
         const line3Parts: string[] = [];
         if (isDeprecated && typeof arg.deprecated === 'string') line3Parts.push(styler.meta(`(deprecated: ${arg.deprecated})`));
         if (arg.examples && arg.examples.length > 0) {
           const exampleValues = arg.examples.map((example) => (typeof example === 'string' ? example : JSON.stringify(example))).join(', ');
           line3Parts.push(styler.example('Example:'), styler.exampleValue(exampleValues));
         }
-        if (line3Parts.length > 0) lines.push(indent(3) + join(line3Parts));
+        if (line3Parts.length > 0) lines.push(contPad + join(line3Parts));
 
-        // Line 4: stdin, env, config
+        // stdin, env, config — always on separate line
         const line4Parts: string[] = [];
         if (info.usage.stdinField === arg.name) line4Parts.push(styler.meta('(stdin)'));
         if (arg.env) {
@@ -472,7 +428,7 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBui
         if (arg.configKey) {
           line4Parts.push(styler.example('Config:'), styler.exampleValue(arg.configKey));
         }
-        if (line4Parts.length > 0) lines.push(indent(3) + join(line4Parts));
+        if (line4Parts.length > 0) lines.push(contPad + join(line4Parts));
       }
     };
 
@@ -632,18 +588,6 @@ function createJsonFormatter(): Formatter {
   };
 }
 
-// ============================================================================
-// Formatter Factory
-// ============================================================================
-
-function shouldUseAnsi(): boolean {
-  if (typeof process === 'undefined') return false;
-  if (process.env.NO_COLOR) return false;
-  if (process.env.CI) return false;
-  if (process.stdout && typeof process.stdout.isTTY === 'boolean') return process.stdout.isTTY;
-  return false;
-}
-
 // ============================================================================
 // Minimal Formatter
 // ============================================================================
@@ -673,13 +617,17 @@ export function createFormatter(
   detail: HelpDetail = 'standard',
   theme?: ColorTheme | ColorConfig,
   all?: boolean,
+  width?: number,
+  terminal?: { columns?: number; isTTY?: boolean },
+  env?: Record<string, string | undefined>,
 ): Formatter {
   if (detail === 'minimal') return createMinimalFormatter();
   if (format === 'json') return createJsonFormatter();
-  if (format === 'ansi' || (format === 'auto' && shouldUseAnsi()))
-    return createGenericFormatter(createAnsiStyler(theme), createTextLayout(), all);
-  if (format === 'console') return createGenericFormatter(createConsoleStyler(theme), createTextLayout(), all);
+  const tw = format === 'markdown' || format === 'html' ? undefined : (width ?? terminal?.columns ?? DEFAULT_TERMINAL_WIDTH);
+  if (format === 'ansi' || (format === 'auto' && shouldUseAnsi(env, terminal?.isTTY)))
+    return createGenericFormatter(createAnsiStyler(theme), createTextLayout(), all, tw);
+  if (format === 'console') return createGenericFormatter(createConsoleStyler(theme), createTextLayout(), all, tw);
   if (format === 'markdown') return createGenericFormatter(createMarkdownStyler(), createMarkdownLayout(), all);
   if (format === 'html') return createGenericFormatter(createHtmlStyler(), createHtmlLayout(), all);
-  return createGenericFormatter(createTextStyler(), createTextLayout(), all);
+  return createGenericFormatter(createTextStyler(), createTextLayout(), all, tw);
 }

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

@@ -1,7 +1,9 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
-import { extractSchemaMetadata, JSON_SCHEMA_OPTS, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
+import { extractSchemaMetadata, getJsonSchema, type PadroneArgsSchemaMeta, parsePositionalConfig } from '../core/args.ts';
+import { findCommandByName } from '../core/commands.ts';
+import type { AnyPadroneCommand } from '../types/index.ts';
+import { getRootCommand } from '../util/utils.ts';
 import type { ColorConfig, ColorTheme } from './colorizer.ts';
-import { findCommandByName } from './command-utils.ts';
 import {
   createFormatter,
   type HelpArgumentInfo,
@@ -11,8 +13,6 @@ import {
   type HelpPositionalInfo,
   type HelpSubcommandInfo,
 } from './formatter.ts';
-import type { AnyPadroneCommand } from './types.ts';
-import { getRootCommand } from './utils.ts';
 
 export type HelpPreferences = {
   format?: HelpFormat | 'auto';
@@ -20,6 +20,12 @@ export type HelpPreferences = {
   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>;
 };
 
 /**
@@ -39,7 +45,7 @@ function extractPositionalArgsInfo(
   const positionalConfig = parsePositionalConfig(meta.positional);
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
+    const jsonSchema = getJsonSchema(schema) as Record<string, any>;
 
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
       const properties = jsonSchema.properties as Record<string, any>;
@@ -79,7 +85,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
   const argsMeta = meta?.fields;
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
+    const jsonSchema = getJsonSchema(schema) as Record<string, any>;
 
     // Handle object: z.object({ key: z.string(), ... })
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
@@ -190,7 +196,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) : undefined,
+      stdinField: cmd.meta?.stdin,
     },
   };
 
@@ -366,6 +372,14 @@ 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, prefs?.all);
-  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail, prefs?.theme, prefs?.all);
+  const formatter = createFormatter(
+    prefs?.format ?? 'auto',
+    prefs?.detail,
+    prefs?.theme,
+    prefs?.all,
+    prefs?.width,
+    prefs?.terminal,
+    prefs?.env,
+  );
   return formatter.format(helpInfo);
 }

package/src/output/output-indicator.ts

@@ -0,0 +1,87 @@
+import type { KeyValueOptions, ListItem, ListOptions, TableOptions, TreeNode, TreeOptions } from './primitives.ts';
+import { renderKeyValue, renderList, renderTable, renderTree } from './primitives.ts';
+import type { OutputContext } from './styling.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.
+ */
+export 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. */
+export type OutputPrimitiveType = 'table' | 'tree' | 'list' | 'kv' | 'json';
+export type OutputConfig =
+  | OutputPrimitiveType
+  | { type: OutputPrimitiveType; options?: TableOptions | TreeOptions | ListOptions | KeyValueOptions };
+
+/** Create an output indicator that renders through the given output function and format context. */
+export function createOutputIndicator(outputFn: (...args: unknown[]) => void, ctx: OutputContext): PadroneOutputIndicator {
+  let _called = false;
+
+  const emit = (rendered: string) => {
+    _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. */
+export function formatDeclarativeOutput(value: unknown, config: OutputConfig, ctx: OutputContext): string | undefined {
+  const type = typeof config === 'string' ? config : config.type;
+  const options = typeof config === 'object' ? config.options : undefined;
+
+  switch (type) {
+    case 'table':
+      if (!Array.isArray(value)) return undefined;
+      return renderTable(value as Record<string, unknown>[], options as TableOptions | undefined, ctx);
+    case 'tree':
+      return renderTree(value as TreeNode | TreeNode[], options as TreeOptions | undefined, ctx);
+    case 'list':
+      if (!Array.isArray(value)) return undefined;
+      return renderList(value as ListItem[], options as ListOptions | undefined, ctx);
+    case 'kv':
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+      return renderKeyValue(value as Record<string, unknown>, options as KeyValueOptions | undefined, ctx);
+    case 'json':
+      return JSON.stringify(value, null, 2);
+    default:
+      return undefined;
+  }
+}