padrone 1.5.0 → 1.7.0

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

package/src/output/styling.ts

@@ -0,0 +1,221 @@
+import type { PadroneActionContext } from '../types/index.ts';
+import { type ColorConfig, type ColorTheme, createColorizer } from './colorizer.ts';
+
+export const DEFAULT_TERMINAL_WIDTH = 80;
+
+export function wrapText(text: string, maxWidth: number): string[] {
+  if (maxWidth <= 0 || text.length <= maxWidth) return [text];
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let current = '';
+  for (const word of words) {
+    if (current && current.length + 1 + word.length > maxWidth) {
+      lines.push(current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.length > 0 ? lines : [text];
+}
+
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#039;');
+}
+
+// ── Styler ──────────────────────────────────────────────────────────────
+
+/**
+ * Styling functions for semantic text roles.
+ * Used by formatters to apply visual styles (ANSI, HTML, Markdown, etc.)
+ * to different types of content.
+ */
+export 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.
+ */
+export type LayoutConfig = {
+  newline: string;
+  indent: (level: number) => string;
+  join: (parts: string[]) => string;
+  wrapDocument?: (content: string) => string;
+};
+
+// ── Styler Factories ────────────────────────────────────────────────────
+
+export 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,
+  };
+}
+
+export 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,
+  };
+}
+
+export function createConsoleStyler(theme?: ColorTheme | ColorConfig): Styler {
+  return createAnsiStyler(theme);
+}
+
+export 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}~~`,
+  };
+}
+
+export 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 Factories ────────────────────────────────────────────────────
+
+export function createTextLayout(): LayoutConfig {
+  return {
+    newline: '\n',
+    indent: (level) => '  '.repeat(level),
+    join: (parts) => parts.filter(Boolean).join(' '),
+  };
+}
+
+export function createMarkdownLayout(): LayoutConfig {
+  return {
+    newline: '\n\n',
+    indent: (level) => {
+      if (level === 0) return '';
+      if (level === 1) return '  ';
+      return '    ';
+    },
+    join: (parts) => parts.filter(Boolean).join(' '),
+  };
+}
+
+export 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>`,
+  };
+}
+
+// ── Format Detection ────────────────────────────────────────────────────
+
+export 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;
+}
+
+// ── Output Context ──────────────────────────────────────────────────────
+
+/** Resolved formatting context used by output primitives. */
+export type OutputFormat = 'text' | 'ansi' | 'json' | 'markdown' | 'html';
+
+export type OutputContext = {
+  format: OutputFormat;
+  styler: Styler;
+  layout: LayoutConfig;
+  terminalWidth?: number;
+};
+
+/** Resolve the output format from the runtime and caller context. */
+export function resolveOutputFormat(
+  runtime: {
+    format?: string;
+    theme?: ColorTheme | ColorConfig;
+    terminal?: { columns?: number; isTTY?: boolean };
+    env: () => Record<string, string | undefined>;
+  },
+  caller?: PadroneActionContext['caller'],
+): OutputContext {
+  let format: OutputFormat;
+
+  if (caller === 'serve' || caller === 'mcp' || caller === 'tool') {
+    format = 'json';
+  } else if (runtime.format && runtime.format !== 'auto' && runtime.format !== 'console') {
+    format = runtime.format as OutputFormat;
+  } else {
+    format = shouldUseAnsi(runtime.env(), runtime.terminal?.isTTY) ? 'ansi' : 'text';
+  }
+
+  const terminalWidth = format === 'markdown' || format === 'html' ? undefined : (runtime.terminal?.columns ?? DEFAULT_TERMINAL_WIDTH);
+
+  let styler: Styler;
+  let layout: LayoutConfig;
+
+  switch (format) {
+    case 'ansi':
+      styler = createAnsiStyler(runtime.theme);
+      layout = createTextLayout();
+      break;
+    case 'markdown':
+      styler = createMarkdownStyler();
+      layout = createMarkdownLayout();
+      break;
+    case 'html':
+      styler = createHtmlStyler();
+      layout = createHtmlLayout();
+      break;
+    default:
+      styler = createTextStyler();
+      layout = createTextLayout();
+      break;
+  }
+
+  return { format, styler, layout, terminalWidth };
+}

package/src/{zod.d.ts → schema/zod.d.ts}

@@ -1,4 +1,4 @@
-import type { PadroneFieldMeta } from './args.ts';
+import type { PadroneFieldMeta } from '../core/args.ts';
 
 declare module 'zod/v4/core' {
   export interface GlobalMeta extends PadroneFieldMeta {}

package/src/schema/zod.ts

@@ -0,0 +1,50 @@
+import * as z from 'zod/v4';
+import type { PadroneSchema } from '../types/index.ts';
+import { asyncStream } from '../util/stream.ts';
+
+/**
+ * Creates a Zod schema for an async stream field, ready to use in `.arguments()`.
+ * Wraps `z.custom<AsyncIterable<T>>()` with the `asyncStream()` metadata automatically.
+ *
+ * @param itemSchema - Optional item schema for per-item validation.
+ *
+ * @example
+ * ```ts
+ * import { zodAsyncStream } from 'padrone/zod';
+ *
+ * // String lines
+ * z.object({ lines: zodAsyncStream() })
+ *
+ * // Typed items — each line JSON.parse'd and validated
+ * const recordSchema = z.object({ name: z.string(), age: z.number() });
+ * z.object({ records: zodAsyncStream(jsonCodec(recordSchema)) })
+ * ```
+ */
+export function zodAsyncStream<T = string>(itemSchema?: PadroneSchema<unknown, T>) {
+  return z.custom<AsyncIterable<T>>().meta(asyncStream(itemSchema));
+}
+
+/**
+ * JSON codec for Zod schemas
+ * @see https://zod.dev/codecs?id=jsonschema
+ * Unlike the example in the docs, this codec also handles the case where the input is already an object
+ */
+export const jsonCodec = <T extends z.ZodType>(schema: T) =>
+  z.codec(z.union([z.string(), z.unknown()]), schema, {
+    decode: (jsonString, ctx) => {
+      try {
+        // HACK: in some cases the object is already deserialized, we just need to validate it
+        if (typeof jsonString !== 'string') return jsonString as z.input<T>;
+        return JSON.parse(jsonString) as z.input<T>;
+      } catch (err: any) {
+        ctx.issues.push({
+          code: 'invalid_format',
+          format: 'json',
+          input: typeof jsonString === 'string' ? jsonString : JSON.stringify(jsonString),
+          message: err.message,
+        });
+        return z.NEVER;
+      }
+    },
+    encode: (value) => JSON.stringify(value),
+  });