<p align="center">
  <img src="https://raw.githubusercontent.com/konamgil/mandu/main/mandu_only_simbol.png" alt="Mandu" width="200" />
</p>

<h1 align="center">@mandujs/cli</h1>

<p align="center">
  <strong>Agent-Native Fullstack Framework CLI</strong><br/>
  에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS
</p>

<p align="center">
  <a href="./README.md"><strong>English</strong></a> | 한국어
</p>

## 설치

```bash
# Bun 필수
bun add -D @mandujs/cli
```

## 빠른 시작

```bash
# 대화형 모드 (권장)
bunx @mandujs/cli create

# 비대화형 모드
bunx @mandujs/cli create my-app --yes

# 개발 서버 시작
cd my-app
bun install
bun run dev
```

생성된 앱에서는 `bun run dev`가 `mandu dev`를 실행하며, 기본 개발 서버는 `http://localhost:3333`에서 시작합니다.

대화형 모드에서는 프로젝트 이름, 템플릿, 의존성 설치 여부를 묻습니다.
`--yes` / `-y` 플래그로 프롬프트를 건너뛸 수 있고, `--no-install`로 자동 설치를 비활성화합니다.

## 명령어

### `mandu create <project-name>`

새 폴더에 Mandu 프로젝트를 스캐폴딩합니다. 이름 생략 시 대화형 모드로 진입합니다.

```bash
bunx @mandujs/cli create           # 대화형
bunx @mandujs/cli create my-app    # 비대화형 (기본 옵션)
bunx @mandujs/cli create my-app --yes --no-install  # 설치 건너뛰기
```

### `mandu init`

현재 폴더에 Mandu 환경을 retrofit 합니다 (`package.json` merge + `app/page.tsx` 생성).
기존 파일은 `--force` 없으면 보존되며, `--dry-run` 으로 변경사항을 미리 볼 수 있습니다.

```bash
mandu init                # 현재 폴더에 retrofit
mandu init --dry-run      # 어떤 파일이 변경될지 미리보기
mandu init --force        # 충돌 시 mandu 버전으로 덮어쓰기
```

> 호환: `mandu init my-app` 처럼 인자를 주면 한 사이클 동안 deprecation 경고와 함께 `mandu create my-app` 으로 위임됩니다. 다음 메이저에서 제거 예정.

생성되는 구조:
```
my-app/
├── app/                 # FS Routes
│   └── page.tsx         # /
├── src/                 # 아키텍처 레이어
│   ├── client/          # 클라이언트 (FSD)
│   │   ├── app/
│   │   ├── pages/
│   │   ├── widgets/
│   │   ├── features/
│   │   ├── entities/
│   │   └── shared/
│   ├── server/          # 서버 (Clean)
│   │   ├── api/
│   │   ├── application/
│   │   ├── domain/
│   │   ├── infra/
│   │   └── core/
│   └── shared/          # 공용
│       ├── contracts/        # client-safe 계약
│       ├── types/
│       ├── utils/
│       │   ├── client/       # 클라이언트 safe 유틸
│       │   └── server/       # 서버 전용 유틸
│       ├── schema/           # 서버 전용 스키마
│       └── env/              # 서버 전용 환경
├── apps/
│   ├── server/main.ts    # 서버 진입점
│   └── web/entry.tsx     # 클라이언트 진입점
├── spec/
│   ├── slots/              # 비즈니스 로직 파일
│   └── contracts/          # 타입 안전 계약
├── .mandu/                  # 생성된 산출물 (자동 관리)
│   └── routes.manifest.json # 라우트 매니페스트 (자동 생성)
├── package.json
└── tsconfig.json
```

### `mandu dev`

개발 서버를 시작합니다 (HMR 지원).

```bash
bun run dev
# 또는
bunx mandu dev
```

### `mandu routes generate`

FS Routes(app/)를 스캔하여 매니페스트를 생성합니다.

```bash
bun run generate
```

### `mandu generate`

spec 기반으로 코드를 생성합니다.

```bash
bun run generate
```

### `mandu guard`

아키텍처 규칙을 검사합니다. (기본: mandu 프리셋)

```bash
bun run guard

# 프리셋 변경
bunx mandu guard --preset fsd

# CI 모드 (warning도 실패 처리)
bunx mandu guard --ci
```

### `mandu guard legacy`

레거시 Spec Guard 검사 + 자동 수정입니다.

```bash
bunx mandu guard legacy

# 자동 수정 비활성화
bunx mandu guard legacy --no-auto-correct
```

자동 수정 가능한 규칙(legacy):
- `GENERATED_MANUAL_EDIT` → 코드 재생성
- `SLOT_NOT_FOUND` → slot 파일 생성

### `mandu contract build`

계약 레지스트리(`.mandu/contracts.json`)를 생성합니다.

```bash
bunx mandu contract build
```

### `mandu contract diff`

계약 변경사항(major/minor/patch)을 비교합니다.

```bash
bunx mandu contract diff
```

## FS Routes (라우트 정의)

`app/` 디렉토리가 모든 라우트의 단일 진실 공급원(SSOT)입니다. 파일을 생성하면 라우트가 자동으로 정의됩니다.

```
app/
├── page.tsx              # / (홈 페이지)
├── about/
│   └── page.tsx          # /about
├── api/
│   └── users/
│       └── route.ts      # /api/users
└── blog/
    └── [slug]/
        └── page.tsx      # /blog/:slug (동적 라우트)
```

`bun run generate` 실행 시 `app/` 디렉토리를 스캔하여 `.mandu/routes.manifest.json`을 자동 생성합니다.
직접 매니페스트를 편집할 필요가 없습니다.

- `spec/slots/` - 개발자가 작성하는 비즈니스 로직
- `spec/contracts/` - 타입 안전 계약 정의

### Slot 시스템 (v0.2.0+)

비즈니스 로직을 분리하려면 `slotModule`을 추가합니다:

```json
{
  "id": "getUsers",
  "pattern": "/api/users",
  "kind": "api",
  "module": "apps/server/api/users.generated.ts",
  "slotModule": "apps/server/api/users.slot.ts"
}
```

- `*.generated.ts` - 프레임워크가 관리 (수정 금지)
- `*.slot.ts` - 개발자가 작성하는 비즈니스 로직

## 개발 워크플로우

```bash
# 1. app/ 디렉토리에 라우트 파일 생성/수정

# 2. 코드 생성 (매니페스트 자동 갱신)
bun run generate

# 3. 아키텍처 검사
bun run guard

# 4. 테스트
bun test

# 5. 개발 서버
bun run dev
```

## 테스트

Bun 테스트 프레임워크를 기본 지원합니다.

```bash
bun test           # 테스트 실행
bun test --watch   # 감시 모드
```

## AI 에이전트 통합

`mandu init` 시 MCP(Model Context Protocol) 설정이 자동 생성됩니다:

| 에이전트 | 설정 파일 | 자동 설정 |
|----------|-----------|-----------|
| Claude Code | `.mcp.json` | Yes |
| Claude Desktop | `.claude.json` | Yes |
| Gemini CLI | `.gemini/settings.json` | Yes |

`@mandujs/mcp` 서버가 `mandu_negotiate`, `mandu_generate_scaffold`, `mandu_guard` 등의 도구를 제공하여 AI 에이전트가 아키텍처를 자동으로 스캐폴딩, 검증, 유지합니다.

## 요구 사항

- Bun >= 1.0.0
- React >= 19.0.0

## 관련 패키지

- [@mandujs/core](https://www.npmjs.com/package/@mandujs/core) - 핵심 런타임
- [@mandujs/mcp](https://www.npmjs.com/package/@mandujs/mcp) - MCP 서버

## 라이선스

MPL-2.0
