@mandujs/cli 0.10.0 → 0.12.0

package/src/terminal/help.ts

@@ -0,0 +1,306 @@
+/**
+ * DNA-015: Semantic Help System
+ *
+ * 시맨틱 도움말 포맷팅
+ * - 예제 기반 도움말
+ * - 테마 적용 출력
+ * - 섹션별 구조화
+ */
+
+import { theme, colorize, isRich } from "./theme.js";
+
+/**
+ * 도움말 예제 타입
+ * [명령어, 설명]
+ */
+export type HelpExample = readonly [command: string, description: string];
+
+/**
+ * 명령어 옵션 정의
+ */
+export interface HelpOption {
+  /** 플래그 (예: "--port", "-p, --port") */
+  flags: string;
+  /** 설명 */
+  description: string;
+  /** 기본값 */
+  default?: string;
+  /** 필수 여부 */
+  required?: boolean;
+}
+
+/**
+ * 서브커맨드 정의
+ */
+export interface HelpSubcommand {
+  /** 서브커맨드 이름 */
+  name: string;
+  /** 설명 */
+  description: string;
+  /** 별칭 */
+  aliases?: string[];
+}
+
+/**
+ * 도움말 섹션
+ */
+export interface HelpSection {
+  /** 섹션 제목 */
+  title: string;
+  /** 섹션 내용 */
+  content: string;
+}
+
+/**
+ * 도움말 정의
+ */
+export interface HelpDefinition {
+  /** 명령어 이름 */
+  name: string;
+  /** 짧은 설명 */
+  description: string;
+  /** 사용법 */
+  usage?: string;
+  /** 옵션 목록 */
+  options?: HelpOption[];
+  /** 서브커맨드 목록 */
+  subcommands?: HelpSubcommand[];
+  /** 예제 목록 */
+  examples?: HelpExample[];
+  /** 추가 섹션 */
+  sections?: HelpSection[];
+  /** 참조 링크 */
+  seeAlso?: string[];
+}
+
+/**
+ * 예제 포맷팅
+ *
+ * @example
+ * ```ts
+ * formatHelpExample("mandu dev", "Start development server");
+ * // "  mandu dev"
+ * // "    Start development server"
+ * ```
+ */
+export function formatHelpExample(command: string, description: string): string {
+  const rich = isRich();
+  const cmd = rich ? theme.accent(command) : command;
+  const desc = rich ? theme.muted(description) : description;
+
+  return `  ${cmd}\n    ${desc}`;
+}
+
+/**
+ * 예제 그룹 포맷팅
+ *
+ * @example
+ * ```ts
+ * formatHelpExampleGroup("Examples:", [
+ *   ["mandu dev", "Start development server"],
+ *   ["mandu build --prod", "Build for production"],
+ * ]);
+ * ```
+ */
+export function formatHelpExampleGroup(
+  label: string,
+  examples: ReadonlyArray<HelpExample>
+): string {
+  const rich = isRich();
+  const heading = rich ? theme.heading(label) : label;
+  const formatted = examples
+    .map(([cmd, desc]) => formatHelpExample(cmd, desc))
+    .join("\n\n");
+
+  return `${heading}\n${formatted}`;
+}
+
+/**
+ * 옵션 포맷팅
+ */
+export function formatHelpOption(option: HelpOption): string {
+  const rich = isRich();
+  const flags = rich ? theme.option(option.flags) : option.flags;
+
+  let desc = option.description;
+  if (option.default) {
+    desc += rich
+      ? ` ${theme.muted(`(default: ${option.default})`)}`
+      : ` (default: ${option.default})`;
+  }
+  if (option.required) {
+    desc += rich ? ` ${theme.warn("[required]")}` : " [required]";
+  }
+
+  // 플래그와 설명 정렬
+  const padding = Math.max(0, 24 - option.flags.length);
+  return `  ${flags}${" ".repeat(padding)}${desc}`;
+}
+
+/**
+ * 서브커맨드 포맷팅
+ */
+export function formatHelpSubcommand(subcommand: HelpSubcommand): string {
+  const rich = isRich();
+  let name = subcommand.name;
+
+  if (subcommand.aliases && subcommand.aliases.length > 0) {
+    name += `, ${subcommand.aliases.join(", ")}`;
+  }
+
+  const cmd = rich ? theme.command(name) : name;
+  const desc = rich ? subcommand.description : subcommand.description;
+
+  const padding = Math.max(0, 20 - name.length);
+  return `  ${cmd}${" ".repeat(padding)}${desc}`;
+}
+
+/**
+ * 섹션 제목 포맷팅
+ */
+export function formatSectionTitle(title: string): string {
+  const rich = isRich();
+  return rich ? theme.heading(title) : title;
+}
+
+/**
+ * 전체 도움말 렌더링
+ */
+export function renderHelp(def: HelpDefinition): string {
+  const lines: string[] = [];
+  const rich = isRich();
+
+  // 헤더
+  const name = rich ? theme.accent(def.name) : def.name;
+  lines.push(`${name} - ${def.description}`);
+  lines.push("");
+
+  // 사용법
+  if (def.usage) {
+    lines.push(formatSectionTitle("Usage:"));
+    lines.push(`  ${def.usage}`);
+    lines.push("");
+  }
+
+  // 서브커맨드
+  if (def.subcommands && def.subcommands.length > 0) {
+    lines.push(formatSectionTitle("Commands:"));
+    for (const sub of def.subcommands) {
+      lines.push(formatHelpSubcommand(sub));
+    }
+    lines.push("");
+  }
+
+  // 옵션
+  if (def.options && def.options.length > 0) {
+    lines.push(formatSectionTitle("Options:"));
+    for (const opt of def.options) {
+      lines.push(formatHelpOption(opt));
+    }
+    lines.push("");
+  }
+
+  // 예제
+  if (def.examples && def.examples.length > 0) {
+    lines.push(formatHelpExampleGroup("Examples:", def.examples));
+    lines.push("");
+  }
+
+  // 추가 섹션
+  if (def.sections) {
+    for (const section of def.sections) {
+      lines.push(formatSectionTitle(section.title));
+      lines.push(section.content);
+      lines.push("");
+    }
+  }
+
+  // 참조
+  if (def.seeAlso && def.seeAlso.length > 0) {
+    lines.push(formatSectionTitle("See Also:"));
+    for (const ref of def.seeAlso) {
+      lines.push(`  ${ref}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Mandu CLI 기본 도움말 정의
+ */
+export const MANDU_HELP: HelpDefinition = {
+  name: "mandu",
+  description: "Agent-Native Web Framework",
+  usage: "mandu <command> [options]",
+  subcommands: [
+    { name: "init", description: "Create a new Mandu project" },
+    { name: "dev", description: "Start development server with HMR" },
+    { name: "build", description: "Build for production" },
+    { name: "start", description: "Start production server" },
+    { name: "guard", description: "Check architecture violations", aliases: ["g"] },
+    { name: "routes", description: "Manage file-system routes" },
+    { name: "openapi", description: "Generate OpenAPI spec" },
+    { name: "brain", description: "Setup local AI with Ollama" },
+  ],
+  options: [
+    { flags: "--version, -v", description: "Show version number" },
+    { flags: "--help, -h", description: "Show help" },
+    { flags: "--json", description: "Output in JSON format" },
+    { flags: "--no-color", description: "Disable colored output" },
+    { flags: "--verbose", description: "Enable verbose logging" },
+  ],
+  examples: [
+    ["mandu init my-app", "Create a new project"],
+    ["mandu dev --port 4000", "Start dev server on port 4000"],
+    ["mandu build --prod", "Build for production"],
+    ["mandu guard --fix", "Check and auto-fix violations"],
+  ],
+  sections: [
+    {
+      title: "Environment Variables:",
+      content: `  MANDU_OUTPUT    Output format (json|pretty|plain)
+  NO_COLOR        Disable colors (set to any value)
+  FORCE_COLOR     Force colors even in non-TTY`,
+    },
+  ],
+  seeAlso: [
+    "https://mandujs.com/docs",
+    "https://github.com/mandujs/mandu",
+  ],
+};
+
+/**
+ * 명령어별 도움말 렌더링
+ */
+export function renderCommandHelp(
+  commandName: string,
+  def: Partial<HelpDefinition>
+): string {
+  return renderHelp({
+    name: `mandu ${commandName}`,
+    description: def.description ?? "",
+    ...def,
+  });
+}
+
+/**
+ * 간단한 사용법 힌트
+ */
+export function formatUsageHint(command: string, hint: string): string {
+  const rich = isRich();
+  const cmd = rich ? theme.accent(command) : command;
+  const tip = rich ? theme.muted(hint) : hint;
+  return `${tip}\n  ${cmd}`;
+}
+
+/**
+ * 에러 후 도움말 힌트
+ */
+export function formatErrorHint(errorMessage: string, helpCommand: string): string {
+  const rich = isRich();
+  const error = rich ? theme.error(errorMessage) : errorMessage;
+  const help = rich ? theme.muted(`Run '${helpCommand}' for more information.`) : `Run '${helpCommand}' for more information.`;
+  return `${error}\n\n${help}`;
+}

package/src/terminal/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Terminal UI module
+ *
+ * DNA-009: Color palette & theme
+ * DNA-013: Safe Stream Writer
+ * DNA-015: Semantic help system
+ * DNA-017: Hero banner
+ */
+
+export { MANDU_PALETTE, type ManduColor } from "./palette.js";
+export { theme, isRich, colorize, stripAnsi } from "./theme.js";
+export {
+  shouldShowBanner,
+  renderHeroBanner,
+  renderMiniBanner,
+  renderBoxBanner,
+} from "./banner.js";
+export {
+  createSafeStreamWriter,
+  getSafeWriter,
+  safePrint,
+  safePrintln,
+  safePrintError,
+  type SafeStreamWriter,
+  type SafeStreamWriterOptions,
+} from "./stream-writer.js";
+export {
+  getOutputMode,
+  createFormatContext,
+  formatOutput,
+  formatError,
+  formatSuccess,
+  formatWarning,
+  formatInfo,
+  formatList,
+  type OutputMode,
+  type OutputOptions,
+  type FormatContext,
+} from "./output.js";
+export {
+  renderTable,
+  renderKeyValueTable,
+  type TableColumn,
+  type BorderStyle,
+  type RenderTableOptions,
+} from "./table.js";
+export {
+  createCliProgress,
+  withProgress,
+  startSpinner,
+  runSteps,
+  type ProgressOptions,
+  type ProgressReporter,
+} from "./progress.js";
+export {
+  formatHelpExample,
+  formatHelpExampleGroup,
+  formatHelpOption,
+  formatHelpSubcommand,
+  formatSectionTitle,
+  renderHelp,
+  renderCommandHelp,
+  formatUsageHint,
+  formatErrorHint,
+  MANDU_HELP,
+  type HelpExample,
+  type HelpOption,
+  type HelpSubcommand,
+  type HelpSection,
+  type HelpDefinition,
+} from "./help.js";

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;