# gaonjs (가온)

**AI가 개발을 가장 잘하는 Node.js 풀스택 웹 프레임웍.**

Gaon은 "정답이 하나(The One Way)"를 지향합니다 — 흔한 작업마다 관례가 하나로
정해져 있어, 사람도 AI도 헤매지 않고 첫 시도에 동작하는 코드를 씁니다. 타입은
스키마 → 모델 → 컨트롤러 → 페이지까지 자동으로 흐르고, 인증·실시간·잡·메일 등
배터리가 기본 포함됩니다.

> ℹ️ **설치명은 `gaonjs`, CLI 명령은 `gaon` 입니다.** (npm 패키지명 `gaon` 은
> 유사도 정책으로 점유 불가 → 파사드 패키지명을 `gaonjs` 로 확정.)

## 설치 → 첫 화면까지 (약 60초)

```bash
gaon new my-app              # 새 프로젝트 스캐폴드 (파일 → 설치 → git init)
                             #   설치 없이: npx gaonjs new my-app
cd my-app
gaon dev                     # 개발 스택 통합 기동 (Docker · .gaon 생성 · serve · 워처)
```

`gaon dev` 는 Docker Compose(DB·Redis·NATS 등)를 띄우고, 타입 브리지(`.gaon/`)를
생성하고, 웹 서버를 부팅하고, 코드 변경을 감시해 재시작까지 합니다. 브라우저에서
개발 랜딩이 뜨면 준비 완료입니다. (운영은 감시 없는 `gaon serve`.)

## 핵심 개념

- **배터리 포함** — 인증(세션·JWT), 실시간(채널·프레즌스·`gaon hub`), 비동기 잡
  (NATS JetStream·아웃박스·크론), 메일, 파일 스토리지, i18n 이 코어에 들어 있습니다.
  `gaon g auth` 한 번이면 회원가입·로그인·세션·보호 라우트가 스캐폴드됩니다.
- **타입이 끝까지 흐른다** — `domain/schema` 의 컬럼을 지우면, 그 컬럼을 쓰는 `.vue`
  페이지에서 `vue-tsc` 가 컴파일 에러를 냅니다. 스키마 → `model()` → 컨트롤러
  render props → 페이지 `pageProps<'app:ctrl#action'>()` 까지 타입 브리지(`.gaon/`)로
  자동 연결됩니다.
- **프론트는 Inertia SPA** — 별도 REST 엔드포인트도, 클라이언트 라우터도 없습니다.
  컨트롤러가 `this.render('Posts/Index', props)` 로 Vue 페이지에 props 를 넘기고,
  폼은 `useForm(...)`, 페이지 이동은 `Link`/`router.visit` 를 씁니다.
- **보안 기본 켬** — CORS·rate limit·CSRF 가 기본 활성화됩니다(끄는 것만 명시 설정).
- **The One Way** — 선택지가 생기면 정답이 하나가 되는 쪽을 고릅니다. 탈출구는
  남기되 기본 경로에서는 아무것도 고르지 않게 합니다.

## 프로젝트 구조

```
my-app/
├─ domain/            # schema · models · services · jobs · events · mails · seed
├─ apps/<이름>/       # app.config.ts · routes.ts · controllers · pages · components
├─ shared/            # 앱 간 공유 (라우트를 모르는 순수 UI/유틸)
├─ gaon.config.ts     # DB 등 공통 설정
└─ compose.yaml       # 개발 인프라 (Docker)
```

개발자는 `gaonjs` 하나만 설치합니다 — 내부는 `@gaonjs/*` 로 모듈화돼 있고,
파사드 서브패스로 가져옵니다: `gaonjs/web` · `gaonjs/data` · `gaonjs/vue` ·
`gaonjs/async` · `gaonjs/mail` · `gaonjs/storage` · `gaonjs/i18n` · `gaonjs/service`.

## 주요 CLI

```bash
gaon new <name>      # 새 프로젝트 스캐폴드
gaon dev             # 개발 스택 통합 (Docker · .gaon · serve · 워처)
gaon g auth          # 인증 배터리 스캐폴드
gaon g <타입> …      # controller · model · page · job · app · ui-kit 생성
gaon db migrate      # 마이그레이션 (diff · migrate · status · seed · reset)
gaon check           # typecheck · vue-tsc · build 통합 검사
gaon doctor          # 정적 검사 (관례 위반·안티패턴 · --fix)
gaon serve           # 운영 웹 서버 부팅 (감시 없음)
gaon work / gaon hub # 비동기 워커 · 실시간 허브
```

모든 명령은 `--json` 출력을 지원합니다(자동화·CI).

## AI 네이티브

Gaon 은 AI 에이전트가 첫 시도에 정답을 쓰도록 설계됐습니다. `gaon new` 는
프로젝트에 **`AGENTS.md` + `agents/*.md`**(관례 정본 · doctor 검사 목록 포함)를
함께 스캐폴드하므로, Claude Code 같은 에이전트가 그 규칙을 그대로 따릅니다.
`gaon mcp`(MCP 도구)로 에이전트에 프레임웍 능력을 노출할 수도 있습니다.

- 홈페이지 / 문서: https://gaonjs.dev
- 라이선스: MIT