@mandujs/cli 0.9.46 → 0.11.0

package/src/terminal/output.ts

@@ -0,0 +1,295 @@
+/**
+ * DNA-014: Adaptive Output Format (JSON/Pretty/Plain)
+ *
+ * 환경에 따라 출력 형식을 자동 결정
+ * - TTY: Pretty (색상 + 포맷팅)
+ * - CI/pipe/agent: JSON (자동 처리/에이전트 친화)
+ * - --json 플래그: JSON
+ * - MANDU_OUTPUT 환경변수: 강제 지정
+ */
+
+import { theme, isRich, stripAnsi } from "./theme.js";
+
+/**
+ * 출력 모드
+ */
+export type OutputMode = "json" | "pretty" | "plain";
+
+/**
+ * 출력 옵션
+ */
+export interface OutputOptions {
+  /** JSON 출력 강제 */
+  json?: boolean;
+  /** Plain 텍스트 강제 */
+  plain?: boolean;
+}
+
+/**
+ * 출력 모드 결정
+ *
+ * 우선순위:
+ * 1. --json 플래그 → "json"
+ * 2. --plain 플래그 → "plain"
+ * 3. MANDU_OUTPUT 환경변수 → 지정된 값
+ * 4. 에이전트 환경 → "json"
+ * 5. !TTY (파이프), CI → "json"
+ * 6. 기본값 → "pretty"
+ */
+export function getOutputMode(opts: OutputOptions = {}): OutputMode {
+  // 플래그 우선
+  if (opts.json) return "json";
+  if (opts.plain) return "plain";
+
+  // 환경변수 체크
+  const envOutput = process.env.MANDU_OUTPUT?.toLowerCase();
+  if (envOutput === "json") return "json";
+  if (envOutput === "plain") return "plain";
+  if (envOutput === "pretty") return "pretty";
+  if (envOutput === "agent") return "json";
+
+  // 에이전트 환경이면 JSON
+  const agentSignals = [
+    "MANDU_AGENT",
+    "CODEX_AGENT",
+    "CODEX",
+    "CLAUDE_CODE",
+    "ANTHROPIC_CLAUDE_CODE",
+  ];
+  for (const key of agentSignals) {
+    const value = process.env[key];
+    if (value === "1" || value === "true") {
+      return "json";
+    }
+  }
+
+  // CI 환경이면 JSON
+  if (process.env.CI) return "json";
+
+  // TTY가 아니면 JSON
+  if (!process.stdout.isTTY) return "json";
+
+  return "pretty";
+}
+
+/**
+ * 출력 모드에 따른 포맷팅 컨텍스트
+ */
+export interface FormatContext {
+  mode: OutputMode;
+  rich: boolean;
+}
+
+/**
+ * 포맷팅 컨텍스트 생성
+ */
+export function createFormatContext(opts: OutputOptions = {}): FormatContext {
+  const mode = getOutputMode(opts);
+  return {
+    mode,
+    rich: mode === "pretty" && isRich(),
+  };
+}
+
+/**
+ * 데이터를 모드에 맞게 포맷팅
+ */
+export function formatOutput<T>(
+  data: T,
+  ctx: FormatContext,
+  formatters: {
+    json?: (data: T) => unknown;
+    pretty?: (data: T, rich: boolean) => string;
+    plain?: (data: T) => string;
+  }
+): string {
+  const { mode, rich } = ctx;
+
+  if (mode === "json") {
+    const jsonData = formatters.json ? formatters.json(data) : data;
+    return JSON.stringify(jsonData, null, 2);
+  }
+
+  if (mode === "plain") {
+    if (formatters.plain) {
+      return formatters.plain(data);
+    }
+    // Pretty 포맷터에서 ANSI 코드 제거
+    if (formatters.pretty) {
+      return stripAnsi(formatters.pretty(data, false));
+    }
+    return String(data);
+  }
+
+  // Pretty 모드
+  if (formatters.pretty) {
+    return formatters.pretty(data, rich);
+  }
+
+  return String(data);
+}
+
+/**
+ * 에러 출력 포맷팅
+ */
+export interface ErrorOutput {
+  type: "error";
+  message: string;
+  error?: string;
+  hint?: string;
+  code?: string;
+}
+
+/**
+ * 에러를 모드에 맞게 포맷팅
+ */
+export function formatError(
+  error: Error | string,
+  ctx: FormatContext,
+  options: {
+    hint?: string;
+    code?: string;
+  } = {}
+): string {
+  const { mode, rich } = ctx;
+  const message = error instanceof Error ? error.message : error;
+  const errorStack = error instanceof Error ? error.stack : undefined;
+
+  if (mode === "json") {
+    const output: ErrorOutput = {
+      type: "error",
+      message,
+      code: options.code,
+      hint: options.hint,
+    };
+    if (error instanceof Error && error.stack) {
+      output.error = error.stack;
+    }
+    return JSON.stringify(output, null, 2);
+  }
+
+  const lines: string[] = [];
+
+  // 에러 메시지
+  if (options.code) {
+    lines.push(
+      rich
+        ? `${theme.error("❌ Error")} [${theme.muted(options.code)}]`
+        : `Error [${options.code}]`
+    );
+  } else {
+    lines.push(rich ? theme.error("❌ Error") : "Error");
+  }
+  lines.push(rich ? `   ${message}` : `   ${message}`);
+
+  // 힌트
+  if (options.hint) {
+    lines.push("");
+    lines.push(rich ? theme.muted(`💡 ${options.hint}`) : `Hint: ${options.hint}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 성공 메시지 포맷팅
+ */
+export function formatSuccess(
+  message: string,
+  ctx: FormatContext,
+  details?: Record<string, unknown>
+): string {
+  const { mode, rich } = ctx;
+
+  if (mode === "json") {
+    return JSON.stringify({ type: "success", message, ...details }, null, 2);
+  }
+
+  if (rich) {
+    return `${theme.success("✓")} ${message}`;
+  }
+
+  return `[OK] ${message}`;
+}
+
+/**
+ * 경고 메시지 포맷팅
+ */
+export function formatWarning(
+  message: string,
+  ctx: FormatContext,
+  details?: Record<string, unknown>
+): string {
+  const { mode, rich } = ctx;
+
+  if (mode === "json") {
+    return JSON.stringify({ type: "warning", message, ...details }, null, 2);
+  }
+
+  if (rich) {
+    return `${theme.warn("⚠")} ${message}`;
+  }
+
+  return `[WARN] ${message}`;
+}
+
+/**
+ * 정보 메시지 포맷팅
+ */
+export function formatInfo(
+  message: string,
+  ctx: FormatContext,
+  details?: Record<string, unknown>
+): string {
+  const { mode, rich } = ctx;
+
+  if (mode === "json") {
+    return JSON.stringify({ type: "info", message, ...details }, null, 2);
+  }
+
+  if (rich) {
+    return `${theme.info("ℹ")} ${message}`;
+  }
+
+  return `[INFO] ${message}`;
+}
+
+/**
+ * 리스트 출력 포맷팅
+ */
+export function formatList<T>(
+  items: T[],
+  ctx: FormatContext,
+  options: {
+    title?: string;
+    itemFormatter?: (item: T, rich: boolean) => string;
+    emptyMessage?: string;
+  } = {}
+): string {
+  const { mode, rich } = ctx;
+  const { title, itemFormatter, emptyMessage = "No items" } = options;
+
+  if (mode === "json") {
+    return JSON.stringify({ title, items, count: items.length }, null, 2);
+  }
+
+  const lines: string[] = [];
+
+  if (title) {
+    lines.push(rich ? theme.heading(title) : title);
+    lines.push("");
+  }
+
+  if (items.length === 0) {
+    lines.push(rich ? theme.muted(emptyMessage) : emptyMessage);
+  } else {
+    for (const item of items) {
+      const formatted = itemFormatter
+        ? itemFormatter(item, rich)
+        : String(item);
+      lines.push(`  ${formatted}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/terminal/palette.ts

@@ -0,0 +1,30 @@
+/**
+ * DNA-009: Mandu Color Palette
+ *
+ * Inspired by OpenClaw's "Lobster Seam" palette
+ * @see https://github.com/dominikwilkowski/cfonts
+ */
+
+/**
+ * Mandu 브랜드 색상 팔레트
+ * 분홍색 기반의 따뜻한 톤
+ */
+export const MANDU_PALETTE = {
+  // 브랜드 컬러 (만두 분홍)
+  accent: "#E8B4B8",
+  accentBright: "#F5D0D3",
+  accentDim: "#C9A0A4",
+
+  // 시맨틱 컬러
+  info: "#87CEEB", // 스카이 블루
+  success: "#90EE90", // 라이트 그린
+  warn: "#FFD700", // 골드
+  error: "#FF6B6B", // 코랄 레드
+
+  // 뉴트럴
+  muted: "#9CA3AF", // 그레이
+  dim: "#6B7280", // 다크 그레이
+  text: "#F9FAFB", // 화이트
+} as const;
+
+export type ManduColor = keyof typeof MANDU_PALETTE;

package/src/terminal/progress.ts

@@ -0,0 +1,327 @@
+/**
+ * DNA-012: Multi-fallback Progress
+ *
+ * 다단계 폴백 프로그레스 시스템
+ * - TTY: 스피너 (ora) → 라인 → 로그
+ * - Non-TTY: 로그만
+ * - withProgress() 패턴으로 자동 정리
+ */
+
+import { theme } from "./theme.js";
+
+/**
+ * 프로그레스 옵션
+ */
+export interface ProgressOptions {
+  /** 레이블 */
+  label: string;
+  /** 전체 단계 수 (기본: 100) */
+  total?: number;
+  /** 출력 스트림 (기본: stderr) */
+  stream?: NodeJS.WriteStream;
+  /** 폴백 모드 */
+  fallback?: "spinner" | "line" | "log" | "none";
+  /** 성공 메시지 */
+  successMessage?: string;
+  /** 실패 메시지 */
+  failMessage?: string;
+}
+
+/**
+ * 프로그레스 리포터
+ */
+export interface ProgressReporter {
+  /** 레이블 변경 */
+  setLabel: (label: string) => void;
+  /** 퍼센트 설정 (0-100) */
+  setPercent: (percent: number) => void;
+  /** 진행 (delta 만큼 증가) */
+  tick: (delta?: number) => void;
+  /** 성공 완료 */
+  done: (message?: string) => void;
+  /** 실패 완료 */
+  fail: (message?: string) => void;
+  /** 현재 퍼센트 */
+  getPercent: () => number;
+}
+
+/**
+ * 스피너 문자
+ */
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * 간단한 스피너 구현 (ora 대체)
+ */
+function createSpinner(stream: NodeJS.WriteStream) {
+  let frameIndex = 0;
+  let intervalId: ReturnType<typeof setInterval> | null = null;
+  let text = "";
+  let isRunning = false;
+
+  const render = () => {
+    if (!isRunning) return;
+    const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+    stream.write(`\r${theme.accent(frame)} ${text}`);
+    frameIndex++;
+  };
+
+  return {
+    start: (initialText: string) => {
+      text = initialText;
+      isRunning = true;
+      render();
+      intervalId = setInterval(render, 80);
+    },
+    setText: (newText: string) => {
+      text = newText;
+    },
+    succeed: (successText: string) => {
+      isRunning = false;
+      if (intervalId) clearInterval(intervalId);
+      stream.write(`\r${theme.success("✓")} ${successText}\n`);
+    },
+    fail: (failText: string) => {
+      isRunning = false;
+      if (intervalId) clearInterval(intervalId);
+      stream.write(`\r${theme.error("✗")} ${failText}\n`);
+    },
+    stop: () => {
+      isRunning = false;
+      if (intervalId) clearInterval(intervalId);
+      stream.write("\r" + " ".repeat(text.length + 5) + "\r");
+    },
+  };
+}
+
+/**
+ * 프로그레스 바 렌더링
+ */
+function renderProgressBar(percent: number, width: number = 20): string {
+  const filled = Math.round((percent / 100) * width);
+  const empty = width - filled;
+  const bar = "█".repeat(filled) + "░".repeat(empty);
+  return `[${bar}]`;
+}
+
+/**
+ * CLI 프로그레스 생성
+ *
+ * @example
+ * ```ts
+ * const progress = createCliProgress({ label: "Building...", total: 4 });
+ *
+ * progress.setLabel("Scanning routes...");
+ * await scanRoutes();
+ * progress.tick();
+ *
+ * progress.setLabel("Bundling...");
+ * await bundle();
+ * progress.tick();
+ *
+ * progress.done("Build complete!");
+ * ```
+ */
+export function createCliProgress(options: ProgressOptions): ProgressReporter {
+  const {
+    label: initialLabel,
+    total = 100,
+    stream = process.stderr,
+    fallback = "spinner",
+    successMessage,
+    failMessage,
+  } = options;
+
+  const isTty = stream.isTTY;
+
+  let label = initialLabel;
+  let completed = 0;
+
+  // TTY: 스피너 사용 (stdout이 pipe여도 stderr TTY면 동작)
+  const spinner = isTty && fallback === "spinner" ? createSpinner(stream) : null;
+
+  if (spinner) {
+    spinner.start(label);
+  }
+
+  const getPercent = () => Math.round((completed / total) * 100);
+
+  const render = () => {
+    const percent = getPercent();
+    const text =
+      total > 1 ? `${label} ${renderProgressBar(percent)} ${percent}%` : label;
+
+    if (spinner) {
+      spinner.setText(text);
+    } else if (isTty && fallback === "line") {
+      stream.write(`\r${text}`);
+    }
+    // "log" 모드는 상태 변경 시마다 로그하지 않음
+  };
+
+  return {
+    setLabel: (next: string) => {
+      label = next;
+      render();
+    },
+
+    setPercent: (percent: number) => {
+      completed = (Math.max(0, Math.min(100, percent)) / 100) * total;
+      render();
+    },
+
+    tick: (delta = 1) => {
+      completed = Math.min(total, completed + delta);
+      render();
+    },
+
+    getPercent,
+
+    done: (message?: string) => {
+      const finalMessage =
+        message ?? successMessage ?? `${initialLabel} completed`;
+
+      if (spinner) {
+        spinner.succeed(finalMessage);
+      } else if (isTty) {
+        stream.write(`\r${theme.success("✓")} ${finalMessage}\n`);
+      } else if (fallback !== "none") {
+        stream.write(`[OK] ${finalMessage}\n`);
+      }
+    },
+
+    fail: (message?: string) => {
+      const finalMessage =
+        message ?? failMessage ?? `${initialLabel} failed`;
+
+      if (spinner) {
+        spinner.fail(finalMessage);
+      } else if (isTty) {
+        stream.write(`\r${theme.error("✗")} ${finalMessage}\n`);
+      } else if (fallback !== "none") {
+        stream.write(`[FAIL] ${finalMessage}\n`);
+      }
+    },
+  };
+}
+
+/**
+ * 프로그레스 컨텍스트 패턴
+ *
+ * 작업 완료 후 자동으로 프로그레스 정리
+ *
+ * @example
+ * ```ts
+ * const result = await withProgress(
+ *   { label: "Building...", total: 4 },
+ *   async (progress) => {
+ *     progress.setLabel("Step 1");
+ *     await step1();
+ *     progress.tick();
+ *
+ *     progress.setLabel("Step 2");
+ *     await step2();
+ *     progress.tick();
+ *
+ *     return { success: true };
+ *   }
+ * );
+ * ```
+ */
+export async function withProgress<T>(
+  options: ProgressOptions,
+  work: (progress: ProgressReporter) => Promise<T>
+): Promise<T> {
+  const progress = createCliProgress(options);
+
+  try {
+    const result = await work(progress);
+    progress.done();
+    return result;
+  } catch (error) {
+    progress.fail(
+      error instanceof Error ? error.message : String(error)
+    );
+    throw error;
+  }
+}
+
+/**
+ * 단순 스피너 (진행률 없음)
+ *
+ * @example
+ * ```ts
+ * const stop = startSpinner("Loading...");
+ * await loadData();
+ * stop("Loaded!");
+ * ```
+ */
+export function startSpinner(
+  label: string,
+  stream: NodeJS.WriteStream = process.stderr
+): (successMessage?: string) => void {
+  const isTty = stream.isTTY;
+
+  if (!isTty) {
+    stream.write(`${label}\n`);
+    return (msg) => {
+      if (msg) stream.write(`${msg}\n`);
+    };
+  }
+
+  const spinner = createSpinner(stream);
+  spinner.start(label);
+
+  return (successMessage?: string) => {
+    if (successMessage) {
+      spinner.succeed(successMessage);
+    } else {
+      spinner.stop();
+    }
+  };
+}
+
+/**
+ * 다중 단계 프로그레스
+ *
+ * @example
+ * ```ts
+ * await runSteps([
+ *   { label: "Installing dependencies", fn: installDeps },
+ *   { label: "Building", fn: build },
+ *   { label: "Testing", fn: test },
+ * ]);
+ * ```
+ */
+export async function runSteps<T>(
+  steps: Array<{
+    label: string;
+    fn: () => T | Promise<T>;
+  }>,
+  options: Omit<ProgressOptions, "label" | "total"> = {}
+): Promise<T[]> {
+  const results: T[] = [];
+  const total = steps.length;
+  let current = 0;
+
+  const progress = createCliProgress({
+    ...options,
+    label: steps[0]?.label ?? "Processing...",
+    total,
+  });
+
+  try {
+    for (const step of steps) {
+      progress.setLabel(step.label);
+      const result = await step.fn();
+      results.push(result);
+      current++;
+      progress.tick();
+    }
+    progress.done();
+    return results;
+  } catch (error) {
+    progress.fail();
+    throw error;
+  }
+}