@gaonjs/cli 0.3.0 → 0.5.0

package/dist/templates/project/apps/web/composables/useApiPing.ts.tpl

@@ -0,0 +1,25 @@
+// useApiPing — 앱 전용 컴포저블(errata E-5 §2.1).
+// 파일 하나에 컴포저블 하나 · 파일명 = 컴포저블명 · use 접두사.
+// 앱 전용 컴포저블은 api()/pageProps() 를 자유롭게 쓸 수 있다.
+// shared/composables 는 반대 — 인자로만 받는 순수 로직(E-5 §2.2).
+import { ref } from 'vue'
+
+/** GET /health 를 두드려 서버가 살아 있는지 확인하는 예시 컴포저블. */
+export function useApiPing() {
+  const ok = ref<boolean | null>(null)
+  const error = ref<string | null>(null)
+
+  async function ping(): Promise<void> {
+    try {
+      const res = await fetch('/health', { headers: { Accept: 'application/json' } })
+      const body = (await res.json()) as { ok: boolean }
+      ok.value = body.ok === true
+      error.value = null
+    } catch (err) {
+      ok.value = false
+      error.value = err instanceof Error ? err.message : String(err)
+    }
+  }
+
+  return { ok, error, ping }
+}

package/dist/templates/project/apps/web/controllers/home.ts.tpl

@@ -0,0 +1,19 @@
+// home 컨트롤러 — apps/web/controllers/home.ts. 페이지 액션(this.render)과
+// JSON 액션(반환값 = 응답 · errata E-3)의 두 대표 패턴을 함께 담는다.
+import { controller } from 'gaonjs/web'
+
+export default controller({
+  // GET / — Inertia SPA 홈. this.render 는 Vue 페이지(Home/Index.vue) 로 넘긴다.
+  async index() {
+    return this.render('Home/Index', {
+      title: '{{PROJECT_NAME}}',
+      docs: 'https://gaonjs.dev',
+    })
+  },
+
+  // GET /health — JSON 액션(errata E-3). 반환값이 곧 응답.
+  // 배포 후 헬스체크·60초 실측(v0.15 §13.5 M9 완료 기준)에 쓰인다.
+  async health() {
+    return { ok: true, service: '{{PROJECT_NAME}}' }
+  },
+})

package/dist/templates/project/apps/web/layouts/Default.vue.tpl

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+// 기본 레이아웃 — apps/web/layouts/Default.vue (errata E-5 §2.3).
+// 파일이 존재하면 이 앱의 모든 페이지에 자동 적용된다(파일 존재 = 등록).
+// 다른 레이아웃이 필요한 페이지만 페이지 파일에서 명시적으로 바꾼다.
+//
+// 레이아웃은 shared 에 두지 않는다(E-5 §2.3) — 앱마다 레이아웃이 다른 것이
+// 정상이고, 공용 조각(로고·푸터 등) 만 shared/components 로 뽑는다.
+</script>
+
+<template>
+  <div class="layout">
+    <header class="layout-header">
+      <strong>{{PROJECT_NAME}}</strong>
+    </header>
+    <slot />
+    <footer class="layout-footer">
+      <small>Powered by <a href="https://gaonjs.dev" target="_blank">Gaon</a></small>
+    </footer>
+  </div>
+</template>
+
+<style scoped>
+.layout {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+.layout-header,
+.layout-footer {
+  padding: 1rem;
+  background: #f6f8fa;
+  border-color: #e1e4e8;
+}
+.layout-header {
+  border-bottom: 1px solid #e1e4e8;
+}
+.layout-footer {
+  border-top: 1px solid #e1e4e8;
+  margin-top: auto;
+  text-align: center;
+  color: #6a737d;
+}
+</style>

package/dist/templates/project/apps/web/pages/Home/Index.vue.tpl

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import { pageProps } from 'gaonjs/vue'
+
+// home#index 의 render props — Serialized<> 로 넘어온다(§6.2).
+// 라우트 키는 .gaon/routes.d.ts 가 유효한 값을 알려준다.
+const props = pageProps<'home#index'>()
+</script>
+
+<template>
+  <main class="home">
+    <h1>{{ props.title }}</h1>
+    <p>Gaon 프레임웍이 방금 이 앱을 만들었습니다.</p>
+    <p>
+      문서: <a :href="props.docs" target="_blank">{{ props.docs }}</a>
+    </p>
+    <hr />
+    <h2>다음 단계</h2>
+    <ol>
+      <li><code>gaon g auth</code> — 인증 스캐폴드 생성 (회원가입·로그인·세션)</li>
+      <li><code>gaon g model Post</code> — 모델 스캐폴드 (스키마 + 모델 · E-4)</li>
+      <li><code>gaon g controller posts</code> — 컨트롤러 스캐폴드</li>
+      <li><code>gaon g page Posts/Index</code> — Vue 페이지 (Inertia SPA)</li>
+      <li><code>gaon dev</code> — Docker 자동 기동 · 타입 브리지 · watch</li>
+    </ol>
+  </main>
+</template>
+
+<style scoped>
+.home {
+  max-width: 640px;
+  margin: 4rem auto;
+  padding: 0 1rem;
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.6;
+}
+</style>

package/dist/templates/project/apps/web/routes.ts.tpl

@@ -0,0 +1,8 @@
+// web 앱 라우트 — apps/web/routes.ts. 앱 폴더명(web)이 URL 프리픽스가 되지만
+// web 앱은 관례상 프리픽스 '/' 를 쓴다(v0.15 §6.1).
+import { routes } from 'gaonjs/web'
+
+export default routes((r) => {
+  r.get('/', 'home#index') // GET / → home#index (Inertia SPA · Home/Index.vue)
+  r.get('/health', 'home#health') // GET /health → JSON { ok: true } (헬스체크)
+})

package/dist/templates/project/docker-compose.yaml.tpl

@@ -0,0 +1,73 @@
+# {{PROJECT_NAME}} 개발 스택 — gaon dev 가 자동 기동한다(CLAUDE.md §2 · v0.15 §9).
+# 목업·인메모리 대체는 금지 — 개발·테스트·운영 모두 실 인프라를 쓴다.
+#
+# 기동:  docker compose up -d          (gaon dev 가 자동 실행)
+# 정지:  docker compose down
+name: {{PROJECT_NAME}}
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: {{PROJECT_NAME}}
+      POSTGRES_PASSWORD: {{PROJECT_NAME}}
+      POSTGRES_DB: {{PROJECT_NAME}}_dev
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{PROJECT_NAME}} -d {{PROJECT_NAME}}_dev"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 세션 스토어(§7.4). 캐시·세션은 Redis 가 기본이다.
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 실시간 백본(§7 · M6). NATS JetStream(-js) — 채널·잡·프레즌스 KV 를 모두 처리.
+  nats:
+    image: nats:2.10-alpine
+    command: ["-js", "-m", "8222"]
+    ports:
+      - "4222:4222"
+      - "8222:8222"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8222/healthz"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 메일 배터리(§7 · M8). MailPit = SMTP 싱크 + 웹 UI(:8025) — 개발 미리보기의 실 인프라.
+  mailpit:
+    image: axllent/mailpit:latest
+    ports:
+      - "1025:1025"
+      - "8025:8025"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8025/readyz"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  # 파일 스토리지(§7 · M8). MinIO = S3 호환 — 운영 R2/S3 와 동일 API.
+  minio:
+    image: minio/minio:latest
+    command: ["server", "/data", "--console-address", ":9001"]
+    environment:
+      MINIO_ROOT_USER: {{PROJECT_NAME}}
+      MINIO_ROOT_PASSWORD: {{PROJECT_NAME}}_secret
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 2s
+      timeout: 3s
+      retries: 30

package/dist/templates/project/domain/events/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/jobs/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/listeners/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/mails/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/models/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/schema/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/domain/services/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/gaon.config.ts.tpl

@@ -0,0 +1,27 @@
+// {{PROJECT_NAME}} 루트 설정 (§3.3). 개발자는 이 파일 하나로 배터리를 켠다.
+// 환경 변수는 .env 에서 로드된다 — gaon dev / gaon serve 가 자동 배선.
+import { defineConfig } from 'gaonjs/config'
+
+export default defineConfig({
+  // DB — main 커넥션. 스키마에서 { db: '키' } 로 다른 커넥션에 붙일 수 있다(§4.5).
+  db: process.env.DATABASE_URL
+    ? {
+        main: {
+          adapter: 'postgres',
+          url: process.env.DATABASE_URL,
+        },
+      }
+    : undefined,
+
+  // Redis — 세션 스토어 · 캐시.
+  redis: process.env.REDIS_URL ? { url: process.env.REDIS_URL } : undefined,
+
+  // NATS — 실시간·비동기 백본(§7). broadcast 전용(errata E-2).
+  nats: process.env.NATS_URL ? { url: process.env.NATS_URL } : undefined,
+
+  // 웹 서버 리슨 옵션. --port · env PORT 로 덮을 수 있다.
+  web: {
+    port: process.env.PORT ? Number(process.env.PORT) : 3000,
+    cookieSecret: process.env.COOKIE_SECRET,
+  },
+})

package/dist/templates/project/package.json.tpl

@@ -0,0 +1,27 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "gaon dev",
+    "serve": "gaon serve",
+    "work": "gaon work",
+    "hub": "gaon hub",
+    "check": "gaon check",
+    "doctor": "gaon doctor",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "gaonjs": "{{GAONJS_VERSION}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "vue": "^3.5.0",
+    "vue-tsc": "^3.3.0",
+    "vitest": "^3.0.0"
+  }
+}

package/dist/templates/project/pnpm-workspace.yaml.tpl

@@ -0,0 +1,11 @@
+# pnpm workspace — 앱은 apps/*, 도메인은 domain/, 공용은 shared/ 아래에 둔다.
+# 이 관례는 CLAUDE.md §2 · v0.15 §3.2 를 따른다(앱과 domain 은 별도 폴더).
+packages:
+  - "packages/*"
+
+# pnpm 11 부터 build script 실행은 명시적 승인 필요(보안 기본값 = 비 TTY 에서 exit 1).
+# 스캐폴드 첫 install 이 잡히지 않도록 완화하고, 실제 실행 허용 목록만 명시한다.
+# 정본 문서: https://pnpm.io/settings (구 package.json 의 pnpm 필드 대체).
+strictDepBuilds: false
+onlyBuiltDependencies:
+  - esbuild

package/dist/templates/project/shared/components/.gitkeep.tpl

@@ -0,0 +1 @@
+# 이 폴더는 gaon g <type> <name> 로 채워집니다. .gitkeep 은 스캐폴드 관례상 유지.

package/dist/templates/project/shared/composables/useDebounce.ts.tpl

@@ -0,0 +1,21 @@
+// useDebounce — shared 컴포저블(errata E-5 §2.2).
+// shared 는 shared 컴포넌트의 "props 로만" 규칙과 정확히 대칭이다:
+// gaonjs/vue 서브패스 import 금지 · domain 은 타입 import 만 · 인자로만
+// 받는 순수 로직. (`.gaon/routes.d.ts` 는 앱별 생성이라 구조적으로도
+// 라우트를 몰라야 한다.)
+
+/**
+ * fn 을 delay(ms) 만큼 지연 실행. 새 호출이 오면 이전 타이머를 취소한다.
+ * @param fn 실행할 함수 (인자로 받는다 — shared 는 라우트를 모른다).
+ * @param delay 지연 시간(ms).
+ */
+export function useDebounce<A extends readonly unknown[]>(
+  fn: (...args: A) => void,
+  delay: number,
+): (...args: A) => void {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  return (...args: A) => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => fn(...args), delay)
+  }
+}

package/dist/templates/project/tsconfig.json.tpl

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "jsx": "preserve",
+    "types": ["node"]
+  },
+  "include": [
+    "apps/**/*.ts",
+    "apps/**/*.vue",
+    "domain/**/*.ts",
+    "shared/**/*.ts",
+    "shared/**/*.vue",
+    "gaon.config.ts"
+  ],
+  "exclude": ["node_modules", "dist", ".gaon"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -24,13 +24,13 @@
     "README.md"
   ],
   "dependencies": {
-    "typescript": "*",
-    "@gaonjs/config": "0.1.0",
+    "typescript": "^5.9.0",
     "@gaonjs/async": "0.2.2",
+    "@gaonjs/config": "0.1.0",
     "@gaonjs/core": "0.1.4",
-    "@gaonjs/data": "0.3.0",
+    "@gaonjs/mail": "0.1.0",
     "@gaonjs/web": "0.3.0",
-    "@gaonjs/mail": "0.1.0"
+    "@gaonjs/data": "0.3.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""