@mandujs/cli 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
   "type": "module",
   "main": "./src/main.ts",
@@ -32,7 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "workspace:*"
+    "@mandujs/core": "workspace:*",
+    "cfonts": "^3.3.0"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/commands/registry.ts

@@ -0,0 +1,357 @@
+/**
+ * DNA-010: Command Registry Pattern
+ *
+ * 선언적 명령어 등록 시스템
+ * - 각 명령어를 독립적으로 정의
+ * - 레이지 로딩으로 시작 시간 최적화
+ * - 서브커맨드 자동 라우팅
+ */
+
+import type { CLI_ERROR_CODES } from "../errors";
+
+/**
+ * 명령어 실행 컨텍스트
+ */
+export interface CommandContext {
+  args: string[];
+  options: Record<string, string>;
+}
+
+/**
+ * 명령어 등록 정의
+ */
+export interface CommandRegistration {
+  /** 명령어 ID (예: "dev", "build", "guard") */
+  id: string;
+  /** 명령어 설명 */
+  description: string;
+  /** 서브커맨드 목록 (예: guard의 "arch", "legacy") */
+  subcommands?: string[];
+  /** 기본 서브커맨드 (서브커맨드 없이 호출 시) */
+  defaultSubcommand?: string;
+  /** 명령어 실행 */
+  run: (ctx: CommandContext) => Promise<boolean>;
+}
+
+/**
+ * 명령어 레지스트리
+ */
+export const commandRegistry = new Map<string, CommandRegistration>();
+
+/**
+ * 명령어 등록
+ */
+export function registerCommand(registration: CommandRegistration): void {
+  commandRegistry.set(registration.id, registration);
+}
+
+/**
+ * 명령어 조회
+ */
+export function getCommand(id: string): CommandRegistration | undefined {
+  return commandRegistry.get(id);
+}
+
+/**
+ * 모든 명령어 ID 목록
+ */
+export function getAllCommands(): string[] {
+  return Array.from(commandRegistry.keys());
+}
+
+// ============================================================================
+// 명령어 등록 (레이지 로딩)
+// ============================================================================
+
+registerCommand({
+  id: "init",
+  description: "새 프로젝트 생성 (Tailwind + shadcn/ui 기본 포함)",
+  async run(ctx) {
+    const { init } = await import("./init");
+    return init({
+      name: ctx.options.name || ctx.options._positional,
+      css: ctx.options.css as any,
+      ui: ctx.options.ui as any,
+      theme: ctx.options.theme === "true",
+      minimal: ctx.options.minimal === "true",
+    });
+  },
+});
+
+registerCommand({
+  id: "dev",
+  description: "개발 서버 실행 (FS Routes + Guard 기본)",
+  async run() {
+    const { dev } = await import("./dev");
+    await dev();
+    return true;
+  },
+});
+
+registerCommand({
+  id: "build",
+  description: "클라이언트 번들 빌드 (Hydration)",
+  async run(ctx) {
+    const { build } = await import("./build");
+    return build({ watch: ctx.options.watch === "true" });
+  },
+});
+
+registerCommand({
+  id: "check",
+  description: "FS Routes + Guard 통합 검사",
+  async run() {
+    const { check } = await import("./check");
+    return check();
+  },
+});
+
+registerCommand({
+  id: "guard",
+  description: "아키텍처 위반 검사",
+  subcommands: ["arch", "legacy", "spec"],
+  defaultSubcommand: "arch",
+  async run(ctx) {
+    const subCommand = ctx.args[1];
+    const hasSubCommand = subCommand && !subCommand.startsWith("--");
+
+    const guardOptions = {
+      watch: ctx.options.watch === "true",
+      output: ctx.options.output,
+    };
+
+    switch (subCommand) {
+      case "arch": {
+        const { guardArch } = await import("./guard-arch");
+        return guardArch(guardOptions);
+      }
+      case "legacy":
+      case "spec": {
+        const { guardCheck } = await import("./guard-check");
+        return guardCheck();
+      }
+      default:
+        if (hasSubCommand) {
+          // 알 수 없는 서브커맨드는 main.ts에서 처리
+          return false;
+        }
+        // 기본값: architecture guard
+        const { guardArch } = await import("./guard-arch");
+        return guardArch(guardOptions);
+    }
+  },
+});
+
+registerCommand({
+  id: "routes",
+  description: "FS Routes 관리",
+  subcommands: ["generate", "list", "watch"],
+  defaultSubcommand: "list",
+  async run(ctx) {
+    const subCommand = ctx.args[1];
+    const { routesGenerate, routesList, routesWatch } = await import("./routes");
+
+    const routesOptions = {
+      output: ctx.options.output,
+      verbose: ctx.options.verbose === "true",
+    };
+
+    switch (subCommand) {
+      case "generate":
+        return routesGenerate(routesOptions);
+      case "list":
+        return routesList({ verbose: routesOptions.verbose });
+      case "watch":
+        return routesWatch(routesOptions);
+      default:
+        if (subCommand && !subCommand.startsWith("--")) {
+          return false; // 알 수 없는 서브커맨드
+        }
+        return routesList({ verbose: routesOptions.verbose });
+    }
+  },
+});
+
+registerCommand({
+  id: "contract",
+  description: "Contract-First API 개발",
+  subcommands: ["create", "validate", "build", "diff"],
+  async run(ctx) {
+    const subCommand = ctx.args[1];
+    const {
+      contractCreate,
+      contractValidate,
+      contractBuild,
+      contractDiff,
+    } = await import("./contract");
+
+    switch (subCommand) {
+      case "create": {
+        const routeId = ctx.args[2] || ctx.options._positional;
+        if (!routeId) return false;
+        return contractCreate({ routeId });
+      }
+      case "validate":
+        return contractValidate({ verbose: ctx.options.verbose === "true" });
+      case "build":
+        return contractBuild({ output: ctx.options.output });
+      case "diff":
+        return contractDiff({
+          from: ctx.options.from,
+          to: ctx.options.to,
+          output: ctx.options.output,
+          json: ctx.options.json === "true",
+        });
+      default:
+        return false;
+    }
+  },
+});
+
+registerCommand({
+  id: "openapi",
+  description: "OpenAPI 스펙 생성",
+  subcommands: ["generate", "serve"],
+  async run(ctx) {
+    const subCommand = ctx.args[1];
+    const { openAPIGenerate, openAPIServe } = await import("./openapi");
+
+    switch (subCommand) {
+      case "generate":
+        return openAPIGenerate({
+          output: ctx.options.output,
+          title: ctx.options.title,
+          version: ctx.options.version,
+        });
+      case "serve":
+        return openAPIServe();
+      default:
+        return false;
+    }
+  },
+});
+
+registerCommand({
+  id: "change",
+  description: "변경 트랜잭션 관리",
+  subcommands: ["begin", "commit", "rollback", "status", "list", "prune"],
+  async run(ctx) {
+    const subCommand = ctx.args[1];
+    const {
+      changeBegin,
+      changeCommit,
+      changeRollback,
+      changeStatus,
+      changeList,
+      changePrune,
+    } = await import("./change");
+
+    switch (subCommand) {
+      case "begin":
+        return changeBegin({ message: ctx.options.message });
+      case "commit":
+        return changeCommit();
+      case "rollback":
+        return changeRollback({ id: ctx.options.id });
+      case "status":
+        return changeStatus();
+      case "list":
+        return changeList();
+      case "prune":
+        return changePrune({
+          keep: ctx.options.keep ? Number(ctx.options.keep) : undefined,
+        });
+      default:
+        return false;
+    }
+  },
+});
+
+registerCommand({
+  id: "brain",
+  description: "Brain (sLLM) 관리",
+  subcommands: ["setup", "status"],
+  async run(ctx) {
+    const subCommand = ctx.args[1];
+    const { brainSetup, brainStatus } = await import("./brain");
+
+    switch (subCommand) {
+      case "setup":
+        return brainSetup({
+          model: ctx.options.model,
+          url: ctx.options.url,
+          skipCheck: ctx.options["skip-check"] === "true",
+        });
+      case "status":
+        return brainStatus({ verbose: ctx.options.verbose === "true" });
+      default:
+        return false;
+    }
+  },
+});
+
+registerCommand({
+  id: "doctor",
+  description: "Guard 실패 분석 + 패치 제안",
+  async run(ctx) {
+    const { doctor } = await import("./doctor");
+    return doctor({
+      useLLM: ctx.options["no-llm"] !== "true",
+      output: ctx.options.output,
+    });
+  },
+});
+
+registerCommand({
+  id: "watch",
+  description: "실시간 파일 감시",
+  async run(ctx) {
+    const { watch } = await import("./watch");
+    return watch({
+      status: ctx.options.status === "true",
+      debounce: ctx.options.debounce ? Number(ctx.options.debounce) : undefined,
+    });
+  },
+});
+
+registerCommand({
+  id: "monitor",
+  description: "MCP Activity Monitor",
+  async run(ctx) {
+    const { monitor } = await import("./monitor");
+    return monitor({
+      summary: ctx.options.summary === "true",
+      since: ctx.options.since,
+      follow: ctx.options.follow === "false" ? false : true,
+      file: ctx.options.file,
+    });
+  },
+});
+
+registerCommand({
+  id: "lock",
+  description: "Lockfile 관리",
+  async run(ctx) {
+    const { runLockCommand } = await import("./lock");
+    return runLockCommand(ctx.args.slice(1));
+  },
+});
+
+// 레거시 명령어
+registerCommand({
+  id: "spec-upsert",
+  description: "Spec 파일 검증 및 lock 갱신 (레거시)",
+  async run(ctx) {
+    const { specUpsert } = await import("./spec-upsert");
+    return specUpsert({ file: ctx.options.file });
+  },
+});
+
+registerCommand({
+  id: "generate",
+  description: "Spec에서 코드 생성 (레거시)",
+  async run() {
+    const { generateApply } = await import("./generate-apply");
+    return generateApply();
+  },
+});

package/src/hooks/index.ts

@@ -0,0 +1,17 @@
+/**
+ * DNA-016: CLI Hooks
+ *
+ * 명령어 라이프사이클 훅
+ */
+
+export {
+  preActionRegistry,
+  runPreAction,
+  registerPreActionHook,
+  registerDefaultHooks,
+  setVerbose,
+  isVerbose,
+  setProcessTitle,
+  type PreActionContext,
+  type PreActionHook,
+} from "./preaction.js";

package/src/hooks/preaction.ts

@@ -0,0 +1,256 @@
+/**
+ * DNA-016: Pre-Action Hooks
+ *
+ * 명령어 실행 전 공통 작업 수행
+ * - 프로세스 타이틀 설정
+ * - 조건부 배너 표시
+ * - Verbose 모드 설정
+ * - 설정 로드
+ */
+
+import { shouldShowBanner, renderMiniBanner } from "../terminal/banner.js";
+import { loadManduConfig, type ManduConfig } from "@mandujs/core";
+
+/**
+ * Pre-Action 컨텍스트
+ */
+export interface PreActionContext {
+  /** 현재 명령어 */
+  command: string;
+  /** 서브커맨드 */
+  subcommand?: string;
+  /** 명령어 옵션 */
+  options: Record<string, string>;
+  /** 로드된 설정 */
+  config?: ManduConfig;
+  /** verbose 모드 여부 */
+  verbose: boolean;
+  /** 작업 디렉토리 */
+  cwd: string;
+}
+
+/**
+ * Pre-Action 훅 타입
+ */
+export type PreActionHook = (ctx: PreActionContext) => void | Promise<void>;
+
+/**
+ * Pre-Action 훅 레지스트리
+ */
+class PreActionRegistry {
+  private hooks: PreActionHook[] = [];
+
+  /**
+   * 훅 등록
+   */
+  register(hook: PreActionHook): void {
+    this.hooks.push(hook);
+  }
+
+  /**
+   * 훅 제거
+   */
+  unregister(hook: PreActionHook): boolean {
+    const index = this.hooks.indexOf(hook);
+    if (index >= 0) {
+      this.hooks.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * 모든 훅 실행
+   */
+  async runAll(ctx: PreActionContext): Promise<void> {
+    for (const hook of this.hooks) {
+      await hook(ctx);
+    }
+  }
+
+  /**
+   * 훅 초기화
+   */
+  clear(): void {
+    this.hooks = [];
+  }
+
+  /**
+   * 등록된 훅 수
+   */
+  get size(): number {
+    return this.hooks.length;
+  }
+}
+
+/**
+ * 전역 Pre-Action 훅 레지스트리
+ */
+export const preActionRegistry = new PreActionRegistry();
+
+/**
+ * 설정 로드가 필요없는 명령어
+ */
+const SKIP_CONFIG_COMMANDS = new Set([
+  "init",
+  "help",
+  "version",
+  "completion",
+]);
+
+/**
+ * 배너 표시가 필요없는 명령어
+ */
+const SKIP_BANNER_COMMANDS = new Set([
+  "completion",
+  "version",
+]);
+
+/**
+ * verbose 전역 상태
+ */
+let globalVerbose = false;
+
+/**
+ * verbose 모드 설정
+ */
+export function setVerbose(value: boolean): void {
+  globalVerbose = value;
+}
+
+/**
+ * verbose 모드 확인
+ */
+export function isVerbose(): boolean {
+  return globalVerbose;
+}
+
+/**
+ * 프로세스 타이틀 설정
+ */
+export function setProcessTitle(command: string, subcommand?: string): void {
+  const title = subcommand
+    ? `mandu ${command} ${subcommand}`
+    : `mandu ${command}`;
+
+  if (typeof process.title !== "undefined") {
+    process.title = title;
+  }
+}
+
+/**
+ * 기본 Pre-Action 실행
+ *
+ * @example
+ * ```ts
+ * const ctx = await runPreAction({
+ *   command: "dev",
+ *   options: { port: "3000" },
+ * });
+ *
+ * // ctx.config 에서 로드된 설정 사용
+ * // ctx.verbose 로 verbose 모드 확인
+ * ```
+ */
+export async function runPreAction(params: {
+  command: string;
+  subcommand?: string;
+  options: Record<string, string>;
+  cwd?: string;
+  version?: string;
+}): Promise<PreActionContext> {
+  const {
+    command,
+    subcommand,
+    options,
+    cwd = process.cwd(),
+    version,
+  } = params;
+
+  // 1. verbose 모드 확인
+  const verbose = options.verbose === "true" || process.env.MANDU_VERBOSE === "true";
+  setVerbose(verbose);
+
+  // 2. 프로세스 타이틀 설정
+  setProcessTitle(command, subcommand);
+
+  // 3. 조건부 배너 표시
+  const showBanner =
+    !SKIP_BANNER_COMMANDS.has(command) &&
+    !isTruthyEnv("MANDU_HIDE_BANNER") &&
+    shouldShowBanner();
+
+  if (showBanner && version) {
+    console.log(renderMiniBanner(version));
+    console.log();
+  }
+
+  // 4. 설정 로드 (필요한 명령어만)
+  let config: ManduConfig | undefined;
+  if (!SKIP_CONFIG_COMMANDS.has(command)) {
+    try {
+      config = await loadManduConfig(cwd);
+    } catch {
+      // 설정 로드 실패 시 무시 (옵션 설정만 사용)
+      if (verbose) {
+        console.warn("[mandu] Config load failed, using defaults");
+      }
+    }
+  }
+
+  // Pre-Action 컨텍스트 생성
+  const ctx: PreActionContext = {
+    command,
+    subcommand,
+    options,
+    config,
+    verbose,
+    cwd,
+  };
+
+  // 5. 등록된 훅 실행
+  await preActionRegistry.runAll(ctx);
+
+  return ctx;
+}
+
+/**
+ * 환경변수가 truthy인지 확인
+ */
+function isTruthyEnv(key: string): boolean {
+  const value = process.env[key];
+  if (!value) return false;
+  return !["0", "false", "no", ""].includes(value.toLowerCase());
+}
+
+/**
+ * Pre-Action 훅 등록 헬퍼
+ *
+ * @example
+ * ```ts
+ * registerPreActionHook(async (ctx) => {
+ *   if (ctx.command === "dev") {
+ *     console.log("Starting development mode...");
+ *   }
+ * });
+ * ```
+ */
+export function registerPreActionHook(hook: PreActionHook): () => void {
+  preActionRegistry.register(hook);
+  return () => preActionRegistry.unregister(hook);
+}
+
+/**
+ * 기본 훅들 등록
+ */
+export function registerDefaultHooks(): void {
+  // 예: 개발 모드에서 추가 정보 표시
+  registerPreActionHook((ctx) => {
+    if (ctx.verbose && ctx.config) {
+      console.log(`[mandu] Config loaded from ${ctx.cwd}`);
+      if (ctx.config.server?.port) {
+        console.log(`[mandu] Server port: ${ctx.config.server.port}`);
+      }
+    }
+  });
+}