@mandujs/cli 0.9.46 → 0.11.0

package/src/terminal/stream-writer.ts

@@ -0,0 +1,214 @@
+/**
+ * DNA-013: Safe Stream Writer
+ *
+ * 파이프 환경에서 EPIPE 에러를 안전하게 처리
+ * - `mandu routes list | head -5` 같은 파이프 사용 시 안전
+ * - Broken pipe 감지 후 추가 쓰기 방지
+ */
+
+/**
+ * Safe Stream Writer 옵션
+ */
+export interface SafeStreamWriterOptions {
+  /**
+   * Broken pipe 발생 시 콜백
+   */
+  onBrokenPipe?: (error: NodeJS.ErrnoException, stream: NodeJS.WriteStream) => void;
+
+  /**
+   * 조용히 실패 (에러 출력 안 함)
+   */
+  silent?: boolean;
+
+  /**
+   * Broken pipe 이외의 에러 핸들러 (선택)
+   */
+  onError?: (error: Error, stream: NodeJS.WriteStream) => void;
+}
+
+/**
+ * Safe Stream Writer 인터페이스
+ */
+export interface SafeStreamWriter {
+  /**
+   * 스트림에 텍스트 쓰기
+   * @returns 성공 여부
+   */
+  write: (stream: NodeJS.WriteStream, text: string) => boolean;
+
+  /**
+   * 스트림에 줄 쓰기 (자동 개행)
+   * @returns 성공 여부
+   */
+  writeLine: (stream: NodeJS.WriteStream, text: string) => boolean;
+
+  /**
+   * stdout에 쓰기 (편의 메서드)
+   */
+  print: (text: string) => boolean;
+
+  /**
+   * stdout에 줄 쓰기 (편의 메서드)
+   */
+  println: (text: string) => boolean;
+
+  /**
+   * stderr에 쓰기 (편의 메서드)
+   */
+  printError: (text: string) => boolean;
+
+  /**
+   * 상태 리셋
+   */
+  reset: () => void;
+
+  /**
+   * 스트림이 닫혔는지 확인
+   */
+  isClosed: () => boolean;
+}
+
+/**
+ * Broken Pipe 에러인지 확인
+ */
+function isBrokenPipeError(err: unknown): err is NodeJS.ErrnoException {
+  const errno = err as NodeJS.ErrnoException;
+  return errno?.code === "EPIPE" || errno?.code === "EIO";
+}
+
+/**
+ * Safe Stream Writer 생성
+ *
+ * @example
+ * ```ts
+ * const writer = createSafeStreamWriter();
+ *
+ * // 기본 사용
+ * writer.println("Hello, World!");
+ *
+ * // 파이프에서 안전하게 사용
+ * for (const line of lines) {
+ *   if (!writer.println(line)) {
+ *     // 파이프가 닫힘, 루프 종료
+ *     break;
+ *   }
+ * }
+ * ```
+ */
+export function createSafeStreamWriter(
+  options: SafeStreamWriterOptions = {}
+): SafeStreamWriter {
+  const closedStreams = new Set<NodeJS.WriteStream>();
+  const errorHandlers = new Map<NodeJS.WriteStream, (err: Error) => void>();
+
+  const ensureErrorHandler = (stream: NodeJS.WriteStream): void => {
+    if (errorHandlers.has(stream)) return;
+
+    const handler = (err: Error) => {
+      if (isBrokenPipeError(err)) {
+        closedStreams.add(stream);
+        options.onBrokenPipe?.(err, stream);
+        return;
+      }
+
+      if (options.onError) {
+        options.onError(err, stream);
+        return;
+      }
+
+      if (!options.silent) {
+        console.error("[SafeStreamWriter] Stream error:", err);
+      }
+
+      // 비정상 에러는 기존 동작을 유지하도록 비동기 재-throw
+      setTimeout(() => {
+        throw err;
+      }, 0);
+    };
+
+    stream.on("error", handler);
+    errorHandlers.set(stream, handler);
+  };
+
+  const isStreamClosed = (stream: NodeJS.WriteStream): boolean => {
+    const anyStream = stream as NodeJS.WriteStream & {
+      destroyed?: boolean;
+      writableEnded?: boolean;
+    };
+    if (anyStream.destroyed || anyStream.writableEnded) return true;
+    return closedStreams.has(stream);
+  };
+
+  const write = (stream: NodeJS.WriteStream, text: string): boolean => {
+    if (isStreamClosed(stream)) return false;
+
+    ensureErrorHandler(stream);
+
+    try {
+      stream.write(text);
+      return true;
+    } catch (err) {
+      if (!isBrokenPipeError(err)) {
+        throw err;
+      }
+
+      closedStreams.add(stream);
+      options.onBrokenPipe?.(err, stream);
+      return false;
+    }
+  };
+
+  return {
+    write,
+    writeLine: (stream, text) => write(stream, `${text}\n`),
+    print: (text) => write(process.stdout, text),
+    println: (text) => write(process.stdout, `${text}\n`),
+    printError: (text) => write(process.stderr, `${text}\n`),
+    reset: () => {
+      closedStreams.clear();
+      for (const [stream, handler] of errorHandlers) {
+        stream.removeListener("error", handler);
+      }
+      errorHandlers.clear();
+    },
+    isClosed: () => isStreamClosed(process.stdout),
+  };
+}
+
+/**
+ * 기본 Safe Writer 인스턴스 (싱글톤)
+ */
+let defaultWriter: SafeStreamWriter | null = null;
+
+/**
+ * 기본 Safe Writer 가져오기
+ */
+export function getSafeWriter(): SafeStreamWriter {
+  if (!defaultWriter) {
+    defaultWriter = createSafeStreamWriter({ silent: true });
+  }
+  return defaultWriter;
+}
+
+/**
+ * 안전한 console.log 대체
+ *
+ * @example
+ * ```ts
+ * import { safePrint, safePrintln } from "./stream-writer";
+ *
+ * safePrintln("Hello, World!");
+ * // 파이프가 닫혀도 에러 없음
+ * ```
+ */
+export function safePrint(text: string): boolean {
+  return getSafeWriter().print(text);
+}
+
+export function safePrintln(text: string): boolean {
+  return getSafeWriter().println(text);
+}
+
+export function safePrintError(text: string): boolean {
+  return getSafeWriter().printError(text);
+}

package/src/terminal/table.ts

@@ -0,0 +1,354 @@
+/**
+ * DNA-011: ANSI-aware Table Rendering
+ *
+ * 터미널 테이블 렌더링
+ * - ANSI 색상 코드 인식 (너비 계산에서 제외)
+ * - 유니코드 박스 문자 지원
+ * - 반응형 너비 조정 (flex 컬럼)
+ */
+
+import { stripAnsi } from "./theme.js";
+
+/**
+ * 테이블 컬럼 정의
+ */
+export interface TableColumn {
+  /** 데이터 키 */
+  key: string;
+  /** 헤더 텍스트 */
+  header: string;
+  /** 정렬 (기본: left) */
+  align?: "left" | "right" | "center";
+  /** 최소 너비 */
+  minWidth?: number;
+  /** 최대 너비 */
+  maxWidth?: number;
+  /** 반응형 너비 조정 대상 */
+  flex?: boolean;
+}
+
+/**
+ * 테두리 스타일
+ */
+export type BorderStyle = "unicode" | "ascii" | "none";
+
+/**
+ * 테이블 렌더링 옵션
+ */
+export interface RenderTableOptions {
+  /** 컬럼 정의 */
+  columns: TableColumn[];
+  /** 데이터 행 */
+  rows: Record<string, unknown>[];
+  /** 테두리 스타일 (기본: unicode) */
+  border?: BorderStyle;
+  /** 최대 테이블 너비 */
+  maxWidth?: number;
+  /** 헤더 표시 여부 (기본: true) */
+  showHeader?: boolean;
+  /** 컴팩트 모드 (패딩 최소화) */
+  compact?: boolean;
+}
+
+/**
+ * 박스 그리기 문자
+ */
+interface BoxChars {
+  tl: string; // top-left
+  tr: string; // top-right
+  bl: string; // bottom-left
+  br: string; // bottom-right
+  h: string;  // horizontal
+  v: string;  // vertical
+  t: string;  // top junction
+  b: string;  // bottom junction
+  ml: string; // middle-left
+  mr: string; // middle-right
+  m: string;  // middle junction
+}
+
+const UNICODE_BOX: BoxChars = {
+  tl: "┌",
+  tr: "┐",
+  bl: "└",
+  br: "┘",
+  h: "─",
+  v: "│",
+  t: "┬",
+  b: "┴",
+  ml: "├",
+  mr: "┤",
+  m: "┼",
+};
+
+const ASCII_BOX: BoxChars = {
+  tl: "+",
+  tr: "+",
+  bl: "+",
+  br: "+",
+  h: "-",
+  v: "|",
+  t: "+",
+  b: "+",
+  ml: "+",
+  mr: "+",
+  m: "+",
+};
+
+/**
+ * ANSI 코드를 제외한 실제 표시 너비 계산
+ */
+function displayWidth(str: string): number {
+  return stripAnsi(str).length;
+}
+
+/**
+ * 문자열 패딩 (ANSI 인식)
+ */
+function padString(
+  str: string,
+  width: number,
+  align: "left" | "right" | "center" = "left"
+): string {
+  const visibleLen = displayWidth(str);
+  const padding = width - visibleLen;
+
+  if (padding <= 0) return str;
+
+  switch (align) {
+    case "right":
+      return " ".repeat(padding) + str;
+    case "center": {
+      const left = Math.floor(padding / 2);
+      const right = padding - left;
+      return " ".repeat(left) + str + " ".repeat(right);
+    }
+    case "left":
+    default:
+      return str + " ".repeat(padding);
+  }
+}
+
+/**
+ * 문자열 트렁케이션 (ANSI 인식)
+ */
+function truncateWithAnsi(str: string, maxWidth: number): string {
+  const plain = stripAnsi(str);
+  if (plain.length <= maxWidth) return str;
+
+  // ANSI 코드 위치 추적
+  const ansiRegex = /\x1b\[[0-9;]*m/g;
+  const ansiCodes: { index: number; code: string }[] = [];
+  let match;
+  while ((match = ansiRegex.exec(str)) !== null) {
+    ansiCodes.push({ index: match.index, code: match[0] });
+  }
+
+  // plain text 기준으로 트렁케이션
+  const truncatedPlain = plain.slice(0, maxWidth - 1) + "…";
+
+  // ANSI 코드가 없으면 그대로 반환
+  if (ansiCodes.length === 0) return truncatedPlain;
+
+  // ANSI 코드 재삽입 (복잡하므로 단순화)
+  // 첫 번째와 마지막 ANSI 코드만 보존
+  const firstCode = ansiCodes[0]?.code || "";
+  const resetCode = "\x1b[0m";
+
+  if (firstCode && ansiCodes.length > 0) {
+    return firstCode + truncatedPlain + resetCode;
+  }
+
+  return truncatedPlain;
+}
+
+/**
+ * 컬럼 너비 계산
+ */
+function calculateWidths(
+  columns: TableColumn[],
+  rows: Record<string, unknown>[],
+  maxWidth?: number,
+  compact?: boolean,
+  border: BorderStyle = "unicode"
+): number[] {
+  const padding = compact ? 1 : 2;
+
+  // 각 컬럼의 초기 너비 계산
+  const widths = columns.map((col) => {
+    const headerWidth = displayWidth(col.header);
+    const maxCellWidth = Math.max(
+      0,
+      ...rows.map((row) => displayWidth(String(row[col.key] ?? "")))
+    );
+    const contentWidth = Math.max(headerWidth, maxCellWidth);
+
+    let width = contentWidth + padding;
+
+    if (col.minWidth) width = Math.max(width, col.minWidth);
+    if (col.maxWidth) width = Math.min(width, col.maxWidth);
+
+    return width;
+  });
+
+  // 최대 너비 제약 처리
+  if (maxWidth) {
+    const borderWidth = border === "none" ? 0 : columns.length + 1; // 세로선 개수
+    const totalWidth = widths.reduce((a, b) => a + b, 0) + borderWidth;
+
+    if (totalWidth > maxWidth) {
+      const overflow = totalWidth - maxWidth;
+      const flexIndices = columns
+        .map((c, i) => (c.flex ? i : -1))
+        .filter((i) => i >= 0);
+
+      if (flexIndices.length > 0) {
+        // flex 컬럼에서 균등 축소
+        const shrinkPerColumn = Math.ceil(overflow / flexIndices.length);
+        for (const idx of flexIndices) {
+          const minW = columns[idx].minWidth ?? 5;
+          widths[idx] = Math.max(minW, widths[idx] - shrinkPerColumn);
+        }
+      }
+    }
+  }
+
+  return widths;
+}
+
+/**
+ * 테이블 렌더링
+ *
+ * @example
+ * ```ts
+ * const output = renderTable({
+ *   columns: [
+ *     { key: "name", header: "Name", minWidth: 10 },
+ *     { key: "status", header: "Status", align: "center" },
+ *     { key: "size", header: "Size", align: "right" },
+ *   ],
+ *   rows: [
+ *     { name: "file1.ts", status: "✓", size: "1.2KB" },
+ *     { name: "file2.ts", status: "✗", size: "3.4KB" },
+ *   ],
+ *   border: "unicode",
+ * });
+ *
+ * // ┌────────────┬────────┬───────┐
+ * // │ Name       │ Status │  Size │
+ * // ├────────────┼────────┼───────┤
+ * // │ file1.ts   │   ✓    │ 1.2KB │
+ * // │ file2.ts   │   ✗    │ 3.4KB │
+ * // └────────────┴────────┴───────┘
+ * ```
+ */
+export function renderTable(options: RenderTableOptions): string {
+  const {
+    columns,
+    rows,
+    border = "unicode",
+    maxWidth,
+    showHeader = true,
+    compact = false,
+  } = options;
+
+  if (columns.length === 0) return "";
+
+  const widths = calculateWidths(columns, rows, maxWidth, compact, border);
+  const box = border === "unicode" ? UNICODE_BOX : ASCII_BOX;
+  const lines: string[] = [];
+
+  // 수평선 생성
+  const createLine = (
+    left: string,
+    mid: string,
+    right: string,
+    fill: string
+  ): string => {
+    const segments = widths.map((w) => fill.repeat(w));
+    return left + segments.join(mid) + right;
+  };
+
+  // 데이터 행 생성
+  const createRow = (data: Record<string, unknown>): string => {
+    const cells = columns.map((col, i) => {
+      let value = String(data[col.key] ?? "");
+      const width = widths[i];
+
+      // 트렁케이션
+      if (displayWidth(value) > width - (compact ? 1 : 2)) {
+        value = truncateWithAnsi(value, width - (compact ? 1 : 2));
+      }
+
+      // 패딩
+      const padded = padString(value, width - (compact ? 0 : 1), col.align);
+      return compact ? padded : " " + padded;
+    });
+
+    if (border === "none") {
+      return cells.join(" ");
+    }
+    return box.v + cells.join(box.v) + box.v;
+  };
+
+  // 상단 테두리
+  if (border !== "none") {
+    lines.push(createLine(box.tl, box.t, box.tr, box.h));
+  }
+
+  // 헤더
+  if (showHeader) {
+    const headerRow: Record<string, unknown> = {};
+    for (const col of columns) {
+      headerRow[col.key] = col.header;
+    }
+    lines.push(createRow(headerRow));
+
+    // 헤더 구분선
+    if (border !== "none") {
+      lines.push(createLine(box.ml, box.m, box.mr, box.h));
+    }
+  }
+
+  // 데이터 행
+  for (const row of rows) {
+    lines.push(createRow(row));
+  }
+
+  // 하단 테두리
+  if (border !== "none") {
+    lines.push(createLine(box.bl, box.b, box.br, box.h));
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 간단한 리스트 테이블 (키-값 쌍)
+ *
+ * @example
+ * ```ts
+ * renderKeyValueTable([
+ *   { key: "Name", value: "Mandu" },
+ *   { key: "Version", value: "0.11.0" },
+ * ]);
+ * // ┌─────────┬─────────┐
+ * // │ Name    │ Mandu   │
+ * // │ Version │ 0.11.0  │
+ * // └─────────┴─────────┘
+ * ```
+ */
+export function renderKeyValueTable(
+  items: { key: string; value: string }[],
+  options: { border?: BorderStyle; maxWidth?: number } = {}
+): string {
+  return renderTable({
+    columns: [
+      { key: "key", header: "Key" },
+      { key: "value", header: "Value", flex: true },
+    ],
+    rows: items,
+    showHeader: false,
+    ...options,
+  });
+}

package/src/terminal/theme.ts

@@ -0,0 +1,142 @@
+/**
+ * DNA-009: Mandu CLI Theme System
+ *
+ * Chalk-based dynamic color theme with NO_COLOR/FORCE_COLOR support
+ * Inspired by OpenClaw's terminal/theme.ts
+ */
+
+import { MANDU_PALETTE } from "./palette.js";
+
+// Bun's native console supports colors, but we need a simple wrapper
+// for consistent theming across the CLI
+
+/**
+ * Check if rich output (colors) is supported
+ */
+function checkRichSupport(): boolean {
+  // NO_COLOR takes precedence (accessibility standard)
+  if (process.env.NO_COLOR) {
+    const forceColor = process.env.FORCE_COLOR?.trim();
+    if (forceColor !== "1" && forceColor !== "true") {
+      return false;
+    }
+  }
+
+  // Check TTY
+  if (!process.stdout.isTTY) {
+    return false;
+  }
+
+  // Check TERM
+  const term = process.env.TERM;
+  if (term === "dumb") {
+    return false;
+  }
+
+  return true;
+}
+
+const richSupported = checkRichSupport();
+
+/**
+ * ANSI escape code wrapper
+ */
+function ansi(code: string) {
+  return richSupported ? `\x1b[${code}m` : "";
+}
+
+/**
+ * Convert hex to ANSI 256 color (approximation)
+ */
+function hexToAnsi256(hex: string): number {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+
+  // Convert to 6x6x6 color cube
+  const ri = Math.round((r / 255) * 5);
+  const gi = Math.round((g / 255) * 5);
+  const bi = Math.round((b / 255) * 5);
+
+  return 16 + 36 * ri + 6 * gi + bi;
+}
+
+/**
+ * Create a color function from hex
+ */
+function hex(hexColor: string): (text: string) => string {
+  if (!richSupported) return (text) => text;
+
+  const colorCode = hexToAnsi256(hexColor);
+  return (text) => `\x1b[38;5;${colorCode}m${text}\x1b[0m`;
+}
+
+/**
+ * Create a bold color function
+ */
+function boldHex(hexColor: string): (text: string) => string {
+  if (!richSupported) return (text) => text;
+
+  const colorCode = hexToAnsi256(hexColor);
+  return (text) => `\x1b[1;38;5;${colorCode}m${text}\x1b[0m`;
+}
+
+/**
+ * Mandu CLI Theme
+ */
+export const theme = {
+  // Brand colors
+  accent: hex(MANDU_PALETTE.accent),
+  accentBright: hex(MANDU_PALETTE.accentBright),
+  accentDim: hex(MANDU_PALETTE.accentDim),
+
+  // Semantic colors
+  info: hex(MANDU_PALETTE.info),
+  success: hex(MANDU_PALETTE.success),
+  warn: hex(MANDU_PALETTE.warn),
+  error: hex(MANDU_PALETTE.error),
+
+  // Neutral
+  muted: hex(MANDU_PALETTE.muted),
+  dim: hex(MANDU_PALETTE.dim),
+
+  // Composite styles
+  heading: boldHex(MANDU_PALETTE.accent),
+  command: hex(MANDU_PALETTE.accentBright),
+  option: hex(MANDU_PALETTE.warn),
+  path: hex(MANDU_PALETTE.info),
+
+  // Basic styles
+  bold: richSupported ? (text: string) => `\x1b[1m${text}\x1b[0m` : (text: string) => text,
+  italic: richSupported ? (text: string) => `\x1b[3m${text}\x1b[0m` : (text: string) => text,
+  underline: richSupported ? (text: string) => `\x1b[4m${text}\x1b[0m` : (text: string) => text,
+
+  // Reset
+  reset: richSupported ? "\x1b[0m" : "",
+} as const;
+
+/**
+ * Check if rich output is available
+ */
+export function isRich(): boolean {
+  return richSupported;
+}
+
+/**
+ * Conditionally apply color based on rich mode
+ */
+export function colorize(
+  rich: boolean,
+  colorFn: (text: string) => string,
+  text: string
+): string {
+  return rich ? colorFn(text) : text;
+}
+
+/**
+ * Strip ANSI codes from string (for width calculation)
+ */
+export function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}