@task-mcp/shared 1.0.8 → 1.0.10

package/src/utils/terminal-ui.ts

@@ -0,0 +1,706 @@
+/**
+ * Terminal UI utilities for task-mcp
+ * Zero-dependency ANSI colors, box drawing, and layout helpers
+ * Supports CJK (Korean, Chinese, Japanese) character width calculation
+ */
+
+// =============================================================================
+// ANSI Escape Codes
+// =============================================================================
+
+const ESC = "\x1b[";
+const RESET = `${ESC}0m`;
+
+// Foreground color codes
+const FG = {
+  black: 30,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  blue: 34,
+  magenta: 35,
+  cyan: 36,
+  white: 37,
+  gray: 90,
+  brightRed: 91,
+  brightGreen: 92,
+  brightYellow: 93,
+  brightBlue: 94,
+  brightMagenta: 95,
+  brightCyan: 96,
+  brightWhite: 97,
+} as const;
+
+// Style codes
+const STYLE = {
+  bold: 1,
+  dim: 2,
+  italic: 3,
+  underline: 4,
+  inverse: 7,
+  strikethrough: 9,
+} as const;
+
+type ColorName = keyof typeof FG;
+type StyleName = keyof typeof STYLE;
+
+/**
+ * Apply color to text
+ */
+export function color(text: string, colorName: ColorName): string {
+  return `${ESC}${FG[colorName]}m${text}${RESET}`;
+}
+
+/**
+ * Apply style to text
+ */
+export function style(text: string, styleName: StyleName): string {
+  return `${ESC}${STYLE[styleName]}m${text}${RESET}`;
+}
+
+/**
+ * Combine color and style
+ */
+export function styled(text: string, colorName: ColorName, styleName?: StyleName): string {
+  if (styleName) {
+    return `${ESC}${STYLE[styleName]};${FG[colorName]}m${text}${RESET}`;
+  }
+  return color(text, colorName);
+}
+
+// =============================================================================
+// Color Helper Functions
+// =============================================================================
+
+export const c = {
+  // Basic styles
+  reset: (s: string) => `${s}${RESET}`,
+  bold: (s: string) => style(s, "bold"),
+  dim: (s: string) => style(s, "dim"),
+  italic: (s: string) => style(s, "italic"),
+  underline: (s: string) => style(s, "underline"),
+
+  // Colors
+  black: (s: string) => color(s, "black"),
+  red: (s: string) => color(s, "red"),
+  green: (s: string) => color(s, "green"),
+  yellow: (s: string) => color(s, "yellow"),
+  blue: (s: string) => color(s, "blue"),
+  magenta: (s: string) => color(s, "magenta"),
+  cyan: (s: string) => color(s, "cyan"),
+  white: (s: string) => color(s, "white"),
+  gray: (s: string) => color(s, "gray"),
+
+  // Bright colors
+  brightRed: (s: string) => color(s, "brightRed"),
+  brightGreen: (s: string) => color(s, "brightGreen"),
+  brightYellow: (s: string) => color(s, "brightYellow"),
+  brightBlue: (s: string) => color(s, "brightBlue"),
+  brightMagenta: (s: string) => color(s, "brightMagenta"),
+  brightCyan: (s: string) => color(s, "brightCyan"),
+  brightWhite: (s: string) => color(s, "brightWhite"),
+
+  // Semantic colors
+  success: (s: string) => color(s, "green"),
+  error: (s: string) => color(s, "red"),
+  warning: (s: string) => color(s, "yellow"),
+  info: (s: string) => color(s, "cyan"),
+  muted: (s: string) => color(s, "gray"),
+  highlight: (s: string) => color(s, "brightCyan"),
+  label: (s: string) => styled(s, "cyan", "bold"),
+  title: (s: string) => styled(s, "brightWhite", "bold"),
+  value: (s: string) => color(s, "white"),
+};
+
+// =============================================================================
+// Box Drawing Characters
+// =============================================================================
+
+export const BOX = {
+  // Single line
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│",
+  teeRight: "├",
+  teeLeft: "┤",
+  teeDown: "┬",
+  teeUp: "┴",
+  cross: "┼",
+
+  // Double line
+  dblTopLeft: "╔",
+  dblTopRight: "╗",
+  dblBottomLeft: "╚",
+  dblBottomRight: "╝",
+  dblHorizontal: "═",
+  dblVertical: "║",
+
+  // Rounded corners
+  rTopLeft: "╭",
+  rTopRight: "╮",
+  rBottomLeft: "╰",
+  rBottomRight: "╯",
+} as const;
+
+// =============================================================================
+// String Utilities
+// =============================================================================
+
+/**
+ * Strip all ANSI escape codes from string
+ */
+export function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * Check if a character is full-width (CJK, Korean, emoji, etc.)
+ * Full-width characters take 2 columns in terminal
+ */
+function isFullWidth(char: string): boolean {
+  const code = char.codePointAt(0);
+  if (code === undefined) return false;
+
+  return (
+    (code >= 0x1100 && code <= 0x115f) || // Hangul Jamo
+    (code >= 0x2e80 && code <= 0x9fff) || // CJK
+    (code >= 0xac00 && code <= 0xd7af) || // Hangul Syllables
+    (code >= 0xf900 && code <= 0xfaff) || // CJK Compatibility
+    (code >= 0xfe10 && code <= 0xfe1f) || // Vertical forms
+    (code >= 0xfe30 && code <= 0xfe6f) || // CJK Compatibility Forms
+    (code >= 0xff00 && code <= 0xff60) || // Fullwidth Forms
+    (code >= 0xffe0 && code <= 0xffe6) || // Fullwidth symbols
+    (code >= 0x1f300 && code <= 0x1f9ff) || // Emoji
+    (code >= 0x2600 && code <= 0x26ff) || // Misc Symbols
+    (code >= 0x2700 && code <= 0x27bf) || // Dingbats
+    (code >= 0x20000 && code <= 0x2ffff) // CJK Extension B+
+  );
+}
+
+/**
+ * Get display width of string (excluding ANSI codes, CJK = 2 columns)
+ */
+export function displayWidth(str: string): number {
+  const stripped = stripAnsi(str);
+  let width = 0;
+  for (const char of stripped) {
+    width += isFullWidth(char) ? 2 : 1;
+  }
+  return width;
+}
+
+// Alias for compatibility
+export const visibleLength = displayWidth;
+
+/**
+ * Pad string to width (accounting for display width)
+ */
+export function pad(str: string, width: number, align: "left" | "right" | "center" = "left"): string {
+  const len = displayWidth(str);
+  const diff = width - len;
+  if (diff <= 0) return str;
+
+  switch (align) {
+    case "right":
+      return " ".repeat(diff) + str;
+    case "center": {
+      const left = Math.floor(diff / 2);
+      return " ".repeat(left) + str + " ".repeat(diff - left);
+    }
+    default:
+      return str + " ".repeat(diff);
+  }
+}
+
+// Aliases for compatibility
+export const padEnd = (str: string, width: number) => pad(str, width, "left");
+export const padStart = (str: string, width: number) => pad(str, width, "right");
+export const center = (str: string, width: number) => pad(str, width, "center");
+
+/**
+ * Truncate string to max display width
+ */
+export function truncateStr(str: string, maxLen: number, suffix = "..."): string {
+  const stripped = stripAnsi(str);
+  if (displayWidth(stripped) <= maxLen) return str;
+
+  const suffixWidth = displayWidth(suffix);
+  let width = 0;
+  let result = "";
+
+  for (const char of stripped) {
+    const charWidth = isFullWidth(char) ? 2 : 1;
+    if (width + charWidth > maxLen - suffixWidth) break;
+    result += char;
+    width += charWidth;
+  }
+
+  return result + suffix;
+}
+
+/**
+ * Create a horizontal line
+ */
+export function hline(width: number, char: string = BOX.horizontal): string {
+  return char.repeat(width);
+}
+
+// =============================================================================
+// Progress Bar
+// =============================================================================
+
+export interface ProgressBarOptions {
+  width?: number;
+  filled?: string;
+  empty?: string;
+  showPercent?: boolean;
+  filledColor?: ColorName;
+  emptyColor?: ColorName;
+}
+
+export function progressBar(
+  current: number,
+  total: number,
+  options: ProgressBarOptions = {}
+): string {
+  const {
+    width = 20,
+    filled = "█",
+    empty = "░",
+    showPercent = true,
+    filledColor = "green",
+    emptyColor = "gray",
+  } = options;
+
+  const percent = total > 0 ? Math.round((current / total) * 100) : 0;
+  const filledCount = Math.round((percent / 100) * width);
+  const emptyCount = width - filledCount;
+
+  const bar = color(filled.repeat(filledCount), filledColor) + color(empty.repeat(emptyCount), emptyColor);
+
+  return showPercent ? `${bar} ${percent}%` : bar;
+}
+
+// =============================================================================
+// Box Drawing
+// =============================================================================
+
+export interface BoxOptions {
+  title?: string;
+  width?: number;
+  padding?: number;
+  borderColor?: ColorName;
+  rounded?: boolean;
+}
+
+/**
+ * Create a box around content (string input, string output)
+ */
+export function box(content: string, options: BoxOptions = {}): string {
+  const { padding = 1, borderColor = "cyan", title, rounded = true } = options;
+
+  const lines = content.split("\n");
+  const maxLen = Math.max(...lines.map(l => displayWidth(stripAnsi(l))), title ? title.length + 2 : 0);
+  const innerWidth = options.width ? options.width - 2 - padding * 2 : maxLen + padding * 2;
+
+  const tl = rounded ? BOX.rTopLeft : BOX.topLeft;
+  const tr = rounded ? BOX.rTopRight : BOX.topRight;
+  const bl = rounded ? BOX.rBottomLeft : BOX.bottomLeft;
+  const br = rounded ? BOX.rBottomRight : BOX.bottomRight;
+  const h = BOX.horizontal;
+  const v = BOX.vertical;
+
+  const applyBorder = (s: string) => color(s, borderColor);
+
+  // Top border with optional title
+  let top: string;
+  if (title) {
+    const titlePart = ` ${title} `;
+    const remaining = innerWidth - titlePart.length;
+    const leftPad = Math.floor(remaining / 2);
+    const rightPad = remaining - leftPad;
+    top = applyBorder(tl + h.repeat(leftPad)) + c.bold(titlePart) + applyBorder(h.repeat(rightPad) + tr);
+  } else {
+    top = applyBorder(tl + h.repeat(innerWidth) + tr);
+  }
+
+  // Padding lines
+  const padLine = applyBorder(v) + " ".repeat(innerWidth) + applyBorder(v);
+  const paddingLines = Array(padding).fill(padLine);
+
+  // Content lines
+  const contentLines = lines.map(line => {
+    const lineWidth = displayWidth(stripAnsi(line));
+    const padRight = innerWidth - lineWidth - padding;
+    return applyBorder(v) + " ".repeat(padding) + line + " ".repeat(Math.max(0, padRight)) + applyBorder(v);
+  });
+
+  // Bottom border
+  const bottom = applyBorder(bl + h.repeat(innerWidth) + br);
+
+  return [top, ...paddingLines, ...contentLines, ...paddingLines, bottom].join("\n");
+}
+
+/**
+ * Draw a box around content (array input, array output)
+ * For MCP server compatibility
+ */
+export function drawBox(lines: string[], options: BoxOptions = {}): string[] {
+  const { title, padding = 1, borderColor = "gray" } = options;
+
+  let maxContentWidth = 0;
+  for (const line of lines) {
+    maxContentWidth = Math.max(maxContentWidth, displayWidth(line));
+  }
+
+  const innerWidth = options.width ? options.width - 2 - padding * 2 : maxContentWidth;
+  const boxWidth = innerWidth + 2 + padding * 2;
+
+  const result: string[] = [];
+  const padStr = " ".repeat(padding);
+
+  const applyBorder = (s: string) => color(s, borderColor);
+
+  // Top border with optional title
+  if (title) {
+    const titleStr = ` ${title} `;
+    const remainingWidth = boxWidth - 2 - displayWidth(titleStr);
+    const leftBorder = Math.floor(remainingWidth / 2);
+    const rightBorder = remainingWidth - leftBorder;
+    result.push(
+      applyBorder(BOX.topLeft) +
+      applyBorder(BOX.horizontal.repeat(leftBorder)) +
+      c.label(titleStr) +
+      applyBorder(BOX.horizontal.repeat(rightBorder)) +
+      applyBorder(BOX.topRight)
+    );
+  } else {
+    result.push(
+      applyBorder(BOX.topLeft) +
+      applyBorder(BOX.horizontal.repeat(boxWidth - 2)) +
+      applyBorder(BOX.topRight)
+    );
+  }
+
+  // Content lines
+  for (const line of lines) {
+    result.push(
+      applyBorder(BOX.vertical) +
+      padStr +
+      padEnd(line, innerWidth) +
+      padStr +
+      applyBorder(BOX.vertical)
+    );
+  }
+
+  // Bottom border
+  result.push(
+    applyBorder(BOX.bottomLeft) +
+    applyBorder(BOX.horizontal.repeat(boxWidth - 2)) +
+    applyBorder(BOX.bottomRight)
+  );
+
+  return result;
+}
+
+// =============================================================================
+// Side-by-Side Layout
+// =============================================================================
+
+/**
+ * Place multiple boxes side by side (string input, string output)
+ */
+export function sideBySide(boxes: string[], gap: number = 2): string {
+  const boxLines = boxes.map(b => b.split("\n"));
+  const maxHeight = Math.max(...boxLines.map(lines => lines.length));
+  const boxWidths = boxLines.map(lines => Math.max(...lines.map(l => displayWidth(l))));
+
+  // Pad each box to max height
+  const paddedBoxLines = boxLines.map((lines, i) => {
+    const width = boxWidths[i] ?? 0;
+    while (lines.length < maxHeight) {
+      lines.push(" ".repeat(width));
+    }
+    return lines.map(line => {
+      const lineWidth = displayWidth(line);
+      if (lineWidth < width) {
+        return line + " ".repeat(width - lineWidth);
+      }
+      return line;
+    });
+  });
+
+  // Combine lines horizontally
+  const result: string[] = [];
+  const gapStr = " ".repeat(gap);
+
+  for (let i = 0; i < maxHeight; i++) {
+    const lineParts = paddedBoxLines.map(lines => lines[i] ?? "");
+    result.push(lineParts.join(gapStr));
+  }
+
+  return result.join("\n");
+}
+
+/**
+ * Merge two boxes side by side (array input, array output)
+ * For MCP server compatibility
+ */
+export function sideBySideArrays(
+  leftLines: string[],
+  rightLines: string[],
+  gap = 2
+): string[] {
+  const leftWidth = leftLines.length > 0
+    ? Math.max(...leftLines.map(displayWidth))
+    : 0;
+
+  const maxLines = Math.max(leftLines.length, rightLines.length);
+  const result: string[] = [];
+  const gapStr = " ".repeat(gap);
+  const emptyLeft = " ".repeat(leftWidth);
+
+  for (let i = 0; i < maxLines; i++) {
+    const left = leftLines[i];
+    const right = rightLines[i] ?? "";
+
+    if (left !== undefined) {
+      result.push(padEnd(left, leftWidth) + gapStr + right);
+    } else {
+      result.push(emptyLeft + gapStr + right);
+    }
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Table Rendering
+// =============================================================================
+
+export interface TableColumn {
+  key: string;
+  header: string;
+  width?: number;
+  align?: "left" | "center" | "right";
+  format?: (value: unknown, row?: Record<string, unknown>) => string;
+}
+
+export function table<T extends Record<string, unknown>>(
+  data: T[],
+  columns: TableColumn[],
+  options: {
+    headerColor?: ColorName;
+    borderColor?: ColorName;
+  } = {}
+): string {
+  const { headerColor = "cyan", borderColor = "gray" } = options;
+
+  // Calculate column widths
+  const widths = columns.map(col => {
+    const headerWidth = displayWidth(col.header);
+    const maxDataWidth = Math.max(
+      ...data.map(row => {
+        const val = col.format ? col.format(row[col.key], row) : String(row[col.key] ?? "");
+        return displayWidth(val);
+      }),
+      0
+    );
+    return col.width ?? Math.max(headerWidth, maxDataWidth);
+  });
+
+  const border = color(BOX.vertical, borderColor);
+  const hBorder = color(BOX.horizontal, borderColor);
+
+  // Header row
+  const headerRow = columns
+    .map((col, i) => color(pad(col.header, widths[i] ?? 0, col.align), headerColor))
+    .join(` ${border} `);
+
+  // Separator
+  const separator = widths.map(w => hBorder.repeat(w)).join(color(`─${BOX.cross}─`, borderColor));
+
+  // Data rows
+  const dataRows = data.map(row =>
+    columns
+      .map((col, i) => {
+        const w = widths[i] ?? 0;
+        const val = col.format ? col.format(row[col.key], row) : String(row[col.key] ?? "");
+        return pad(truncateStr(val, w), w, col.align);
+      })
+      .join(` ${border} `)
+  );
+
+  return [headerRow, separator, ...dataRows].join("\n");
+}
+
+/**
+ * Render table with full borders (array output)
+ * For MCP server compatibility
+ */
+export function renderTable(
+  columns: TableColumn[],
+  rows: Record<string, unknown>[]
+): string[] {
+  const colWidths: number[] = columns.map((col) => {
+    const headerWidth = col.header.length;
+    const maxValueWidth = Math.max(
+      ...rows.map((row) => String(row[col.key] ?? "").length)
+    );
+    return col.width ?? Math.max(headerWidth, maxValueWidth);
+  });
+
+  const result: string[] = [];
+
+  // Header row
+  const headerCells = columns.map((col, i) =>
+    c.label(center(col.header, colWidths[i] ?? 0))
+  );
+  result.push(c.muted(BOX.vertical) + headerCells.join(c.muted(BOX.vertical)) + c.muted(BOX.vertical));
+
+  // Separator
+  const separator = columns.map((_, i) => BOX.horizontal.repeat(colWidths[i] ?? 0));
+  result.push(
+    c.muted(BOX.teeRight) +
+    c.muted(separator.join(BOX.cross)) +
+    c.muted(BOX.teeLeft)
+  );
+
+  // Data rows
+  for (const row of rows) {
+    const cells = columns.map((col, i) => {
+      const w = colWidths[i] ?? 0;
+      const value = String(row[col.key] ?? "");
+      const colorFn = col.format;
+      const colored = colorFn ? colorFn(value, row) : value;
+
+      switch (col.align) {
+        case "center":
+          return center(String(colored), w);
+        case "right":
+          return padStart(String(colored), w);
+        default:
+          return padEnd(String(colored), w);
+      }
+    });
+    result.push(c.muted(BOX.vertical) + cells.join(c.muted(BOX.vertical)) + c.muted(BOX.vertical));
+  }
+
+  // Top border
+  const topBorder =
+    c.muted(BOX.topLeft) +
+    c.muted(colWidths.map((w) => BOX.horizontal.repeat(w)).join(BOX.teeDown)) +
+    c.muted(BOX.topRight);
+
+  // Bottom border
+  const bottomBorder =
+    c.muted(BOX.bottomLeft) +
+    c.muted(colWidths.map((w) => BOX.horizontal.repeat(w)).join(BOX.teeUp)) +
+    c.muted(BOX.bottomRight);
+
+  return [topBorder, ...result, bottomBorder];
+}
+
+// =============================================================================
+// Status & Priority Formatters
+// =============================================================================
+
+export const statusColors: Record<string, (s: string) => string> = {
+  pending: c.yellow,
+  in_progress: c.cyan,
+  completed: c.green,
+  blocked: c.red,
+  deferred: c.muted,
+  cancelled: c.muted,
+};
+
+export const statusIcons: Record<string, string> = {
+  pending: "○",
+  in_progress: "◐",
+  completed: "●",
+  blocked: "⊘",
+  deferred: "◇",
+  cancelled: "✕",
+};
+
+export const icons = {
+  // Status
+  pending: c.yellow("○"),
+  in_progress: c.blue("◐"),
+  completed: c.green("✓"),
+  blocked: c.red("✗"),
+  cancelled: c.gray("⊘"),
+
+  // Priority
+  critical: c.red("!!!"),
+  high: c.yellow("!!"),
+  medium: c.blue("!"),
+  low: c.gray("·"),
+
+  // Misc
+  arrow: c.cyan("→"),
+  bullet: c.gray("•"),
+  check: c.green("✓"),
+  cross: c.red("✗"),
+  warning: c.yellow("⚠"),
+  info: c.cyan("ℹ"),
+};
+
+export function formatStatus(status: string): string {
+  const icon = statusIcons[status] ?? "?";
+  const colorFn = statusColors[status] ?? c.white;
+  return colorFn(`${icon} ${status}`);
+}
+
+export const priorityColors: Record<string, (s: string) => string> = {
+  critical: c.brightRed,
+  high: c.yellow,
+  medium: c.cyan,
+  low: c.green,
+};
+
+export function formatPriority(priority: string): string {
+  const colorFn = priorityColors[priority] ?? c.white;
+  return colorFn(priority);
+}
+
+export function formatDependencies(deps: string[]): string {
+  if (deps.length === 0) return c.muted("None");
+  return c.magenta(deps.join(", "));
+}
+
+// =============================================================================
+// Banner
+// =============================================================================
+
+/**
+ * ASCII art text banner
+ */
+export function banner(text: string): string {
+  const letters: Record<string, string[]> = {
+    T: ["████", " ██ ", " ██ ", " ██ ", " ██ "],
+    A: [" ██ ", "████", "██ █", "████", "██ █"],
+    S: ["████", "██  ", "████", "  ██", "████"],
+    K: ["██ █", "███ ", "██  ", "███ ", "██ █"],
+    M: ["█   █", "██ ██", "█ █ █", "█   █", "█   █"],
+    C: ["████", "██  ", "██  ", "██  ", "████"],
+    P: ["████", "██ █", "████", "██  ", "██  "],
+    " ": ["  ", "  ", "  ", "  ", "  "],
+  };
+
+  const chars = text.toUpperCase().split("");
+  const lines: string[] = ["", "", "", "", ""];
+
+  const defaultLetter = ["  ", "  ", "  ", "  ", "  "];
+  for (const char of chars) {
+    const letterLines = letters[char] ?? defaultLetter;
+    for (let i = 0; i < 5; i++) {
+      lines[i] += (letterLines[i] ?? "") + " ";
+    }
+  }
+
+  return lines.map(l => c.cyan(l)).join("\n");
+}