@gaonjs/cli 0.4.0 → 0.10.0

package/dist/mcp/tools.js

@@ -0,0 +1,485 @@
+/**
+ * @gaonjs/cli · MCP 도구 4종 — v0.15 §12 질문 8 원문 명세.
+ *
+ * 정본 §12 질문 8 원문:
+ *   "내장 MCP 서버 — 종결 (v0.11). 권장안 채택: 최소 도구 4종
+ *    (라우트 목록, 스키마 조회, 마이그레이션 실행, 테스트 실행)으로 시작."
+ *
+ * 정본 §7.5.3 (에러 = 수리 안내서 · 내장 MCP 서버) 원문:
+ *   "gaon mcp 로 프레임웍이 자신을 AI 도구로 노출한다: 라우트 목록,
+ *    스키마 조회, 마이그레이션 실행, 테스트 실행을 구조화된 도구로 제공.
+ *    에이전트가 grep 으로 프로젝트를 더듬는 대신 프레임웍에게 직접 묻는다."
+ *
+ * 도구 명명(kebab_case → 함수명 snake_case):
+ *   list_routes      — 라우트 목록 (§13.5 M10 · 질문 8 ①)
+ *   get_schema       — 스키마 조회 (§13.5 M10 · 질문 8 ②)
+ *   run_migration    — 마이그레이션 실행 (§13.5 M10 · 질문 8 ③)
+ *   run_tests        — 테스트 실행 (§13.5 M10 · 질문 8 ④)
+ *
+ * 실 인프라 §9 — 각 도구는 실제 CLI 로직을 재사용해 실 실행한다. 목업 X.
+ *   list_routes  → @gaonjs/config resolveApps + @gaonjs/web routes 파싱
+ *   get_schema   → @gaonjs/data scanSchemaDir + columns() 조회
+ *   run_migration→ ../db/migrate.ts (dryRun 지원)
+ *   run_tests    → ../commands/test.ts (실 vitest spawn)
+ *
+ * 반환은 항상 사람용 텍스트 + 구조화 JSON(둘 다). MCP 스펙상
+ * content[] 에는 텍스트만 담고, structuredContent 에 원본 JSON 을 넣는다 —
+ * 클라이언트가 렌더링·파싱 어느 쪽이든 쓸 수 있게.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { registerTsResolve } from '../tsResolve.js';
+import { runDbMigrate } from '../db/migrate.js';
+import { scanSchemaDir, columns } from '@gaonjs/data';
+// ── 유틸 ────────────────────────────────────────────────────
+/** 문자열 옵션 안전 추출. */
+function stringOpt(args, key) {
+    const v = args[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** 불리언 옵션 안전 추출. */
+function boolOpt(args, key) {
+    return args[key] === true;
+}
+/**
+ * 에러 → ToolResult. 사용자가 볼 텍스트에는 "→ 수리 안내" 를 포함한다
+ * (§7.5.3 원칙 · 에러가 곧 실행 가능한 수리 명령).
+ */
+function errorResult(message, extra) {
+    return {
+        text: `[gaon mcp] ${message}`,
+        data: { ok: false, error: message, ...extra },
+        isError: true,
+    };
+}
+// ── 도구 1: list_routes ──────────────────────────────────────
+/**
+ * `list_routes` — 프로젝트의 모든 앱과 라우트를 나열한다.
+ *
+ * 관례(§3.3): apps/<name>/routes.ts 의 default export 가 routes(...) 결과
+ * (RouteDef · entries[]). @gaonjs/config resolveApps 가 발견·로드한다.
+ *
+ * 인자:
+ *   { app?: string }   — 지정 시 그 앱만. 없으면 전 앱.
+ *
+ * 반환:
+ *   data.apps: [{ name, routeCount, routes: [{ method, path, controller, action }] }]
+ */
+export async function listRoutesTool(args, cwd) {
+    registerTsResolve();
+    const appFilter = stringOpt(args, 'app');
+    // 정본 §3.3 관례를 그대로 재사용. resolveApps 는 @gaonjs/config 에 있지만
+    // CLI 는 config 를 workspace 의존으로 이미 갖고 있다.
+    const { resolveApps } = await import('@gaonjs/config');
+    const apps = await resolveApps(cwd);
+    const filtered = appFilter ? apps.filter((a) => a.name === appFilter) : apps;
+    if (appFilter && filtered.length === 0) {
+        const known = apps.map((a) => a.name).sort();
+        return errorResult(`앱 '${appFilter}' 을(를) 찾을 수 없습니다.\n` +
+            `  발견된 앱: ${known.length ? known.join(', ') : '(없음 · apps/<name>/routes.ts 를 만드세요)'}`);
+    }
+    const summary = [];
+    for (const app of filtered) {
+        const def = app.routes;
+        const entries = Array.isArray(def?.entries) ? def.entries : [];
+        summary.push({
+            name: app.name,
+            dir: app.dir,
+            routeCount: entries.length,
+            routes: entries.map((e) => ({
+                method: e.method,
+                path: e.path,
+                controller: e.controller,
+                action: e.action,
+            })),
+        });
+    }
+    const totalRoutes = summary.reduce((a, s) => a + s.routeCount, 0);
+    const lines = [];
+    if (summary.length === 0) {
+        lines.push('(발견된 앱이 없습니다. apps/<name>/routes.ts 관례를 확인하세요.)');
+    }
+    else {
+        for (const app of summary) {
+            lines.push(`■ ${app.name}  (${app.routeCount}개)`);
+            for (const r of app.routes) {
+                lines.push(`  ${r.method.toUpperCase().padEnd(6)} ${r.path.padEnd(30)} → ${r.controller}#${r.action}`);
+            }
+        }
+        lines.push('');
+        lines.push(`총 ${summary.length}개 앱 · ${totalRoutes}개 라우트`);
+    }
+    return {
+        text: lines.join('\n'),
+        data: { ok: true, apps: summary, totalApps: summary.length, totalRoutes },
+        isError: false,
+    };
+}
+function columnToInfo(name, meta) {
+    const info = {
+        name,
+        sqlType: meta.sqlType,
+        nullable: meta.nullable,
+        primaryKey: meta.primaryKey,
+        hasDefault: meta.hasDefault,
+        hidden: meta.hidden,
+        references: meta.references,
+        maxLen: meta.maxLen,
+        precision: meta.precision,
+        scale: meta.scale,
+        enumValues: meta.enumValues,
+        unique: meta.unique,
+        index: meta.index,
+        checkExpr: meta.checkExpr,
+    };
+    return info;
+}
+function isTableDef(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'name' in v &&
+        'defs' in v &&
+        'db' in v &&
+        typeof v.name === 'string');
+}
+/**
+ * `get_schema` — domain/schema/ 의 테이블 정의를 조회한다.
+ *
+ * 관례(§4.1): domain/schema/*.ts 의 export 로 table(...) 결과가 놓인다.
+ * @gaonjs/data scanSchemaDir 로 모듈을 로드하고, TableDef 만 추려 컬럼 메타를
+ * 함께 낸다. 커넥션 키(§4.5) · 복합 제약(§4.2) 도 포함.
+ *
+ * 인자:
+ *   { table?: string, db?: string }
+ *      table — 지정 시 그 테이블만
+ *      db    — 지정 시 그 커넥션 것만 (기본: 전 커넥션)
+ *
+ * 반환:
+ *   data.tables: [{ name, db, columns: [...], constraints: { unique, index, check } }]
+ */
+export async function getSchemaTool(args, cwd) {
+    registerTsResolve();
+    const tableFilter = stringOpt(args, 'table');
+    const dbFilter = stringOpt(args, 'db');
+    const schemaDir = join(resolvePath(cwd), 'domain', 'schema');
+    if (!existsSync(schemaDir)) {
+        return errorResult(`domain/schema/ 디렉터리가 없습니다.\n` +
+            `→ ${schemaDir} 에 스키마 파일(예: post.ts)을 만들고 \`export const posts = table('posts', { ... })\` 로 선언하세요.`);
+    }
+    const outDir = join(resolvePath(cwd), '.gaon');
+    const modules = await scanSchemaDir(schemaDir, outDir);
+    const all = [];
+    for (const mod of modules) {
+        for (const [, value] of Object.entries(mod.ns)) {
+            if (isTableDef(value))
+                all.push(value);
+        }
+    }
+    const filtered = all.filter((t) => {
+        if (tableFilter && t.name !== tableFilter)
+            return false;
+        if (dbFilter && t.db !== dbFilter)
+            return false;
+        return true;
+    });
+    if (tableFilter && filtered.length === 0) {
+        const known = all.map((t) => t.name).sort();
+        return errorResult(`테이블 '${tableFilter}' 을(를) 찾을 수 없습니다.\n` +
+            `  발견된 테이블: ${known.length ? known.join(', ') : '(없음)'}`);
+    }
+    const tables = filtered
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((t) => ({
+        name: t.name,
+        db: t.db,
+        columns: columns(t).map(([n, m]) => columnToInfo(n, m)),
+        constraints: {
+            unique: t.constraints.unique,
+            index: t.constraints.index,
+            check: t.constraints.check,
+        },
+    }));
+    const lines = [];
+    if (tables.length === 0) {
+        lines.push('(발견된 테이블이 없습니다. domain/schema/*.ts 에 table(...) 을 export 하세요.)');
+    }
+    else {
+        for (const t of tables) {
+            lines.push(`■ ${t.name}  (db='${t.db}')`);
+            for (const c of t.columns) {
+                const flags = [];
+                if (c.primaryKey)
+                    flags.push('PK');
+                if (c.nullable)
+                    flags.push('null');
+                if (c.hasDefault)
+                    flags.push('default');
+                if (c.hidden)
+                    flags.push('hidden');
+                if (c.unique)
+                    flags.push('unique');
+                if (c.references)
+                    flags.push(`→ ${c.references}`);
+                const flagStr = flags.length > 0 ? `  [${flags.join(', ')}]` : '';
+                lines.push(`  ${c.name.padEnd(24)} ${c.sqlType}${flagStr}`);
+            }
+            const uniq = t.constraints.unique ?? [];
+            const idx = t.constraints.index ?? [];
+            const chk = t.constraints.check ?? [];
+            if (uniq.length > 0)
+                lines.push(`  unique: ${uniq.map((u) => `[${u.join(', ')}]`).join(', ')}`);
+            if (idx.length > 0)
+                lines.push(`  index:  ${idx.map((u) => `[${u.join(', ')}]`).join(', ')}`);
+            if (chk.length > 0)
+                lines.push(`  check:  ${chk.map(([n]) => n).join(', ')}`);
+        }
+        lines.push('');
+        lines.push(`총 ${tables.length}개 테이블`);
+    }
+    return {
+        text: lines.join('\n'),
+        data: { ok: true, tables, total: tables.length },
+        isError: false,
+    };
+}
+// ── 도구 3: run_migration ────────────────────────────────────
+/**
+ * `run_migration` — 스키마 diff 를 계산해 DB 에 적용한다.
+ *
+ * 실제 로직은 `../db/migrate.ts` (M9-D · gaon db migrate) 를 그대로 재사용.
+ * 실 DB 필요(§9) — 목업 없이 진짜 커넥션에 실행한다.
+ *
+ * 인자:
+ *   { db?: string, dryRun?: boolean }
+ *      db     — 커넥션 키(§4.5). 기본 'main'.
+ *      dryRun — true 면 SQL 만 계산·출력, DB 미변경.
+ *
+ * 반환: runDbMigrate 의 결과 그대로(text + json).
+ */
+export async function runMigrationTool(args, cwd) {
+    const dbKey = stringOpt(args, 'db') ?? 'main';
+    const dryRun = boolOpt(args, 'dryRun');
+    try {
+        const r = await runDbMigrate({ cwd, dbKey, json: true, dryRun });
+        return {
+            text: r.text,
+            data: r.json,
+            isError: r.exitCode !== 0,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return errorResult(msg);
+    }
+}
+// ── 도구 4: run_tests ────────────────────────────────────────
+/**
+ * `run_tests` — 프로젝트 테스트를 실 실행한다(§9 · vitest spawn).
+ *
+ * `gaon test` 와 같은 경로를 쓰되, MCP 컨텍스트에서는 stdout 을 파이프로
+ * 캡처해서 결과를 도구 응답에 담아 돌려준다(자식이 종료할 때까지 대기).
+ *
+ * 인자:
+ *   { scope?: 'unit'|'integration'|'all', filter?: string }
+ *      scope  — 기본 'all'
+ *      filter — vitest 위치 인자(파일 패턴 substring)
+ *
+ * 반환:
+ *   data: { exitCode, scope, filter, output }
+ *   text: vitest 자체 출력(사람 UI 그대로)
+ */
+export async function runTestsTool(args, cwd) {
+    const scope = (stringOpt(args, 'scope') ?? 'all');
+    const filter = stringOpt(args, 'filter');
+    if (!['unit', 'integration', 'all'].includes(scope)) {
+        return errorResult(`scope 는 'unit' | 'integration' | 'all' 중 하나여야 합니다. 입력값: '${scope}'`);
+    }
+    // scopeArgs 는 test.ts 와 동일 규칙을 재구성한다 — 순환 import 를 피하려고
+    // 여기서 직접 계산한다(관례는 test.ts scopeArgs 와 정합).
+    const scopeExtras = scope === 'unit'
+        ? ['--exclude', '**/*.integration.test.ts']
+        : scope === 'integration'
+            ? ['integration.test']
+            : [];
+    const passthrough = [...scopeExtras, ...(filter ? [filter] : [])];
+    // 실행 경로: 로컬 vitest 바이너리 우선. 없으면 에러 안내.
+    const vitestBin = join(resolvePath(cwd), 'node_modules', '.bin', 'vitest');
+    if (!existsSync(vitestBin)) {
+        return errorResult(`vitest 가 설치돼 있지 않습니다: ${vitestBin}\n` +
+            `→ 프로젝트에서 \`pnpm add -D vitest\` 후 다시 시도하세요.`);
+    }
+    const child = spawn(vitestBin, ['run', ...passthrough], {
+        cwd,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => {
+        stdout += d.toString('utf8');
+    });
+    child.stderr.on('data', (d) => {
+        stderr += d.toString('utf8');
+    });
+    const exitCode = await new Promise((resolveExit) => {
+        child.on('close', (code) => resolveExit(code ?? 1));
+    });
+    const output = stdout + (stderr ? `\n[stderr]\n${stderr}` : '');
+    return {
+        text: output || `(vitest 출력 없음 · exit ${exitCode})`,
+        data: {
+            ok: exitCode === 0,
+            exitCode,
+            scope,
+            filter: filter ?? null,
+            output,
+        },
+        isError: exitCode !== 0,
+    };
+}
+// ── 도구 5: read_agent_doc ──────────────────────────────────
+/**
+ * `read_agent_doc` — 관례 문서 2층 구조(결정 40)의 카테고리 문서를 조회한다.
+ *
+ * 루트 AGENTS.md(코어) 색인은 "해당 영역 작업 전에 agents/<카테고리>.md 를
+ * 읽어라" 고 지시한다. 파일시스템 접근이 제한된 MCP 클라이언트도 이 지시를
+ * 이행할 수 있도록 문서 조회를 구조화 도구로 노출한다 — grep 대체 원칙
+ * (§7.5.3) 의 문서판.
+ *
+ * 인자:
+ *   { category?: string }  — data·web·frontend·async·realtime·testing·security.
+ *                            생략 시 사용 가능한 카테고리 목록을 반환.
+ */
+export async function readAgentDocTool(args, cwd) {
+    const agentsDir = join(cwd, 'agents');
+    if (!existsSync(agentsDir)) {
+        return errorResult(`agents/ 폴더가 없습니다: ${agentsDir}\n` +
+            `  → 프로젝트 루트에서 실행 중인지 확인하세요. gaon new 스캐폴드는 AGENTS.md 와 agents/*.md 를 함께 생성합니다.`);
+    }
+    const available = readdirSync(agentsDir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => f.slice(0, -'.md'.length))
+        .sort();
+    const category = stringOpt(args, 'category');
+    if (!category) {
+        return {
+            text: `사용 가능한 카테고리: ${available.join(', ')}\n  → read_agent_doc { category: '<이름>' } 으로 원문을 조회하세요.`,
+            data: { ok: true, categories: available },
+            isError: false,
+        };
+    }
+    const file = join(agentsDir, `${category}.md`);
+    if (!existsSync(file)) {
+        return errorResult(`카테고리 문서가 없습니다: agents/${category}.md\n` +
+            `  → 사용 가능한 카테고리: ${available.join(', ')}`, { categories: available });
+    }
+    const body = readFileSync(file, 'utf8');
+    return {
+        text: body,
+        data: { ok: true, category, path: `agents/${category}.md`, contents: body },
+        isError: false,
+    };
+}
+/**
+ * 정본 §12 질문 8 확정 명세 4종을 카탈로그로 제공한다. 순서 = 원문 순서
+ * (라우트 · 스키마 · 마이그레이션 · 테스트).
+ */
+export const TOOLS = [
+    {
+        name: 'list_routes',
+        description: '프로젝트의 모든 앱과 라우트를 나열한다. 인자로 app 을 주면 그 앱만 필터. ' +
+            'apps/<name>/routes.ts 관례를 재사용한다(§3.3).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                app: { type: 'string', description: '앱 이름(예: web, api). 생략 시 전 앱.' },
+            },
+            additionalProperties: false,
+        },
+        run: listRoutesTool,
+    },
+    {
+        name: 'get_schema',
+        description: 'domain/schema/ 의 테이블 정의(§4.1)를 조회한다. 컬럼·타입·제약·커넥션 키(§4.5) 를 함께 낸다. ' +
+            'table 또는 db 인자로 필터 가능.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: '테이블 이름(예: posts). 생략 시 전 테이블.' },
+                db: { type: 'string', description: '커넥션 키(예: main, analytics). 생략 시 전 커넥션.' },
+            },
+            additionalProperties: false,
+        },
+        run: getSchemaTool,
+    },
+    {
+        name: 'run_migration',
+        description: '스키마 desired 상태와 실 DB 를 비교해 마이그레이션을 실 적용한다(§9 실 인프라). ' +
+            'dryRun=true 면 SQL 만 계산·출력하고 DB 는 미변경. db 는 커넥션 키(기본 main).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                db: { type: 'string', description: '커넥션 키(§4.5). 기본 main.' },
+                dryRun: { type: 'boolean', description: 'true 면 SQL 만 계산·출력.' },
+            },
+            additionalProperties: false,
+        },
+        run: runMigrationTool,
+    },
+    {
+        name: 'run_tests',
+        description: '프로젝트 테스트를 실 vitest 로 실행한다(§9). scope 로 unit/integration/all 중 선택, ' +
+            'filter 로 파일 패턴(substring) 을 좁힐 수 있다.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    enum: ['unit', 'integration', 'all'],
+                    description: 'unit=*.test.ts, integration=*.integration.test.ts, all=둘 다. 기본 all.',
+                },
+                filter: { type: 'string', description: 'vitest 위치 인자(파일명 substring).' },
+            },
+            additionalProperties: false,
+        },
+        run: runTestsTool,
+    },
+    {
+        name: 'read_agent_doc',
+        description: '관례 문서 2층 구조(결정 40)의 카테고리 문서(agents/*.md)를 조회한다. ' +
+            'category 생략 시 사용 가능한 카테고리 목록. 해당 영역 작업 전에 반드시 읽는다 — 루트 AGENTS.md 색인 지시.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'data·web·frontend·async·realtime·testing·security 중 하나. 생략 시 목록 반환.',
+                },
+            },
+            additionalProperties: false,
+        },
+        run: readAgentDocTool,
+    },
+];
+/**
+ * 이름으로 도구를 찾는다. 없으면 undefined.
+ */
+export function findTool(name) {
+    return TOOLS.find((t) => t.name === name);
+}
+/**
+ * 앱 관례 검사(진단용) — apps/ 존재만 확인. 도구 실행 전에 조기 종료를 하지 않고,
+ * 각 도구가 자체 관례 검사를 하도록 한다(에러 = 수리 안내 · §7.5.3).
+ * 이 함수는 외부에서 문서 생성용으로만 쓴다(현재 unused 지만 진단 훅 자리).
+ */
+export function projectSummary(cwd) {
+    const root = resolvePath(cwd);
+    return {
+        hasApps: existsSync(join(root, 'apps')) && readdirSync(join(root, 'apps'), { withFileTypes: true }).some((e) => e.isDirectory()),
+        hasSchema: existsSync(join(root, 'domain', 'schema')),
+    };
+}
+// 순환 참조 회피 — pathToFileURL 이 사용됨을 확실히(트리쉐이킹 안전).
+void pathToFileURL;

package/dist/scaffold/app.d.ts

@@ -0,0 +1,5 @@
+import type { ScaffoldFile } from './controller.js';
+/** 이름 유효성 — apps/<name>/ 이 안전하고 URL 프리픽스로도 무리 없는 부분집합. */
+export declare function validateAppName(name: string): void;
+/** 앱 스캐폴드 파일 계획. 순수 함수 — 실제 쓰기는 writeScaffold 가 담당. */
+export declare function appScaffoldFiles(name: string): ScaffoldFile[];

package/dist/scaffold/app.js

@@ -0,0 +1,172 @@
+// @gaonjs/cli · scaffold · app (M9-fix · v0.16 §3 · §13.5 M9)
+//
+// `gaon g app <name>` — 다중 앱 스캐폴드. v0.16 §3 정본:
+//   "필요해지면 gaon g app admin 한 줄로 앱이 늘어난다 — 구조 개편이 없다."
+// 새 앱 이름은 URL 프리픽스가 되며(§3.3, web 은 '/', 그 외는 '/<name>'),
+// 개발 모드에서는 `<이름>.localhost` 로도 접근된다(§3.3 · v0.11 확정).
+//
+// 만드는 파일:
+//   apps/<name>/routes.ts                   (라우트 최소 예제 · health JSON)
+//   apps/<name>/app.config.ts               (관례 이탈용 · 주석뿐인 빈 설정)
+//   apps/<name>/controllers/home.ts         (페이지 + JSON 액션 예제 · E-3)
+//   apps/<name>/pages/Home/Index.vue        (Inertia SPA · pageProps<>() 브리지)
+//   apps/<name>/layouts/Default.vue         (E-5 §2.3 · 파일 존재 = 등록)
+//   apps/<name>/components/.gitkeep         (관례 유지)
+//   apps/<name>/composables/.gitkeep        (E-5 §2.2 · 앱 종속 컴포저블 자리)
+//   apps/<name>/channels/.gitkeep           (M6 · 실시간 채널 자리)
+//
+// 이름 규칙: 영문/숫자로 시작 · 소문자·숫자·-·_ 만. `web` 은 관례상 최초
+// 앱이라 `gaon new` 가 이미 만든다 — 존재하면 여기서 실패한다(중복 스캐폴드
+// 방지 · Rails 관례).
+/** 이름 유효성 — apps/<name>/ 이 안전하고 URL 프리픽스로도 무리 없는 부분집합. */
+export function validateAppName(name) {
+    if (!name) {
+        throw new Error(`앱 이름이 비어 있습니다.\n` +
+            `  → 예: gaon g app admin (apps/admin/ 생성)`);
+    }
+    if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+        throw new Error(`앱 이름에 '/' '\\\\' '..' 는 사용할 수 없습니다: ${name}`);
+    }
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) {
+        throw new Error(`앱 이름은 소문자/숫자로 시작해 소문자·숫자·-·_ 만 씁니다: ${name}\n` +
+            `  → 예: admin · api · marketing`);
+    }
+    // 예약 이름 — URL 프리픽스가 될 이름과 충돌을 피한다.
+    const reserved = new Set([
+        'api', // 관례상 API 앱 이름으로 자주 쓰이나 예약 여부는 후속. v1 은 허용.
+        // 시스템/디자인 예약 슬롯 — 확장 대비.
+        '_gaon',
+        '.gaon',
+        'node_modules',
+        'dist',
+        'build',
+        '__test__',
+    ]);
+    if (reserved.has(name) && name !== 'api') {
+        throw new Error(`앱 이름 '${name}' 은 예약되어 있습니다.`);
+    }
+}
+/** 앱 스캐폴드 파일 계획. 순수 함수 — 실제 쓰기는 writeScaffold 가 담당. */
+export function appScaffoldFiles(name) {
+    validateAppName(name);
+    const files = [];
+    // 1) routes.ts — 관례상 GET / + /health 두 라우트로 시작한다.
+    files.push({
+        path: `apps/${name}/routes.ts`,
+        contents: [
+            `// ${name} 앱 라우트 — apps/${name}/routes.ts (v0.16 §3.3).`,
+            `// 앱 폴더명이 URL 프리픽스가 된다: '/${name}' 아래로 서빙된다.`,
+            `// 개발 모드에서는 '${name}.localhost' 로도 접근된다(§3.3 · v0.11 확정).`,
+            `import { routes } from 'gaonjs/web'`,
+            ``,
+            `export default routes((r) => {`,
+            `  r.get('/', 'home#index')   // GET /${name}/ (또는 http://${name}.localhost/)`,
+            `  r.get('/health', 'home#health') // GET /${name}/health · JSON { ok: true }`,
+            `})`,
+            ``,
+        ].join('\n'),
+    });
+    // 2) app.config.ts — 잘 지은 앱은 거의 비어 있어야 한다(§1.1 ②).
+    files.push({
+        path: `apps/${name}/app.config.ts`,
+        contents: [
+            `// ${name} 앱 설정 — apps/${name}/app.config.ts.`,
+            `// 잘 지은 앱의 app.config.ts 는 거의 비어 있다(v0.16 §1.1 ②).`,
+            `// 관례에서 벗어날 때만 값을 채운다:`,
+            `//   hosts: ['${name}.example.com']  // 도메인 바인딩(개발은 ${name}.localhost 자동)`,
+            `//   session: { cookie: '${name}_session' }  // 세션 옵션 덮어쓰기`,
+            `import { defineAppConfig } from 'gaonjs/config'`,
+            ``,
+            `export default defineAppConfig({})`,
+            ``,
+        ].join('\n'),
+    });
+    // 3) controllers/home.ts — 페이지 + JSON 액션 두 대표 패턴(errata E-3).
+    files.push({
+        path: `apps/${name}/controllers/home.ts`,
+        contents: [
+            `// home 컨트롤러 — apps/${name}/controllers/home.ts.`,
+            `// 페이지 액션(this.render)과 JSON 액션(반환값 = 응답 · errata E-3) 예제.`,
+            `import { controller } from 'gaonjs/web'`,
+            ``,
+            `export default controller({`,
+            `  // GET /${name}/ — Inertia SPA 홈. this.render 는 Vue 페이지로 넘긴다.`,
+            `  async index() {`,
+            `    return this.render('Home/Index', {`,
+            `      app: '${name}',`,
+            `    })`,
+            `  },`,
+            ``,
+            `  // GET /${name}/health — JSON 액션(errata E-3). 반환값이 곧 응답.`,
+            `  async health() {`,
+            `    return { ok: true, app: '${name}' }`,
+            `  },`,
+            `})`,
+            ``,
+        ].join('\n'),
+    });
+    // 4) pages/Home/Index.vue — Inertia 페이지. pageProps 브리지(§6.2).
+    files.push({
+        path: `apps/${name}/pages/Home/Index.vue`,
+        contents: [
+            `<script setup lang="ts">`,
+            `import { pageProps } from 'gaonjs/vue'`,
+            ``,
+            `// home#index 의 render props — Serialized<> 로 넘어온다(§6.2).`,
+            `const props = pageProps<'home#index'>()`,
+            `</script>`,
+            ``,
+            `<template>`,
+            `  <main class="app-home">`,
+            `    <h1>{{ props.app }} 앱</h1>`,
+            `    <p>gaon g app ${name} 이 방금 이 앱을 만들었습니다.</p>`,
+            `    <p>URL 프리픽스: <code>/${name}</code> · 로컬 도메인: <code>http://${name}.localhost</code></p>`,
+            `  </main>`,
+            `</template>`,
+            ``,
+            `<style scoped>`,
+            `.app-home {`,
+            `  max-width: 640px;`,
+            `  margin: 4rem auto;`,
+            `  padding: 0 1rem;`,
+            `  font-family: system-ui, -apple-system, sans-serif;`,
+            `  line-height: 1.6;`,
+            `}`,
+            `</style>`,
+            ``,
+        ].join('\n'),
+    });
+    // 5) layouts/Default.vue — E-5 §2.3 · 파일 존재 = 등록. 앱별 레이아웃.
+    files.push({
+        path: `apps/${name}/layouts/Default.vue`,
+        contents: [
+            `<script setup lang="ts">`,
+            `// ${name} 앱 기본 레이아웃 — apps/${name}/layouts/Default.vue (errata E-5 §2.3).`,
+            `// 파일이 존재하면 이 앱의 모든 페이지에 자동 적용된다(파일 존재 = 등록).`,
+            `</script>`,
+            ``,
+            `<template>`,
+            `  <div class="layout">`,
+            `    <header class="layout-header"><strong>${name}</strong></header>`,
+            `    <slot />`,
+            `  </div>`,
+            `</template>`,
+            ``,
+            `<style scoped>`,
+            `.layout { min-height: 100vh; }`,
+            `.layout-header { padding: 1rem; background: #f6f8fa; border-bottom: 1px solid #e1e4e8; }`,
+            `</style>`,
+            ``,
+        ].join('\n'),
+    });
+    // 6-8) 관례 폴더 유지 — git 이 빈 폴더를 추적하지 않아 .gitkeep 을 둔다.
+    //     components · composables · channels 는 앱이 클수록 자주 채워지는
+    //     세 자리다(E-5 §2.2 · M6 실시간).
+    for (const sub of ['components', 'composables', 'channels']) {
+        files.push({
+            path: `apps/${name}/${sub}/.gitkeep`,
+            contents: '',
+        });
+    }
+    return files;
+}

package/dist/scaffold/controller.js

@@ -18,13 +18,13 @@
  * @param app 대상 앱 폴더(apps/<app>/).
  */
 export function controllerScaffold(names, app) {
-    const { pascal, camel, plural } = names;
+    const { pascal, plural } = names;
     const lines = [
         `// ${plural} 컨트롤러 — gaon g controller (M9-B).`,
         `// 페이지 액션(this.render)과 JSON 액션(반환값=응답 · errata E-3) 예시를 담는다.`,
         `// 응답 종류를 한 컨트롤러에서 섞으면 doctor 가 경고한다(§C) — 규모가 커지면 분리.`,
         `import { controller } from 'gaonjs/web'`,
-        `import { ${pascal} } from '../../../domain/models/${camel}.js'`,
+        `import { ${pascal} } from '../../../domain/models/${pascal}.js'`,
         ``,
         `export default controller({`,
         `  // GET /${plural} — 목록 페이지 (Inertia render).`,