padrone 1.6.0 → 1.7.1

package/src/output/formatter.ts

@@ -1,24 +1,20 @@
 import { camelToKebab } from '../util/shell-utils.ts';
-import { type ColorConfig, type ColorTheme, createColorizer } from './colorizer.ts';
-
-const DEFAULT_TERMINAL_WIDTH = 80;
-
-function wrapText(text: string, maxWidth: number): string[] {
-  if (maxWidth <= 0 || text.length <= maxWidth) return [text];
-  const words = text.split(' ');
-  const lines: string[] = [];
-  let current = '';
-  for (const word of words) {
-    if (current && current.length + 1 + word.length > maxWidth) {
-      lines.push(current);
-      current = word;
-    } else {
-      current = current ? `${current} ${word}` : word;
-    }
-  }
-  if (current) lines.push(current);
-  return lines.length > 0 ? lines : [text];
-}
+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';
@@ -144,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
 // ============================================================================
@@ -729,17 +588,6 @@ function createJsonFormatter(): Formatter {
   };
 }
 
-// ============================================================================
-// Formatter Factory
-// ============================================================================
-
-function shouldUseAnsi(env?: Record<string, string | undefined>, isTTY?: boolean): boolean {
-  if (env?.NO_COLOR) return false;
-  if (env?.CI) return false;
-  if (typeof isTTY === 'boolean') return isTTY;
-  return false;
-}
-
 // ============================================================================
 // Minimal Formatter
 // ============================================================================

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;
+  }
+}

package/src/output/primitives.ts

@@ -0,0 +1,335 @@
+import { escapeHtml, type OutputContext } from './styling.ts';
+
+// ── Table ───────────────────────────────────────────────────────────────
+
+export 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;
+};
+
+function stringifyCell(value: unknown): string {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(value);
+}
+
+function truncate(text: string, max: number): string {
+  if (max <= 0 || text.length <= max) return text;
+  return max <= 1 ? '…' : `${text.slice(0, max - 1)}…`;
+}
+
+function padCell(text: string, width: number, alignment: 'left' | 'right' | 'center' = 'left'): string {
+  const pad = width - text.length;
+  if (pad <= 0) return text;
+  if (alignment === 'right') return ' '.repeat(pad) + text;
+  if (alignment === 'center') {
+    const left = Math.floor(pad / 2);
+    return ' '.repeat(left) + text + ' '.repeat(pad - left);
+  }
+  return text + ' '.repeat(pad);
+}
+
+export function renderTable(data: Record<string, unknown>[], options: TableOptions | undefined, ctx: OutputContext): string {
+  if (data.length === 0) return '';
+  if (ctx.format === 'json') return JSON.stringify(data, null, 2);
+
+  const columns = options?.columns ?? Object.keys(data[0]!);
+  if (columns.length === 0) return '';
+
+  const headers = columns.map((col) => options?.headers?.[col] ?? col);
+  const maxCol = options?.maxColumnWidth;
+
+  const rows = data.map((row) =>
+    columns.map((col) => {
+      const text = stringifyCell(row[col]);
+      return maxCol ? truncate(text, maxCol) : text;
+    }),
+  );
+
+  const colWidths = columns.map((_, i) => {
+    const headerWidth = headers[i]!.length;
+    const maxCellWidth = rows.reduce((max, row) => Math.max(max, row[i]!.length), 0);
+    return Math.max(headerWidth, maxCellWidth);
+  });
+
+  const getAlign = (i: number): 'left' | 'right' | 'center' => options?.align?.[columns[i]!] ?? 'left';
+
+  if (ctx.format === 'markdown') return renderTableMarkdown(headers, rows, colWidths, getAlign);
+  if (ctx.format === 'html') return renderTableHtml(columns, headers, rows, data, getAlign);
+  return renderTableText(headers, rows, colWidths, getAlign, options?.border !== false, ctx);
+}
+
+function renderTableText(
+  headers: string[],
+  rows: string[][],
+  colWidths: number[],
+  getAlign: (i: number) => 'left' | 'right' | 'center',
+  border: boolean,
+  ctx: OutputContext,
+): string {
+  const { styler } = ctx;
+  const formatRow = (cells: string[], style?: (s: string) => string) =>
+    cells.map((cell, i) => {
+      const padded = padCell(cell, colWidths[i]!, getAlign(i));
+      return style ? style(padded) : padded;
+    });
+
+  if (border) {
+    const sep = ctx.styler.meta('─');
+    const divider = colWidths.map((w) => sep.repeat(w + 2)).join(styler.meta('┼'));
+    const row = (cells: string[]) => cells.map((c, i) => ` ${padCell(c, colWidths[i]!, getAlign(i))} `).join(styler.meta('│'));
+    const headerRow = row(headers.map((h) => styler.label(h)));
+    const dataRows = rows.map((r) => row(r.map((c) => styler.description(c))));
+    return [headerRow, styler.meta('─') + divider + styler.meta('─'), ...dataRows].join('\n');
+  }
+
+  const headerCells = formatRow(headers, styler.label);
+  const dataCells = rows.map((r) => formatRow(r, styler.description));
+  const gap = '  ';
+  return [headerCells.join(gap), ...dataCells.map((r) => r.join(gap))].join('\n');
+}
+
+function renderTableMarkdown(
+  headers: string[],
+  rows: string[][],
+  colWidths: number[],
+  getAlign: (i: number) => 'left' | 'right' | 'center',
+): string {
+  const headerLine = `| ${headers.map((h, i) => padCell(h, colWidths[i]!, 'left')).join(' | ')} |`;
+  const separatorLine =
+    '| ' +
+    colWidths
+      .map((w, i) => {
+        const a = getAlign(i);
+        const dashes = '─'.repeat(Math.max(w, 3));
+        if (a === 'center') return `:${dashes}:`;
+        if (a === 'right') return `${dashes}:`;
+        return dashes;
+      })
+      .join(' | ') +
+    ' |';
+  const dataLines = rows.map((r) => `| ${r.map((c, i) => padCell(c, colWidths[i]!, 'left')).join(' | ')} |`);
+  return [headerLine, separatorLine, ...dataLines].join('\n');
+}
+
+function renderTableHtml(
+  columns: string[],
+  headers: string[],
+  _rows: string[][],
+  data: Record<string, unknown>[],
+  getAlign: (i: number) => 'left' | 'right' | 'center',
+): string {
+  const ths = headers.map((h, i) => {
+    const a = getAlign(i);
+    const style = a !== 'left' ? ` style="text-align: ${a};"` : '';
+    return `<th${style}>${escapeHtml(h)}</th>`;
+  });
+  const trs = data.map(
+    (row) =>
+      '<tr>' +
+      columns
+        .map((col, i) => {
+          const a = getAlign(i);
+          const style = a !== 'left' ? ` style="text-align: ${a};"` : '';
+          return `<td${style}>${escapeHtml(stringifyCell(row[col]))}</td>`;
+        })
+        .join('') +
+      '</tr>',
+  );
+  return `<table><thead><tr>${ths.join('')}</tr></thead><tbody>${trs.join('')}</tbody></table>`;
+}
+
+// ── Tree ────────────────────────────────────────────────────────────────
+
+export type TreeNode = {
+  label: string;
+  children?: TreeNode[];
+};
+
+export type TreeOptions = {
+  /** Characters per indent level (default: 2). */
+  indent?: number;
+  /** Show tree guide lines (default: true for ansi/text). */
+  guides?: boolean;
+};
+
+export function renderTree(data: TreeNode | TreeNode[], options: TreeOptions | undefined, ctx: OutputContext): string {
+  const nodes = Array.isArray(data) ? data : [data];
+  if (nodes.length === 0) return '';
+  if (ctx.format === 'json') return JSON.stringify(nodes, null, 2);
+  if (ctx.format === 'markdown') return renderTreeMarkdown(nodes, 0);
+  if (ctx.format === 'html') return renderTreeHtml(nodes);
+
+  const guides = options?.guides !== false;
+  return renderTreeText(nodes, '', guides, ctx).join('\n');
+}
+
+function renderTreeText(nodes: TreeNode[], prefix: string, guides: boolean, ctx: OutputContext): string[] {
+  const lines: string[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]!;
+    const isLast = i === nodes.length - 1;
+    if (guides) {
+      const connector = isLast ? '└── ' : '├── ';
+      const childPrefix = isLast ? '    ' : '│   ';
+      lines.push(prefix + ctx.styler.meta(connector) + ctx.styler.label(node.label));
+      if (node.children?.length) lines.push(...renderTreeText(node.children, prefix + ctx.styler.meta(childPrefix), guides, ctx));
+    } else {
+      const indent = prefix ? `${prefix}  ` : '';
+      lines.push(indent + ctx.styler.label(node.label));
+      if (node.children?.length) lines.push(...renderTreeText(node.children, indent, guides, ctx));
+    }
+  }
+  return lines;
+}
+
+function renderTreeMarkdown(nodes: TreeNode[], depth: number): string {
+  return nodes
+    .map((node) => {
+      const indent = '  '.repeat(depth);
+      const line = `${indent}- ${node.label}`;
+      if (!node.children?.length) return line;
+      return `${line}\n${renderTreeMarkdown(node.children, depth + 1)}`;
+    })
+    .join('\n');
+}
+
+function renderTreeHtml(nodes: TreeNode[]): string {
+  const items = nodes
+    .map((node) => {
+      const label = escapeHtml(node.label);
+      if (!node.children?.length) return `<li>${label}</li>`;
+      return `<li>${label}${renderTreeHtml(node.children)}</li>`;
+    })
+    .join('');
+  return `<ul>${items}</ul>`;
+}
+
+// ── List ────────────────────────────────────────────────────────────────
+
+export type ListItem = string | { label: string; description?: string };
+
+export 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;
+};
+
+export function renderList(data: ListItem[], options: ListOptions | undefined, ctx: OutputContext): string {
+  if (data.length === 0) return '';
+  if (ctx.format === 'json') {
+    const normalized = data.map((item) => (typeof item === 'string' ? { label: item } : item));
+    return JSON.stringify(normalized, null, 2);
+  }
+  if (ctx.format === 'markdown') return renderListMarkdown(data, options);
+  if (ctx.format === 'html') return renderListHtml(data, options);
+  return renderListText(data, options, ctx);
+}
+
+function renderListText(data: ListItem[], options: ListOptions | undefined, ctx: OutputContext): string {
+  const { styler } = ctx;
+  const numbered = options?.numbered ?? false;
+  const bullet = options?.bullet ?? (ctx.format === 'ansi' ? '•' : '-');
+  const baseIndent = '  '.repeat(options?.indent ?? 0);
+
+  return data
+    .map((item, i) => {
+      const prefix = numbered ? `${i + 1}.` : bullet;
+      const label = typeof item === 'string' ? item : item.label;
+      const desc = typeof item === 'object' && item.description ? item.description : undefined;
+      const line = `${baseIndent}${styler.meta(prefix)} ${styler.label(label)}`;
+      if (!desc) return line;
+      return `${line}  ${styler.description(desc)}`;
+    })
+    .join('\n');
+}
+
+function renderListMarkdown(data: ListItem[], options: ListOptions | undefined): string {
+  const numbered = options?.numbered ?? false;
+  return data
+    .map((item, i) => {
+      const prefix = numbered ? `${i + 1}.` : '-';
+      const label = typeof item === 'string' ? item : item.label;
+      const desc = typeof item === 'object' && item.description ? item.description : undefined;
+      if (!desc) return `${prefix} ${label}`;
+      return `${prefix} **${label}** — ${desc}`;
+    })
+    .join('\n');
+}
+
+function renderListHtml(data: ListItem[], options: ListOptions | undefined): string {
+  const tag = options?.numbered ? 'ol' : 'ul';
+  const items = data
+    .map((item) => {
+      const label = typeof item === 'string' ? item : item.label;
+      const desc = typeof item === 'object' && item.description ? item.description : undefined;
+      if (!desc) return `<li>${escapeHtml(label)}</li>`;
+      return `<li><strong>${escapeHtml(label)}</strong> — ${escapeHtml(desc)}</li>`;
+    })
+    .join('');
+  return `<${tag}>${items}</${tag}>`;
+}
+
+// ── Key-Value ───────────────────────────────────────────────────────────
+
+export 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>;
+};
+
+export function renderKeyValue(data: Record<string, unknown>, options: KeyValueOptions | undefined, ctx: OutputContext): string {
+  const entries = Object.entries(data);
+  if (entries.length === 0) return '';
+  if (ctx.format === 'json') return JSON.stringify(data, null, 2);
+  if (ctx.format === 'markdown') return renderKeyValueMarkdown(entries, options);
+  if (ctx.format === 'html') return renderKeyValueHtml(entries, options);
+  return renderKeyValueText(entries, options, ctx);
+}
+
+function getLabel(key: string, labels?: Record<string, string>): string {
+  return labels?.[key] ?? key;
+}
+
+function renderKeyValueText(entries: [string, unknown][], options: KeyValueOptions | undefined, ctx: OutputContext): string {
+  const { styler } = ctx;
+  const sep = options?.separator ?? ': ';
+  const shouldAlign = options?.align !== false;
+
+  const displayLabels = entries.map(([k]) => getLabel(k, options?.labels));
+  const maxWidth = shouldAlign ? Math.max(...displayLabels.map((l) => l.length)) : 0;
+
+  return entries
+    .map(([_key, value], i) => {
+      const label = displayLabels[i]!;
+      const paddedLabel = shouldAlign ? label + ' '.repeat(maxWidth - label.length) : label;
+      return `${styler.label(paddedLabel)}${styler.meta(sep)}${styler.description(stringifyCell(value))}`;
+    })
+    .join('\n');
+}
+
+function renderKeyValueMarkdown(entries: [string, unknown][], options: KeyValueOptions | undefined): string {
+  return entries.map(([key, value]) => `- **${getLabel(key, options?.labels)}**: ${stringifyCell(value)}`).join('\n');
+}
+
+function renderKeyValueHtml(entries: [string, unknown][], options: KeyValueOptions | undefined): string {
+  const items = entries
+    .map(([key, value]) => `<dt>${escapeHtml(getLabel(key, options?.labels))}</dt><dd>${escapeHtml(stringifyCell(value))}</dd>`)
+    .join('');
+  return `<dl>${items}</dl>`;
+}