@gaonjs/cli 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,27 +1,36 @@
 /**
  * @gaonjs/cli — Gaon CLI 구현.
  *
- * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M3 부터
- * `gaon dev` 가 실제로 동작한다 — .gaon 타입 브리지(tables·routes)를
- * 감시·재생성한다(dev.ts). 모든 명령은 `--json` 출력을 함께 제공한다
- * (CLAUDE.md §4). 스캐폴딩·나머지 제너레이터는 이후 마일스톤이다.
+ * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M9-C 부터
+ * `gaon dev` 가 통합 개발 오케스트레이션을 담당한다 — Docker Compose
+ * 자동 기동 + .gaon 타입 브리지 재생성 + serve 자식 프로세스 + tsc/vue-tsc
+ * --watch + 소스 변경 시 서버 재시작(commands/dev.ts). 모든 명령은 `--json`
+ * 출력을 함께 제공한다 (CLAUDE.md §4).
  *
  * 표시 버전은 호출자(파사드)가 주입한다 — 사용자가 설치한 패키지
  * (`gaonjs`) 버전을 그대로 보여주기 위함. 미주입 시 core 버전을 쓴다.
  */
 import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
-import { runDevCommand } from "./dev.js";
-import { runCheckCommand } from "./check.js";
+import { runDevCommand } from "./commands/dev.js";
+import { runCheckCommand } from "./commands/check.js";
+import { runNewCommand } from "./commands/new.js";
+import { runConsoleCommand } from "./commands/console.js";
+import { runTestCommand } from "./commands/test.js";
 import { runGenerateAuthCommand } from "./generate.js";
 import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
 import { runServeCommand } from "./serve.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
-import { runDbSeedCommand } from "./db.js";
+import { runDbCommand } from "./commands/db.js";
 import { runDoctorCommand } from "./doctor.js";
-export { runDevCommand, startDev, resolveDevLayout, } from "./dev.js";
-export { runCheck, runCheckCommand, } from "./check.js";
+export { startDev, resolveDevLayout, } from "./dev.js";
+export { runDevCommand } from "./commands/dev.js";
+export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, } from "./dev/index.js";
+export { runCheckCommand, } from "./commands/check.js";
+export { runNewCommand } from "./commands/new.js";
+export { runConsoleCommand } from "./commands/console.js";
+export { runTestCommand } from "./commands/test.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
 export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
@@ -29,6 +38,8 @@ export { runServeCommand } from "./serve.js";
 export { runWorkCommand } from "./work.js";
 export { runJobsCommand } from "./jobs.js";
 export { runDbSeedCommand, loadSeed } from "./db.js";
+export { runDbCommand, } from "./commands/db.js";
+export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, } from "./db/index.js";
 export { runDoctorCommand, runDoctor, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
 export { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
@@ -74,12 +85,18 @@ function renderHelp(version = VERSION) {
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
-        "    gaon dev           .gaon 타입 브리지를 감시·재생성 (스키마·라우트)",
-        "    gaon dev --json    재생성 이벤트를 JSON 으로 출력",
+        "    gaon new <name>    새 프로젝트 스캐폴드 (파일 → 설치 → git · --skip-install · --skip-git · --pm <이름>)",
+        "    gaon dev           개발 스택 통합 (Docker · .gaon · serve · tsc/vue-tsc · 재시작 워처)",
+        "    gaon dev --stop-docker  Ctrl+C 시 Docker Compose 도 down",
+        "    gaon dev --no-watch|--no-tsc|--no-vue-tsc|--no-docker  개별 debug 옵션",
+        "    gaon dev --port <n> --host <h>  serve 리슨 지정",
+        "    gaon dev --json    통합 콘솔을 JSON 라인으로 출력(자동화)",
         "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
         "    gaon serve --port <n> --host <h>   리슨 포트·호스트 (config 값을 덮음)",
-        "    gaon check         .gaon 재생성 후 타입 검사 (CI·AI 정합)",
-        "    gaon doctor        정적 검사 (5 검사 · 응답 혼용·N+1·의존 방향·커넥션·마이그)",
+        "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
+        "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
+        "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
+        "    gaon doctor        정적 검사 (7 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
@@ -92,6 +109,11 @@ function renderHelp(version = VERSION) {
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
         "    gaon jobs list --failed   DLQ(실패 잡) 목록",
         "    gaon jobs retry <id>      DLQ 잡 재적재",
+        "    gaon db diff              스키마 ↔ DB 차이 계산 (적용 X · --json · --db <키>)",
+        "    gaon db migrate           스키마 변경을 실제 적용 + _gaon_migrations 이력",
+        "    gaon db migrate --dry-run 적용 없이 up SQL 만 출력",
+        "    gaon db reset --yes       DROP ALL → 재마이그 → seed (--yes 필수 · production 거부)",
+        "    gaon db seed              domain/seed.ts 실행 (M8)",
         "    gaon --json        같은 정보를 JSON 으로 출력",
         "    gaon --version     버전 출력",
         "    gaon --help        이 도움말",
@@ -111,6 +133,8 @@ export function parseDoctorChecks(argv) {
         "dependency-direction",
         "connections",
         "migration-diff",
+        "shared-composable-purity",
+        "no-auto-import",
     ];
     const isKnown = (s) => known.includes(s);
     const out = [];
@@ -127,10 +151,26 @@ export function parseDoctorChecks(argv) {
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
-    // `gaon dev` — .gaon 갱신 파이프라인(장기 실행). 워처가 활성 핸들로
-    // 프로세스를 살려 두고, SIGINT 로 종료된다. 에러는 stderr + exit 1.
+    // `gaon dev` — 통합 개발 오케스트레이션(M9-C · v0.15 §13.5). Docker Compose
+    // 자동 기동 + .gaon 재생성 + serve 자식 + tsc/vue-tsc watch + 서버 재시작 워처.
+    // SIGINT/SIGTERM 시 순서대로 정리(serve → tsc → 워처 → Docker[--stop-docker 시]).
+    // 개별 debug 옵션은 --no-watch / --no-tsc / --no-vue-tsc / --no-docker 뿐.
     if (argv[0] === "dev") {
-        void runDevCommand({ json: argv.includes("--json") }).catch((err) => {
+        const portIdx = argv.indexOf("--port");
+        const hostIdx = argv.indexOf("--host");
+        const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
+        const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+        void runDevCommand({
+            json: argv.includes("--json"),
+            stopDocker: argv.includes("--stop-docker"),
+            noWatch: argv.includes("--no-watch"),
+            noTsc: argv.includes("--no-tsc"),
+            noVueTsc: argv.includes("--no-vue-tsc"),
+            noDocker: argv.includes("--no-docker"),
+            timestamp: argv.includes("--timestamp"),
+            port,
+            host,
+        }).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon dev 실패: ${msg}\n`);
             process.exitCode = 1;
@@ -150,9 +190,21 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon check` — .gaon 재생성 후 타입 검사(§13.4-5). 종료 코드로 결과 전달.
+    // `gaon check` — typecheck · vue-tsc · build (·doctor) 통합 검사(M9-G).
+    // package.json 스크립트 관례 재사용. --only <step> 로 단일 단계, --include-doctor
+    // 로 doctor 포함. 종료 코드로 결과 전달.
     if (argv[0] === "check") {
-        void runCheckCommand({ json: argv.includes("--json") })
+        const knownSteps = ["typecheck", "vue-tsc", "build", "doctor"];
+        const onlyIdx = argv.indexOf("--only");
+        const onlyRaw = onlyIdx >= 0 ? argv[onlyIdx + 1] : undefined;
+        const only = onlyRaw && knownSteps.includes(onlyRaw)
+            ? onlyRaw
+            : undefined;
+        void runCheckCommand({
+            json: argv.includes("--json"),
+            only,
+            includeDoctor: argv.includes("--include-doctor"),
+        })
             .then((code) => {
             process.exitCode = code;
         })
@@ -164,11 +216,16 @@ export function runCli(argv, opts = {}) {
         return;
     }
     // `gaon doctor` — 정적 검사(M9-E · 5 검사). --check=<이름>[,<이름>...] 로
-    // 선택 실행, --json 은 자동화 파싱용. exit code: errors.length > 0 이면 1.
+    // 선택 실행, --json 은 자동화 파싱용.
+    // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
         const checks = parseDoctorChecks(argv);
         void runDoctorCommand({ json: argv.includes("--json"), checks })
             .then((result) => {
+            if (result.fatal) {
+                process.exitCode = 2;
+                return;
+            }
             process.exitCode = result.errors.length > 0 ? 1 : 0;
         })
             .catch((err) => {
@@ -211,17 +268,33 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon db seed` — domain/seed.ts 실행(§7 M8). diff·migrate 는 M9 CLI 완성.
-    if (argv[0] === "db" && argv[1] === "seed") {
-        const json = argv.includes("--json");
-        void runDbSeedCommand({ json })
-            .then((res) => {
-            process.stdout.write((json ? JSON.stringify(res.json) : res.text) + "\n");
-            process.exitCode = res.exitCode;
+    // `gaon db <sub>` — diff · migrate · reset · seed (§7 M8/M9-D).
+    if (argv[0] === "db") {
+        const sub = argv[1];
+        const known = ["diff", "migrate", "reset", "seed"];
+        if (!sub || !known.includes(sub)) {
+            process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
+                `  → 지원: gaon db diff | migrate | reset | seed\n` +
+                `  → 옵션: --json · --db <키> · --config <path> · --yes · --dry-run\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const dbIdx = argv.indexOf("--db");
+        const cfgIdx = argv.indexOf("--config");
+        const dbOpts = {
+            json: argv.includes("--json"),
+            db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
+            config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
+            yes: argv.includes("--yes"),
+            dryRun: argv.includes("--dry-run"),
+        };
+        void runDbCommand(sub, dbOpts)
+            .then((code) => {
+            process.exitCode = code;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`  ✗ gaon db seed 실패: ${msg}\n`);
+            process.stderr.write(`  ✗ gaon db ${sub} 실패: ${msg}\n`);
             process.exitCode = 1;
         });
         return;
@@ -281,6 +354,81 @@ export function runCli(argv, opts = {}) {
         process.exitCode = 1;
         return;
     }
+    // `gaon new <name>` — 프로젝트 스캐폴드(M9-F). 파일 생성 → 의존성 설치 → git init.
+    if (argv[0] === "new") {
+        const rest = argv.slice(1);
+        let name;
+        for (const a of rest) {
+            if (!a.startsWith("--") && name === undefined)
+                name = a;
+        }
+        if (!name) {
+            process.stderr.write("  ✗ gaon new: 프로젝트 이름이 없습니다.\n  → 예: gaon new demo\n");
+            process.exitCode = 1;
+            return;
+        }
+        const pmIdx = rest.indexOf("--pm");
+        const pmRaw = pmIdx >= 0 ? rest[pmIdx + 1] : undefined;
+        const packageManager = pmRaw === "pnpm" || pmRaw === "npm" || pmRaw === "yarn" ? pmRaw : undefined;
+        void runNewCommand(name, {
+            json: argv.includes("--json"),
+            skipInstall: argv.includes("--skip-install"),
+            skipGit: argv.includes("--skip-git"),
+            packageManager,
+        })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon new 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
+    // `gaon console` — 프로젝트 컨텍스트 REPL(M9-G). --no-config 로 배선 없이 기동.
+    if (argv[0] === "console") {
+        void runConsoleCommand({
+            json: argv.includes("--json"),
+            noConfig: argv.includes("--no-config"),
+        }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon console 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
+    // `gaon test [--scope unit|integration|all] [-- vitest 인자]` — 테스트 러너(M9-G).
+    if (argv[0] === "test") {
+        const rest = argv.slice(1);
+        const scopeIdx = rest.indexOf("--scope");
+        const scopeRaw = scopeIdx >= 0 ? rest[scopeIdx + 1] : undefined;
+        const scope = scopeRaw === "unit" || scopeRaw === "integration" || scopeRaw === "all"
+            ? scopeRaw
+            : undefined;
+        const passthrough = [];
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === "--scope") {
+                i++;
+                continue;
+            }
+            if (a === "--json")
+                continue;
+            if (a !== undefined)
+                passthrough.push(a);
+        }
+        void runTestCommand(passthrough, { json: argv.includes("--json"), scope })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon test 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         process.stdout.write(renderHelp(version) + "\n");
         return;

package/dist/templates/index.d.ts

@@ -0,0 +1,23 @@
+/** 생성할 파일 하나 — path 는 프로젝트 루트 기준 상대 경로(POSIX). */
+export interface ProjectFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** 템플릿 렌더 시 치환되는 토큰 값. */
+export interface ProjectTemplateTokens {
+    readonly projectName: string;
+    readonly gaonjsVersion: string;
+}
+/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
+export declare function renderTemplate(raw: string, tokens: ProjectTemplateTokens): string;
+/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
+export declare function listTemplateFiles(root?: string): string[];
+/**
+ * 스캐폴드 파일 전체를 렌더링해 반환한다.
+ * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
+ */
+export declare function renderProjectFiles(tokens: ProjectTemplateTokens): ProjectFile[];
+/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
+export declare function templateDir(): string;
+/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
+export declare function findUnresolvedTokens(contents: string): string[];

package/dist/templates/index.js

@@ -0,0 +1,66 @@
+// @gaonjs/cli · templates/index.ts — 프로젝트 스캐폴드 템플릿 로더 (M9-F).
+//
+// `gaon new <name>` 이 소비하는 파일 트리. 소스 트리(src/templates/project/*)
+// 를 재귀 스캔해 각 `.tpl` 파일의 최종 경로와 렌더된 내용을 반환한다.
+// 렌더는 `{{TOKEN}}` 리터럴 replaceAll — Vue 의 `{{ }}` 보간과 겹치지 않는
+// 고정 리터럴이라 정규식 없이 안전하다(generate.ts 와 동일 관례).
+//
+// 폴더는 관례상 유지되어야 하지만 git 이 빈 폴더를 추적하지 않으므로
+// `.gitkeep.tpl` 을 두어 실 파일 `.gitkeep` 으로 렌더한다. 최종 경로는
+// `.tpl` 접미사를 벗긴 값이다.
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, posix, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'project');
+/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
+export function renderTemplate(raw, tokens) {
+    return raw
+        .replaceAll('{{PROJECT_NAME}}', tokens.projectName)
+        .replaceAll('{{GAONJS_VERSION}}', tokens.gaonjsVersion);
+}
+/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
+export function listTemplateFiles(root = TEMPLATE_DIR) {
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            out.push(abs);
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+/**
+ * 스캐폴드 파일 전체를 렌더링해 반환한다.
+ * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
+ */
+export function renderProjectFiles(tokens) {
+    const paths = listTemplateFiles();
+    return paths.map((abs) => {
+        const rel = relative(TEMPLATE_DIR, abs).split(sep).join(posix.sep);
+        const outPath = rel.endsWith('.tpl') ? rel.slice(0, -'.tpl'.length) : rel;
+        const raw = readFileSync(abs, 'utf8');
+        return { path: outPath, contents: renderTemplate(raw, tokens) };
+    });
+}
+/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
+export function templateDir() {
+    return TEMPLATE_DIR;
+}
+/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
+export function findUnresolvedTokens(contents) {
+    const re = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g;
+    const found = new Set();
+    for (const m of contents.matchAll(re)) {
+        // Vue 템플릿의 {{ prop }} (소문자·공백 시작) 은 제외 — 위 정규식이 대문자만
+        // 잡으므로 자연스럽게 걸러진다. 남으면 진짜 미치환.
+        found.add(m[1]);
+    }
+    return [...found].sort();
+}

package/dist/templates/index.ts

@@ -0,0 +1,85 @@
+// @gaonjs/cli · templates/index.ts — 프로젝트 스캐폴드 템플릿 로더 (M9-F).
+//
+// `gaon new <name>` 이 소비하는 파일 트리. 소스 트리(src/templates/project/*)
+// 를 재귀 스캔해 각 `.tpl` 파일의 최종 경로와 렌더된 내용을 반환한다.
+// 렌더는 `{{TOKEN}}` 리터럴 replaceAll — Vue 의 `{{ }}` 보간과 겹치지 않는
+// 고정 리터럴이라 정규식 없이 안전하다(generate.ts 와 동일 관례).
+//
+// 폴더는 관례상 유지되어야 하지만 git 이 빈 폴더를 추적하지 않으므로
+// `.gitkeep.tpl` 을 두어 실 파일 `.gitkeep` 으로 렌더한다. 최종 경로는
+// `.tpl` 접미사를 벗긴 값이다.
+
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, posix, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 생성할 파일 하나 — path 는 프로젝트 루트 기준 상대 경로(POSIX). */
+export interface ProjectFile {
+  readonly path: string
+  readonly contents: string
+}
+
+/** 템플릿 렌더 시 치환되는 토큰 값. */
+export interface ProjectTemplateTokens {
+  readonly projectName: string
+  readonly gaonjsVersion: string
+}
+
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'project')
+
+/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
+export function renderTemplate(raw: string, tokens: ProjectTemplateTokens): string {
+  return raw
+    .replaceAll('{{PROJECT_NAME}}', tokens.projectName)
+    .replaceAll('{{GAONJS_VERSION}}', tokens.gaonjsVersion)
+}
+
+/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
+export function listTemplateFiles(root: string = TEMPLATE_DIR): string[] {
+  const out: string[] = []
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walk(abs)
+        continue
+      }
+      if (!entry.isFile()) continue
+      out.push(abs)
+    }
+  }
+  walk(root)
+  return out.sort()
+}
+
+/**
+ * 스캐폴드 파일 전체를 렌더링해 반환한다.
+ * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
+ */
+export function renderProjectFiles(tokens: ProjectTemplateTokens): ProjectFile[] {
+  const paths = listTemplateFiles()
+  return paths.map((abs) => {
+    const rel = relative(TEMPLATE_DIR, abs).split(sep).join(posix.sep)
+    const outPath = rel.endsWith('.tpl') ? rel.slice(0, -'.tpl'.length) : rel
+    const raw = readFileSync(abs, 'utf8')
+    return { path: outPath, contents: renderTemplate(raw, tokens) }
+  })
+}
+
+/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
+export function templateDir(): string {
+  return TEMPLATE_DIR
+}
+
+/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
+export function findUnresolvedTokens(contents: string): string[] {
+  const re = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g
+  const found = new Set<string>()
+  for (const m of contents.matchAll(re)) {
+    // Vue 템플릿의 {{ prop }} (소문자·공백 시작) 은 제외 — 위 정규식이 대문자만
+    // 잡으므로 자연스럽게 걸러진다. 남으면 진짜 미치환.
+    found.add(m[1]!)
+  }
+  return [...found].sort()
+}
+

package/dist/templates/project/.env.example.tpl

@@ -0,0 +1,18 @@
+# {{PROJECT_NAME}} 환경 변수 — cp .env.example .env 후 편집.
+# gaon.config.ts 의 env('KEY') 로 참조된다. gaon dev · gaon serve 가 자동 로드.
+
+# DB — docker-compose.yaml 의 postgres 서비스와 정합.
+DATABASE_URL=postgres://{{PROJECT_NAME}}:{{PROJECT_NAME}}@127.0.0.1:5432/{{PROJECT_NAME}}_dev
+
+# Redis — 세션 스토어.
+REDIS_URL=redis://127.0.0.1:6379
+
+# NATS — 실시간·비동기 백본(§7).
+NATS_URL=nats://127.0.0.1:4222
+
+# 세션 · 쿠키 서명 비밀 (32자 이상, 운영은 반드시 교체).
+SESSION_SECRET=change-me-to-a-32-char-random-secret!!
+COOKIE_SECRET=change-me-too-32-char-random-secret!!
+
+# 리슨 포트 (gaon serve --port 로 덮음).
+PORT=3000

package/dist/templates/project/.gitignore.tpl

@@ -0,0 +1,24 @@
+# 의존성 · 빌드 산출물
+node_modules/
+dist/
+*.tsbuildinfo
+
+# 자동 생성 타입 브리지(§6.3) — gaon check / gaon dev 가 재생성한다.
+.gaon/
+
+# 환경 변수
+.env
+.env.local
+.env.*.local
+
+# 로그 · 캐시
+*.log
+.DS_Store
+.cache/
+coverage/
+
+# 에디터
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json

package/dist/templates/project/.npmrc.tpl

@@ -0,0 +1,4 @@
+# pnpm 로컬 설정(선택). 대부분의 pnpm 설정은 pnpm-workspace.yaml 로
+# 이동했다(구 package.json 의 pnpm 필드도 마찬가지). 여기는 로그·레지스트리
+# 처럼 파일 단위로 다르게 둘 수 있는 것만 남긴다.
+loglevel=info

package/dist/templates/project/CLAUDE.md.tpl

@@ -0,0 +1,119 @@
+# {{PROJECT_NAME}} — AI 작업 지침
+
+이 파일은 이 프로젝트에서 AI(Claude 등)가 코드를 만질 때 지켜야 할
+관례를 담는다. Gaon 프레임웍이 이 관례를 스캐폴드(`gaon new`)로 자동
+심어 두는 이유는 하나다 — 첫 시도부터 프로젝트 관례에 맞게 코드를 짜
+반복 수정을 없애기 위함(§1.1 AI 첫 시도 성공률).
+
+## 0. 먼저 읽을 것
+
+Gaon 프레임웍 문서: https://gaonjs.dev
+
+- 설계 정본(v0.15) · errata E-1(파사드 = `gaonjs`) · E-3(JSON 액션 +
+  `api()`) · E-4(컬럼 확장) · E-5(컴포저블·레이아웃)
+- 앱 내 One Way(§1) — 선택지가 있는 것을 만들지 않는다. 하나로 정한다.
+
+## 1. 절대 규칙 (12개 · 프레임웍 정본에서 유래)
+
+1. **TypeScript 전용.** JS 파일 추가 금지. 데코레이터 금지 — 함수·객체
+   스타일(`model()`·`controller()`·`job()`) 만 쓴다.
+2. **`.gaon/` 자동 생성 파일 편집 금지.** `routes.d.ts`·`tables.d.ts`
+   는 `gaon check` / `gaon dev` 가 재생성한다.
+3. **의존 방향 4규칙**(doctor 강제): 앱→domain 허용 · domain→앱 금지 ·
+   앱→앱 금지 · 앱→shared 허용(shared 는 앱 import 금지, domain 은
+   타입 import 만).
+4. **PM2·pnpm dev-server 금지.** 클러스터는 `node:cluster` 내장이 유일.
+   컨테이너 기본 워커 1.
+5. **프론트엔드는 프로젝트당 하나.** v1 은 Vue 단일. 앱 간 Vue/React
+   혼용 금지.
+6. **보안 기본값(CORS·rate limit·CSRF)은 켠 채로 둔다.** 끄는 것은
+   명시적 설정으로만.
+7. **멀티 DB 커넥션 규칙**(§4.5): 스키마는 `{ db: '키' }` 로 바인딩,
+   생략 = main. 커넥션을 가로지르는 belongsTo 금지, 서비스 트랜잭션은
+   단일 커넥션에서만 원자적. MongoDB 는 v1 구현 금지.
+8. **테스트는 Docker 실 인프라 필수 · DB·NATS 목업 절대 금지**(§9).
+   SQLite 인메모리·NATS 목업으로 테스트 돌리는 코드 만들지 말 것.
+9. **실시간은 v1 포함**(§7): 웹서버 ↔ 허브는 TCP 지속 연결 · NATS 는
+   broadcast 전용(errata E-2). 운영 프로세스는 serve·work·hub 3종.
+10. **인증·폼은 Inertia SPA**(§6 · SSR 아님). 로그인/회원가입은
+    `this.render('auth/Login')` + `Inertia.post()` → 서버 redirect.
+    REST + `fetch()` 는 API 앱(JWT) 전용.
+11. **컴포저블·레이아웃**(errata E-5): 컴포저블은 컴포넌트와 대칭
+    (`apps/<앱>/composables/` + `shared/composables/`, `use` 접두사).
+    shared 컴포저블은 인자로만 받는 순수 로직(api·pageProps 금지).
+    레이아웃은 `apps/<앱>/layouts/Default.vue` 존재 시 자동 적용.
+    **자동 import 금지** — 모든 import 는 명시적으로.
+12. **JSON 액션 + 타입드 `api()`**(errata E-3): 페이지와 무관한 데이터
+    요청은 컨트롤러의 JSON 액션(반환값 = 응답) · Vue 는 `api()`
+    클라이언트로 호출. `this.params()` 출처 우선순위 = 라우트 > body >
+    query(고정). 출처 명시는 `this.body()`·`this.query()`.
+
+## 2. 프로젝트 구조
+
+```
+{{PROJECT_NAME}}/
+├─ apps/                          앱마다 폴더 = URL 프리픽스
+│  └─ web/                        web 앱 (프리픽스 '/')
+│     ├─ app.config.ts            (선택) 앱 오버라이드
+│     ├─ routes.ts                라우트 정의
+│     ├─ controllers/             컨트롤러 (Rails 관례)
+│     ├─ pages/                   Vue 페이지 (Inertia SPA)
+│     ├─ components/              앱 전용 컴포넌트
+│     ├─ composables/             앱 전용 컴포저블 (E-5)
+│     ├─ layouts/                 앱별 레이아웃 (E-5 · Default.vue 자동)
+│     └─ channels/                (선택) 실시간 채널 (M6)
+├─ domain/                        비즈니스 로직 · 앱 간 공유
+│  ├─ schema/                     테이블 스키마 (@gaonjs/data)
+│  ├─ models/                     모델 (조회·연관·훅)
+│  ├─ services/                   트랜잭션 · 규칙
+│  ├─ jobs/                       비동기 잡 (@gaonjs/async)
+│  ├─ events/                     이벤트 정의
+│  ├─ listeners/                  이벤트 리스너
+│  ├─ mails/                      메일 (@gaonjs/mail)
+│  └─ schedule.ts                 (선택) 크론 스케줄
+├─ shared/                        앱 간 공용 (props로만)
+│  ├─ components/                 shared 컴포넌트 (순수 UI)
+│  └─ composables/                shared 컴포저블 (인자로만 · E-5)
+├─ gaon.config.ts                 루트 설정 (DB · Redis · NATS · ...)
+├─ docker-compose.yaml            개발 인프라 (gaon dev 자동 기동)
+├─ .env.example                   env 템플릿 (cp .env.example .env)
+└─ package.json                   개발자는 gaonjs 하나만 설치
+```
+
+## 3. 개발 검증 루프 (작업마다 실행)
+
+```bash
+gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
+gaon doctor                       # 정적 검사 5종 (응답·N+1·의존·커넥션·마이그)
+npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
+```
+
+## 4. 작업 관례
+
+- **추론 금지 · 사실 검증.** 확인 안 된 것은 실행·측정으로 검증하거나
+  사용자에게 묻는다.
+- **주석은 개발자가 단 것처럼.** AI가 단 티가 나는 주석(`// AI 판단…`
+  `// TODO(AI)` 등) 금지. 기술적 이유(왜 이 코드가 이런지, 특수 케이스
+  근거) 만 담는다.
+- **파일 작게 · 역할은 하나로.** 영리한 코드보다 읽히는 코드.
+- **에러 메시지**(§7.5.3): "어느 파일에 무엇을 추가/수정하고 어떤
+  명령을 실행하라" 까지 쓴다.
+
+## 5. 자주 쓰는 명령
+
+```bash
+gaon dev                          # 개발 (Docker · 타입 브리지 · watch)
+gaon serve                        # 서버만 (운영 프로세스 1/3)
+gaon work                         # 워커 (잡·리스너·아웃박스)
+gaon hub                          # 실시간 허브 (프레즌스 · 리더 선출 HA)
+gaon g controller <name>          # 컨트롤러 스캐폴드
+gaon g model <Name>               # 스키마 + 모델 스캐폴드 (E-4)
+gaon g page <Path>/<Name>         # Vue 페이지 (Inertia SPA · pageProps)
+gaon g job <Name>                 # 비동기 잡
+gaon g auth                       # 인증 스캐폴드 (세션 + JWT 옵션)
+gaon db diff                      # 스키마 ↔ DB 차이 (적용 X)
+gaon db migrate                   # 실제 적용 + _gaon_migrations 이력
+gaon db seed                      # domain/seed.ts 실행
+```
+
+문서 · 진행 상황: https://gaonjs.dev

package/dist/templates/project/apps/web/channels/.gitkeep.tpl

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

package/dist/templates/project/apps/web/components/.gitkeep.tpl

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