@gaonjs/cli 0.4.0 → 0.5.0

package/dist/doctor/shared-composable-purity.js

@@ -0,0 +1,164 @@
+// @gaonjs/cli · doctor · shared 컴포저블 순수성 검사 (M9-E 확장 · errata E-5 §2.2)
+//
+// shared/composables/ 는 shared 컴포넌트의 "props 로만" 규칙과 정확히
+// 같은 구도를 따른다. 라우트를 몰라야 하고(api·pageProps 금지) · domain
+// 은 타입으로만 참조해야 한다. 필요한 데이터·호출 함수는 인자로 받는다.
+// 정본 근거: errata E-5 §2.2 (컴포저블·레이아웃 관례 · 결정 25).
+//
+// 검사 대상:
+//  1) 프레임웍 모듈(gaonjs · gaonjs/vue · @gaonjs/vue · @gaonjs/web) 에서
+//     'api' · 'pageProps' 를 value import 하면 error.
+//     - type-only 는 무해(구조 참조뿐 · 라우트 지식 필요 없음).
+//  2) domain 을 value import 하면 error.
+//     - type-only 는 허용(모델 Row 타입 등 · 순수 타입 참조).
+//
+// 방법: shared/composables/*.ts 를 TS AST 로 파싱해 import 선언만 훑는다.
+// 상대 import 는 실 파일까지 해석하지 않고 경로 접두사(domain/) 로 판정 —
+// 이 검사는 순수성 게이트라 정확도보다 재현성이 우선(false positive 는
+// 오히려 안전).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, dirname } from 'node:path';
+import ts from 'typescript';
+/** 라우트 지식을 담은 심볼 — shared 는 참조할 수 없다. */
+const FORBIDDEN_FRAMEWORK_NAMES = new Set(['api', 'pageProps']);
+/**
+ * 프레임웍 모듈 패턴. 문서 표기(gaon/vue)는 실 패키지 이름의 짧은
+ * 별칭이며, 실 배포본은 gaonjs 파사드 subpath 와 @gaonjs 스코프를 쓴다.
+ * 하나만 잡으면 우회가 쉬우므로 알려진 표기 3종을 모두 매치한다.
+ */
+const FRAMEWORK_MODULE_PATTERNS = [
+    /^gaonjs$/,
+    /^gaonjs\/vue$/,
+    /^@gaonjs\/vue$/,
+    /^@gaonjs\/web$/,
+];
+/** import 선언에서 이름과 type-only 플래그를 추출한다. */
+function collectImportedNames(node) {
+    const out = [];
+    const clause = node.importClause;
+    if (!clause)
+        return out;
+    const clauseTypeOnly = clause.isTypeOnly;
+    if (clause.name)
+        out.push({ name: clause.name.text, typeOnly: clauseTypeOnly });
+    const bindings = clause.namedBindings;
+    if (bindings) {
+        if (ts.isNamespaceImport(bindings)) {
+            out.push({ name: bindings.name.text, typeOnly: clauseTypeOnly });
+        }
+        else if (ts.isNamedImports(bindings)) {
+            for (const el of bindings.elements) {
+                out.push({ name: el.name.text, typeOnly: clauseTypeOnly || el.isTypeOnly });
+            }
+        }
+    }
+    return out;
+}
+function isRelativeSpecifier(s) {
+    return s.startsWith('./') || s.startsWith('../');
+}
+function matchesFrameworkModule(spec) {
+    return FRAMEWORK_MODULE_PATTERNS.some((re) => re.test(spec));
+}
+/**
+ * 단일 shared 컴포저블 소스를 검사해 순수성 위반 목록을 낸다
+ * (단위 테스트 진입점).
+ */
+export function inspectSharedComposable(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const baseDir = dirname(file);
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const spec = node.moduleSpecifier.text;
+            const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+            const names = collectImportedNames(node);
+            // 1) 프레임웍의 api/pageProps 를 value import → error
+            if (matchesFrameworkModule(spec)) {
+                for (const n of names) {
+                    if (n.typeOnly)
+                        continue; // type-only 는 라우트 실행 지식이 아님
+                    if (!FORBIDDEN_FRAMEWORK_NAMES.has(n.name))
+                        continue;
+                    issues.push({
+                        rule: 'shared-composable-purity',
+                        level: 'error',
+                        file: rel,
+                        line: line + 1,
+                        message: `${rel} (line ${line + 1})\n` +
+                            `  '${spec}' 의 '${n.name}' import 발견 · shared 는 라우트를 몰라야 함\n` +
+                            `→ 옵션: apps/<앱>/composables/ 로 옮기거나 · ${n.name} 호출을 인자로 받도록 바꾸라`,
+                        detail: {
+                            kind: 'framework-api',
+                            module: spec,
+                            name: n.name,
+                        },
+                    });
+                }
+            }
+            // 2) domain value import → error (type-only 는 허용)
+            if (isRelativeSpecifier(spec)) {
+                const abs = resolve(baseDir, spec);
+                const parts = relative(cwd, abs).split(/[\\/]/).filter(Boolean);
+                if (parts[0] === 'domain') {
+                    const valueNames = names.filter((n) => !n.typeOnly);
+                    if (valueNames.length > 0) {
+                        issues.push({
+                            rule: 'shared-composable-purity',
+                            level: 'error',
+                            file: rel,
+                            line: line + 1,
+                            message: `${rel} (line ${line + 1})\n` +
+                                `  domain 값 import 발견 · shared 컴포저블은 domain 을 타입으로만 참조해야 함\n` +
+                                `→ 'import type { ... } from ...' 형태로 바꾸거나 · 필요한 값은 인자로 받도록 바꾸라`,
+                            detail: {
+                                kind: 'domain-value',
+                                module: spec,
+                                names: valueNames.map((n) => n.name),
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return issues;
+}
+/** shared/composables/ 를 훑어 순수성 위반을 모두 낸다. */
+export async function checkSharedComposablePurity(cwd) {
+    const composablesDir = join(cwd, 'shared', 'composables');
+    const files = [];
+    await collectTsFiles(composablesDir, files);
+    const issues = [];
+    for (const file of files) {
+        const src = await readFile(file, 'utf8');
+        issues.push(...inspectSharedComposable(file, src, cwd));
+    }
+    return { rule: 'shared-composable-purity', issues };
+}
+async function collectTsFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const name = e.name;
+        if (name === 'node_modules' || name === 'dist' || name === '.gaon')
+            continue;
+        const full = join(root, name);
+        if (e.isDirectory())
+            await collectTsFiles(full, out);
+        else if (e.isFile() &&
+            name.endsWith('.ts') &&
+            !name.endsWith('.d.ts') &&
+            !name.endsWith('.test.ts')) {
+            out.push(full);
+        }
+    }
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/types.js

@@ -1,9 +1,10 @@
-// @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix)
+// @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 5 검사(response-mixing · n-plus-one · dependency-direction · connections
-// · migration-diff)가 모두 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는
-// level 로 passed/warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을
-// 파싱해 errors.length > 0 이면 fail 로 판단한다.
+// 7 검사(response-mixing · n-plus-one · dependency-direction · connections
+// · migration-diff · shared-composable-purity · no-auto-import)가 모두
+// 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
+// warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을 파싱해
+// errors.length > 0 이면 fail 로 판단한다.
 //
 // 사전 검사 실패(프로젝트 마커 없음 · TS API 미노출)는 규칙 실행 자체가
 // 불가능한 상황이므로 별도 `fatal` 필드로 표현한다 — runCli 는 이 경우

package/dist/doctor.d.ts

@@ -6,6 +6,8 @@ export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
 export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/connections.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
+export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
+export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {

package/dist/doctor.js

@@ -1,12 +1,14 @@
 /**
- * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성)
+ * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 5 검사를 조립한다:
+ * 7 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
  *  4) connections (v0.15 §4.5)
  *  5) migration-diff (최소 감지 · 상세는 M9-D)
+ *  6) shared-composable-purity (errata E-5 §2.2 · 결정 25)
+ *  7) no-auto-import (errata E-5 §2.4 · v0.15 §1.2)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -22,6 +24,8 @@ import { checkNPlusOne } from './doctor/n-plus-one.js';
 import { checkDependencyDirection } from './doctor/dependency-direction.js';
 import { checkConnections } from './doctor/connections.js';
 import { checkMigrationDiff } from './doctor/migration-diff.js';
+import { checkSharedComposablePurity } from './doctor/shared-composable-purity.js';
+import { checkNoAutoImport } from './doctor/no-auto-import.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -30,10 +34,12 @@ export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
 export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/connections.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
+export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
+export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 5개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 7개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -41,6 +47,8 @@ const ALL_RULES = [
     'dependency-direction',
     'connections',
     'migration-diff',
+    'shared-composable-purity',
+    'no-auto-import',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -48,6 +56,8 @@ const CHECKERS = {
     'dependency-direction': checkDependencyDirection,
     connections: checkConnections,
     'migration-diff': checkMigrationDiff,
+    'shared-composable-purity': checkSharedComposablePurity,
+    'no-auto-import': checkNoAutoImport,
 };
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).

package/dist/index.d.ts

@@ -2,7 +2,10 @@ import { type DoctorRule } from "./doctor.js";
 export { startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, } from "./dev.js";
 export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
 export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, type DevConsole, type DevConsoleOptions, type DevSource, type DevLevel, type ComposeStatus, type ComposeUpOptions, type EnsureInfraResult, type DockerLocateOptions, type TscWatcherOptions, type TscWatcherHandle, type RestartWatcherOptions, type RestartWatcherHandle, } from "./dev/index.js";
-export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
+export { runCheckCommand, type CheckCommandOptions, type CheckStep, type CheckStepStatus, type CheckStepResult, } from "./commands/check.js";
+export { runNewCommand, type NewCommandOptions, type NewCommandResult } from "./commands/new.js";
+export { runConsoleCommand, type ConsoleCommandOptions } from "./commands/console.js";
+export { runTestCommand, type TestCommandOptions, type TestScope } from "./commands/test.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, type AuthScaffoldOptions, type ScaffoldFile, type ScaffoldResult, type GenerateAuthOptions, } from "./generate.js";
 export { runGenerateCommand, planScaffold, parseGenerateArgs, type GenerateType, type GenerateOptions, type GenerateResult, } from "./commands/g.js";
 export { runHubCommand, type HubCommandOptions } from "./hub.js";

package/dist/index.js

@@ -12,7 +12,10 @@
  */
 import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
-import { runCheckCommand } from "./check.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";
@@ -24,7 +27,10 @@ import { runDoctorCommand } from "./doctor.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 { runCheck, runCheckCommand, } from "./check.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";
@@ -79,6 +85,7 @@ function renderHelp(version = VERSION) {
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
+        "    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 옵션",
@@ -86,8 +93,10 @@ function renderHelp(version = VERSION) {
         "    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        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
@@ -124,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 = [];
@@ -179,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;
         })
@@ -331,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