@gaonjs/cli 0.32.0 → 0.34.0

package/dist/generate.js

@@ -16,45 +16,90 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { authUiKitFiles, writeUiKitFiles } from './uikit.js';
+/** 결정 155: 이 스캐폴드가 공개 회원가입을 포함하는가(web 기본 O · 비-web 은 --public 시만). */
+function includesPublicRegistration(opts) {
+    const app = opts.app ?? 'web';
+    return app === 'web' || opts.public === true;
+}
 // ── 템플릿 로드·치환 ───────────────────────────────────────────
 // 템플릿은 이 모듈과 같은 위치의 templates/auth/ 에 있다(빌드가 dist 로 복사).
 const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'auth');
-/** 템플릿 파일을 읽어 토큰을 치환한다. {{APP_NAME}} 는 Vue 의 {{ }} 보간과
- *  겹치지 않는 고정 리터럴이라 단순 replaceAll 로 안전하다. */
-function renderTemplate(name, app) {
+/**
+ * 앱의 URL 프리픽스 — web 은 루트라 '' (URL 앞에 아무것도 안 붙음), 그 외는 '/<app>'
+ * (결정 141 · 12차 W4). 폴더명=프리픽스 관례(§3.3)와 정합. 라우트 **등록** 경로는
+ * 프레임웍이 앱 스코프에서 자동으로 프리픽스를 붙이므로 이 값은 라우트 등록이 아니라
+ * **절대 URL**(form.post·router.delete·Link href·redirect·loginRedirect)에만 쓴다.
+ */
+function urlPrefixFor(app) {
+    return app === 'web' ? '' : `/${app}`;
+}
+/**
+ * 앱의 세션 secret 환경변수명 — web 은 'SESSION_SECRET'(기존), 그 외는
+ * '<APP>_SESSION_SECRET'(결정 141 · 앱별 세션 완전 분리 · session.ts 는 앱마다
+ * secret 이 달라야 분리가 완성된다고 명시). 앱 이름의 비영숫자는 '_' 로 정규화.
+ */
+function sessionSecretEnvFor(app) {
+    if (app === 'web')
+        return 'SESSION_SECRET';
+    return `${app.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_SESSION_SECRET`;
+}
+/** 앱별 개발용 세션 secret 폴백(32자 이상 · 앱마다 다르게). */
+function devSessionSecretFor(app) {
+    return `dev-only-session-secret-${app}-change-me-now!!`;
+}
+/** 결정 155: Login 페이지의 회원가입 링크 — 공개 가입 앱에만 넣는다(시큐어 앱은 뺀다).
+ *  템플릿의 `{{SIGNUP_LINK}}` 자리(8칸 들여쓰기)에 in-place 치환되므로 첫 줄은 들여쓰기 없이. */
+function signupLinkMarkup(app) {
+    return (`<p class="mt-4 text-center text-sm text-muted-foreground">\n` +
+        `          계정이 없으신가요?\n` +
+        `          <Link href="${urlPrefixFor(app)}/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</Link>\n` +
+        `        </p>`);
+}
+/** 템플릿 파일을 읽어 토큰을 치환한다. {{APP_NAME}}·{{URL_PREFIX}}·{{SESSION_SECRET_ENV}}·
+ *  {{SIGNUP_LINK}} 는 Vue 의 {{ }} 보간과 겹치지 않는 고정 리터럴이라 단순 replaceAll 로
+ *  안전하다(결정 141·155). SIGNUP_LINK 는 공개 가입 앱에만 링크를, 시큐어 앱엔 빈 값. */
+function renderTemplate(name, app, includePublic) {
     const raw = readFileSync(join(TEMPLATE_DIR, name), 'utf8');
-    return raw.replaceAll('{{APP_NAME}}', app);
+    return raw
+        .replaceAll('{{APP_NAME}}', app)
+        .replaceAll('{{URL_PREFIX}}', urlPrefixFor(app))
+        .replaceAll('{{SESSION_SECRET_ENV}}', sessionSecretEnvFor(app))
+        .replaceAll('{{SIGNUP_LINK}}', includePublic ? signupLinkMarkup(app) : '');
 }
-/** 템플릿 파일 → 생성 경로 매핑(라우트 제외 — 라우트는 패치로 처리). */
-const TEMPLATES = [
-    { tpl: 'user.schema.ts.tpl', out: () => 'domain/schema/users.ts' },
-    { tpl: 'user.model.ts.tpl', out: () => 'domain/models/User.ts' },
-    { tpl: 'auth.wiring.ts.tpl', out: (a) => `apps/${a}/auth.ts` },
-    { tpl: 'session.controller.ts.tpl', out: (a) => `apps/${a}/controllers/session.ts` },
-    { tpl: 'registration.controller.ts.tpl', out: (a) => `apps/${a}/controllers/registration.ts` },
-    { tpl: 'dashboard.controller.ts.tpl', out: (a) => `apps/${a}/controllers/dashboard.ts` },
-    // 결정 32·46: Vue 페이지 경로 세그먼트는 PascalCase(Route 이름) — 'Auth/'.
-    // examples/blog 정본과 page-filename doctor 규칙에 정합(소문자 'auth/' 는
-    // doctor 가 error 로 잡던 스캐폴드 표류였다 · W10 실측).
-    { tpl: 'Login.vue.tpl', out: (a) => `apps/${a}/pages/Auth/Login.vue` },
-    { tpl: 'Signup.vue.tpl', out: (a) => `apps/${a}/pages/Auth/Signup.vue` },
-    { tpl: 'Dashboard.vue.tpl', out: (a) => `apps/${a}/pages/Dashboard.vue` },
-    // 결정 59: 세션·인증 배선은 app.config.ts — 표준 부팅(gaon dev/serve = wireGaon)이
-    // 소비한다. 과거의 수동 부팅 스캐폴드(app.ts·server.ts)는 두 번째 부팅 경로를
-    // 만들어 One Way 를 깨고, 표준 경로에는 auth 배선이 빠져 currentUser 가 영구
-    // null 이 되는 파손을 남겼다 — 제거했다.
-    { tpl: 'app.config.ts.tpl', out: (a) => `apps/${a}/app.config.ts` },
-];
-/** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다. */
+/** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다.
+ *  결정 155: 공개 가입 여부(includePublic)로 registration·Signup·dashboard 변형을 가른다. */
 export function authScaffoldFiles(opts = {}) {
     const app = opts.app ?? 'web';
-    return TEMPLATES.map(({ tpl, out }) => ({ path: out(app), contents: renderTemplate(tpl, app) }));
+    const includePublic = includesPublicRegistration(opts);
+    const specs = [
+        { tpl: 'user.schema.ts.tpl', out: 'domain/schema/users.ts' },
+        { tpl: 'user.model.ts.tpl', out: 'domain/models/User.ts' },
+        { tpl: 'auth.wiring.ts.tpl', out: `apps/${app}/auth.ts` },
+        { tpl: 'session.controller.ts.tpl', out: `apps/${app}/controllers/session.ts` },
+        // 결정 155: 시큐어(비-web · 비-public) 앱은 역할 게이트 대시보드, 공개 앱은 requireAuth 대시보드.
+        {
+            tpl: includePublic ? 'dashboard.controller.ts.tpl' : 'dashboard.secure.controller.ts.tpl',
+            out: `apps/${app}/controllers/dashboard.ts`,
+        },
+        // 결정 32·46: Vue 페이지 경로 세그먼트는 PascalCase(Route 이름) — 'Auth/'.
+        { tpl: 'Login.vue.tpl', out: `apps/${app}/pages/Auth/Login.vue` },
+        { tpl: 'Dashboard.vue.tpl', out: `apps/${app}/pages/Dashboard.vue` },
+        // 결정 59: 세션·인증 배선은 app.config.ts — 표준 부팅(gaon dev/serve = wireGaon)이 소비한다.
+        { tpl: 'app.config.ts.tpl', out: `apps/${app}/app.config.ts` },
+    ];
+    // 결정 155: 공개 가입 앱만 회원가입 컨트롤러·페이지를 깐다. 시큐어 앱(admin 등)은 빼서
+    // "관리 앱에 공개 가입 + 로그인 고객 200" 위험 기본을 구조적으로 차단한다.
+    if (includePublic) {
+        specs.splice(4, 0, { tpl: 'registration.controller.ts.tpl', out: `apps/${app}/controllers/registration.ts` });
+        specs.push({ tpl: 'Signup.vue.tpl', out: `apps/${app}/pages/Auth/Signup.vue` });
+    }
+    return specs.map(({ tpl, out }) => ({ path: out, contents: renderTemplate(tpl, app, includePublic) }));
 }
 /**
  * 기존 routes.ts 에 세션·회원가입 리소스를 끼워 넣는다. 이미 있으면 null.
  * `routes((r) => {` 콜백 여는 지점 뒤에 두 줄을 삽입한다.
  */
-export function patchRoutes(existing) {
+export function patchRoutes(existing, includePublic = true) {
     if (existing.includes("resource('session')"))
         return null;
     const m = existing.match(/routes\(\s*\(\s*\w+\s*\)\s*=>\s*\{/);
@@ -64,9 +109,10 @@ export function patchRoutes(existing) {
     // dashboard 라우트도 함께 배선한다 — 없으면 스캐폴드 Dashboard.vue 의
     // pageProps<'…:dashboard#show'> 가 라우트 맵에서 해상되지 않아 vue-tsc 가
     // 깨진다(결정 60 클린룸 실측 — gaon new 프로젝트에 g auth 를 얹는 경로).
+    // 결정 155: 회원가입 리소스는 공개 가입 앱에만(시큐어 앱은 빼서 공개 가입 라우트 자체를 안 깐다).
     const inject = "\n  r.get('/dashboard', 'dashboard#show') // 보호 페이지 (gaon g auth)" +
         "\n  r.resource('session') // 로그인/로그아웃 (gaon g auth)" +
-        "\n  r.resource('registration') // 회원가입 (gaon g auth)";
+        (includePublic ? "\n  r.resource('registration') // 회원가입 (gaon g auth)" : '');
     return existing.slice(0, insertAt) + inject + existing.slice(insertAt);
 }
 /**
@@ -76,18 +122,30 @@ export function patchRoutes(existing) {
  *  · defineAppConfig 객체 리터럴을 못 찾으면 null (안전 · 상위에서 경고 폴백).
  * 성공 시 loadUser import 도 함께 보장한다.
  */
-export function patchAppConfigAddAuth(existing) {
+export function patchAppConfigAddAuth(existing, app = 'web') {
     if (/\bauth\s*:/.test(existing))
         return null;
     const m = existing.match(/defineAppConfig\(\s*\{/);
     if (!m || m.index === undefined)
         return null;
     const insertAt = m.index + m[0].length;
-    let out = existing.slice(0, insertAt) +
-        "\n  // 결정 59: 세션 userId → 사용자 로드 배선(g auth). 이게 있어야 로그인 후" +
-        "\n  // this.currentUser / this.requireAuth() 가 실제 사용자를 받는다." +
-        "\n  auth: { loadUser, loginRedirect: '/session/new' }," +
-        existing.slice(insertAt);
+    const prefix = urlPrefixFor(app);
+    // 결정 141(12차 W4): 대상 앱에 세션이 없으면(예: gaon g app 이 만든 빈 config)
+    // 세션도 함께 배선한다 — 세션이 없으면 로그인이 저장될 곳이 없어 왕복이 깨지고,
+    // doctor 가 세션/CSRF 누락을 error 로 잡는다(결정 140). secret 은 앱별로 분리한다.
+    const hasSession = /\bsession\s*:/.test(existing);
+    const lines = [];
+    if (!hasSession) {
+        const secretEnv = sessionSecretEnvFor(app);
+        lines.push(`  // 세션 secret 은 32자 이상 — .env 의 ${secretEnv} 로 주입한다(앱별 세션 완전 분리).`, `  session: { secret: process.env.${secretEnv} ?? '${devSessionSecretFor(app)}' },`);
+    }
+    lines.push('  // 결정 59: 세션 userId → 사용자 로드 배선(g auth). 이게 있어야 로그인 후', '  // this.currentUser / this.requireAuth() 가 실제 사용자를 받는다.', `  auth: { loadUser, loginRedirect: '${prefix}/session/new' },`);
+    // 결정 141: 닫는 괄호 오염 방지 — 빈 `defineAppConfig({})` 처럼 삽입 지점 바로 뒤가
+    // 닫는 `}` 면 삽입 블록 끝에 개행을 더해 `})` 를 제 줄로 내린다(`},})` 방지).
+    const rest = existing.slice(insertAt);
+    const closesImmediately = /^\s*\}/.test(rest);
+    const block = '\n' + lines.join('\n') + (closesImmediately ? '\n' : '');
+    let out = existing.slice(0, insertAt) + block + rest;
     // loadUser import 보장 — gaonjs/config import 바로 뒤에 넣는다.
     if (!/from\s+['"]\.\/auth\.js['"]/.test(out)) {
         const im = out.match(/import\s+\{[^}]*\}\s+from\s+['"]gaonjs\/config['"][^\n]*\n/);
@@ -113,6 +171,7 @@ export function writeAuthScaffold(cwd, opts = {}) {
     // 필요한 최소 세트를 먼저 보장한다 — 이미 있으면(gaon g ui-kit 를 먼저 돌린
     // 경우) skip, 없으면 생성. 이 보장이 없으면 스캐폴드 직후 페이지가 컴포넌트를
     // 해상하지 못해 vue-tsc 가 깨진다(gaon new → g auth 단독 경로 · 결정 60 게이트).
+    const includePublic = includesPublicRegistration(opts);
     const ui = writeUiKitFiles(root, authUiKitFiles(app));
     created.push(...ui.created);
     skipped.push(...ui.skipped);
@@ -124,7 +183,7 @@ export function writeAuthScaffold(cwd, opts = {}) {
             // 결정 59: auth 배선이 없으면 로그인 후에도 currentUser 가 영구 null 이다.
             if (file.path === `apps/${app}/app.config.ts`) {
                 const existing = readFileSync(abs, 'utf8');
-                const patchedConfig = patchAppConfigAddAuth(existing);
+                const patchedConfig = patchAppConfigAddAuth(existing, app);
                 if (patchedConfig) {
                     writeFileSync(abs, patchedConfig, 'utf8');
                     patched.push(file.path);
@@ -134,7 +193,8 @@ export function writeAuthScaffold(cwd, opts = {}) {
                     skipped.push(file.path);
                     warnings.push(`apps/${app}/app.config.ts 가 이미 있어 인증 배선을 자동 추가하지 못했습니다.\n` +
                         `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
-                        `   auth: { loadUser, loginRedirect: '/session/new' }  // import { loadUser } from './auth.js'\n` +
+                        `   session: { secret: process.env.${sessionSecretEnvFor(app)} ?? '32자 이상 비밀' },\n` +
+                        `   auth: { loadUser, loginRedirect: '${urlPrefixFor(app)}/session/new' }  // import { loadUser } from './auth.js'\n` +
                         `→ 이 배선이 없으면 로그인해도 this.currentUser/requireAuth() 가 사용자를 받지 못합니다.`);
                 }
                 else {
@@ -154,7 +214,7 @@ export function writeAuthScaffold(cwd, opts = {}) {
     const routesPath = join(root, 'apps', app, 'routes.ts');
     const routesRel = `apps/${app}/routes.ts`;
     if (existsSync(routesPath)) {
-        const patchedContent = patchRoutes(readFileSync(routesPath, 'utf8'));
+        const patchedContent = patchRoutes(readFileSync(routesPath, 'utf8'), includePublic);
         if (patchedContent) {
             writeFileSync(routesPath, patchedContent, 'utf8');
             patched.push(routesRel);
@@ -165,18 +225,27 @@ export function writeAuthScaffold(cwd, opts = {}) {
     }
     else {
         mkdirSync(dirname(routesPath), { recursive: true });
-        writeFileSync(routesPath, renderTemplate('routes.ts.tpl', app), 'utf8');
+        writeFileSync(routesPath, renderTemplate('routes.ts.tpl', app, includePublic), 'utf8');
         created.push(routesRel);
     }
+    // 결정 155: 시큐어 앱(공개 가입 미생성)은 역할 게이트 대시보드를 깔았다 — role 컬럼을
+    // 두라고 안내한다(§7.5.3 · authorize 예시가 실제 역할 규칙이 되도록).
+    if (!includePublic) {
+        warnings.push(`apps/${app}/ 는 시큐어 스캐폴드입니다(공개 회원가입 미생성 · 결정 155).\n` +
+            `→ 관리자는 직접 만들거나 승격하세요(공개 가입 라우트 없음). 공개 가입이 필요하면 --public 로 다시 생성.\n` +
+            `→ 역할 인가를 완성하려면 domain/schema/users.ts 에 role 컬럼을 추가하세요:\n` +
+            `   role: t.string().default('user'),\n` +
+            `   그러면 apps/${app}/controllers/dashboard.ts 의 authorize(역할) 게이트가 실제 역할로 동작합니다.`);
+    }
     return { created: created.sort(), skipped: skipped.sort(), patched: patched.sort(), warnings };
 }
 /** `gaon g auth` 진입점. 스캐폴드를 쓰고 결과를 사람/JSON 으로 출력한다. */
 export function runGenerateAuthCommand(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const app = opts.app ?? 'web';
-    const result = writeAuthScaffold(cwd, { app });
+    const result = writeAuthScaffold(cwd, { app, public: opts.public });
     if (opts.json) {
-        process.stdout.write(JSON.stringify({ command: 'g auth', app, ...result }, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ command: 'g auth', app, public: opts.public ?? app === 'web', ...result }, null, 2) + '\n');
         return 0;
     }
     const lines = [''];
@@ -191,11 +260,13 @@ export function runGenerateAuthCommand(opts = {}) {
     for (const w of result.warnings)
         lines.push('', `  ⚠ ${w.split('\n').join('\n  ')}`);
     lines.push('');
+    const prefix = urlPrefixFor(app);
+    const secretEnv = sessionSecretEnvFor(app);
     lines.push('  다음 단계:');
-    lines.push('   1) .env 에 REDIS_URL·SESSION_SECRET(32자 이상)·COOKIE_SECRET 을 설정한다.');
+    lines.push(`   1) .env 에 REDIS_URL·${secretEnv}(32자 이상)·COOKIE_SECRET 을 설정한다.`);
     lines.push('   2) gaon db diff && gaon db migrate 로 users 테이블을 만든다.');
     lines.push('   3) gaon dev 로 실행한다 (.gaon 타입 브리지 생성 + 세션·인증 자동 배선).');
-    lines.push('   → /registration/new 회원가입 · /session/new 로그인 · /dashboard 보호 페이지 (this.requireAuth()).');
+    lines.push(`   → ${prefix}/registration/new 회원가입 · ${prefix}/session/new 로그인 · ${prefix}/dashboard 보호 페이지 (this.requireAuth()).`);
     lines.push('');
     process.stdout.write(lines.join('\n') + '\n');
     return 0;

package/dist/index.d.ts

@@ -4,6 +4,9 @@ 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 { runCheckCommand, type CheckCommandOptions, type CheckStep, type CheckStepStatus, type CheckStepResult, } from "./commands/check.js";
 export { runGenCommand, regenerateProjectGaon, type GenCommandOptions, type GenResult, } from "./commands/gen.js";
+export { runBuildCommand, type BuildCommandOptions, type BuildCommandResult, } from "./commands/build.js";
+export { buildApp, buildAllApps, listFrontendApps, verifyAppDist, appBase, type BuildAppOptions, type DistVerifyResult, } from "./dev/build.js";
+export { generateMessagesDts } from "./messages-gen.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";

package/dist/index.js

@@ -14,6 +14,7 @@ import { MILESTONES, VERSION, HOMEPAGE, loadDotEnv } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
 import { runCheckCommand } from "./commands/check.js";
 import { runGenCommand } from "./commands/gen.js";
+import { runBuildCommand } from "./commands/build.js";
 import { runNewCommand } from "./commands/new.js";
 import { runConsoleCommand } from "./commands/console.js";
 import { runTestCommand } from "./commands/test.js";
@@ -32,6 +33,9 @@ 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 { runGenCommand, regenerateProjectGaon, } from "./commands/gen.js";
+export { runBuildCommand, } from "./commands/build.js";
+export { buildApp, buildAllApps, listFrontendApps, verifyAppDist, appBase, } from "./dev/build.js";
+export { generateMessagesDts } from "./messages-gen.js";
 export { runNewCommand } from "./commands/new.js";
 export { runConsoleCommand } from "./commands/console.js";
 export { runTestCommand } from "./commands/test.js";
@@ -100,8 +104,9 @@ function renderHelp(version = VERSION) {
         "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
         "    gaon serve --port <n> --host <h>   리슨 포트·호스트 (config 값을 덮음)",
         "    gaon serve --workers <n|auto>      node:cluster 워커 다중화 (env WEB_CONCURRENCY · 기본 1)",
-        "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
+        "    gaon check         typecheck · vue-tsc · build · doctor 통합 검사 (--only <step> · --no-doctor)",
         "    gaon gen           .gaon 타입 브리지 + api() 런타임 매니페스트만 재생성 (서버·검사 없이 · build 전제 · --json)",
+        "    gaon build         멀티 앱 프론트 프로덕션 빌드 (gaon gen + apps/* 순회 · 앱별 dist/<앱>·base=/<앱>/ · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
         "    gaon doctor        정적 검사 (25 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계)",
@@ -220,8 +225,8 @@ export function runCli(argv, opts = {}) {
         return;
     }
     // `gaon check` — typecheck · vue-tsc · build (·doctor) 통합 검사(M9-G).
-    // package.json 스크립트 관례 재사용. --only <step> 로 단일 단계, --include-doctor
-    // 로 doctor 포함. 종료 코드로 결과 전달.
+    // package.json 스크립트 관례 재사용. --only <step> 로 단일 단계. 결정 157: doctor 는
+    // 기본 포함(규칙 5 등이 check 만 도는 CI 에서 새지 않게) · --no-doctor 로만 뺀다.
     if (argv[0] === "check") {
         const knownSteps = ["typecheck", "vue-tsc", "build", "doctor"];
         const onlyIdx = argv.indexOf("--only");
@@ -232,7 +237,7 @@ export function runCli(argv, opts = {}) {
         void runCheckCommand({
             json: argv.includes("--json"),
             only,
-            includeDoctor: argv.includes("--include-doctor"),
+            noDoctor: argv.includes("--no-doctor"),
         })
             .then((code) => {
             process.exitCode = code;
@@ -258,6 +263,20 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon build` — 멀티 앱 프론트 프로덕션 빌드(결정 146). gaon gen 뒤 apps/* 를
+    // 순회해 앱마다 root/outDir/base 로 vite build. 스캐폴드 build 스크립트가 이걸 부른다.
+    if (argv[0] === "build") {
+        void runBuildCommand({ json: argv.includes("--json") })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon build 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon doctor` — 정적 검사(M9-E · 17 검사). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
@@ -377,7 +396,8 @@ export function runCli(argv, opts = {}) {
         if (argv[1] === "auth") {
             const appIdx = argv.indexOf("--app");
             const app = appIdx >= 0 ? argv[appIdx + 1] : undefined;
-            const code = runGenerateAuthCommand({ app, json: argv.includes("--json") });
+            // 결정 155: --public 은 비-web 앱도 공개 회원가입을 opt-in(공개 비-web 앱 탈출구).
+            const code = runGenerateAuthCommand({ app, json: argv.includes("--json"), public: argv.includes("--public") });
             process.exitCode = code;
             return;
         }

package/dist/messages-gen.d.ts

@@ -0,0 +1,6 @@
+/**
+ * locales/ 카탈로그에서 .gaon/messages.d.ts 를 생성한다. 카탈로그가 없거나 비어
+ * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
+ * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ */
+export declare function generateMessagesDts(localesDir: string, out: string): boolean;

package/dist/messages-gen.js

@@ -0,0 +1,24 @@
+// @gaonjs/cli · .gaon/messages.d.ts 생성기 (결정 158 · 13차 W2)
+//
+// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 세 번째 축(메시지). locales/
+// 카탈로그의 키를 유니온 타입으로 물성화해, t('key') 의 존재하지 않는 키를 컴파일
+// 타임에 잡는다(현재는 GaonMessages 가 비어 있어 키가 string 으로 열림). 생성 파일은
+// 타입만 담는다(규칙 3). @gaonjs/i18n 의 공개 API(loadLocales·renderMessagesDts)만 쓴다.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
+/**
+ * locales/ 카탈로그에서 .gaon/messages.d.ts 를 생성한다. 카탈로그가 없거나 비어
+ * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
+ * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ */
+export function generateMessagesDts(localesDir, out) {
+    if (!existsSync(localesDir))
+        return false;
+    const resources = loadLocales(localesDir);
+    if (Object.keys(resources).length === 0)
+        return false;
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, renderMessagesDts(resources), 'utf8');
+    return true;
+}

package/dist/scaffold/app.js

@@ -72,9 +72,10 @@ export function appScaffoldFiles(name) {
         contents: [
             `// ${name} 앱 설정 — apps/${name}/app.config.ts.`,
             `// 잘 지은 앱의 app.config.ts 는 거의 비어 있다(v0.16 §1.1 ②).`,
+            `// 세션·인증 배선은 \`gaon g auth --app ${name}\` 이 여기에 채운다 — 직접 손대지 않는다.`,
+            `// 그 전에 상태 변경(POST 등) 라우트를 두면 doctor 가 세션/CSRF 누락을 잡는다(결정 140).`,
             `// 관례에서 벗어날 때만 값을 채운다:`,
             `//   hosts: ['${name}.example.com']  // 도메인 바인딩(개발은 ${name}.localhost 자동)`,
-            `//   session: { cookie: '${name}_session' }  // 세션 옵션 덮어쓰기`,
             `import { defineAppConfig } from 'gaonjs/config'`,
             ``,
             `export default defineAppConfig({})`,

package/dist/templates/auth/Dashboard.vue.tpl

@@ -13,10 +13,10 @@ import Button from '@shared/components/ui/Button.vue'
 // 이 페이지는 requireAuth 로 보호되므로 런타임엔 항상 로그인 상태(타입은 nullable).
 const shared = useShared()
 
-// 로그아웃 = DELETE /session (r.resource('session') 의 destroy).
+// 로그아웃 = DELETE {{URL_PREFIX}}/session (r.resource('session') 의 destroy).
 // HTML <form> 은 DELETE 를 못 보내므로 Inertia 라우터로 실제 메서드를 보낸다(결정 64).
 function logout(): void {
-  router.delete('/session', { headers: { 'x-csrf-token': shared.csrf } })
+  router.delete('{{URL_PREFIX}}/session', { headers: { 'x-csrf-token': shared.csrf } })
 }
 </script>
 

package/dist/templates/auth/Login.vue.tpl

@@ -36,7 +36,7 @@ const form = useForm({ email: '', password: '', _csrf: shared.csrf })
         <Alert v-if="props.error" variant="destructive" class="mb-4">
           <AlertDescription>{{ props.error }}</AlertDescription>
         </Alert>
-        <Form @submit="form.post('/session')">
+        <Form @submit="form.post('{{URL_PREFIX}}/session')">
           <FormField label="이메일" :error="form.errors.email">
             <Input v-model="form.email" type="email" required />
           </FormField>
@@ -45,10 +45,7 @@ const form = useForm({ email: '', password: '', _csrf: shared.csrf })
           </FormField>
           <Button type="submit" class="w-full" :disabled="form.processing">로그인</Button>
         </Form>
-        <p class="mt-4 text-center text-sm text-muted-foreground">
-          계정이 없으신가요?
-          <Link href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</Link>
-        </p>
+        {{SIGNUP_LINK}}
       </CardContent>
     </Card>
   </div>

package/dist/templates/auth/Signup.vue.tpl

@@ -33,7 +33,7 @@ const form = useForm({ name: '', email: '', password: '', _csrf: shared.csrf })
         <Alert v-if="props.error" variant="destructive" class="mb-4">
           <AlertDescription>{{ props.error }}</AlertDescription>
         </Alert>
-        <Form @submit="form.post('/registration')">
+        <Form @submit="form.post('{{URL_PREFIX}}/registration')">
           <FormField label="이름" :error="form.errors.name">
             <Input v-model="form.name" required />
           </FormField>
@@ -47,7 +47,7 @@ const form = useForm({ name: '', email: '', password: '', _csrf: shared.csrf })
         </Form>
         <p class="mt-4 text-center text-sm text-muted-foreground">
           이미 계정이 있으신가요?
-          <Link href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</Link>
+          <Link href="{{URL_PREFIX}}/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</Link>
         </p>
       </CardContent>
     </Card>

package/dist/templates/auth/app.config.ts.tpl

@@ -3,9 +3,9 @@ import { defineAppConfig } from 'gaonjs/config'
 import { loadUser } from './auth.js'
 
 export default defineAppConfig({
-  // 세션 secret 은 32자 이상 — .env 의 SESSION_SECRET 로 주입한다.
-  session: { secret: process.env.SESSION_SECRET ?? 'dev-only-session-secret-change-me-now!!' },
+  // 세션 secret 은 32자 이상 — .env 의 {{SESSION_SECRET_ENV}} 로 주입한다(앱별 세션 완전 분리).
+  session: { secret: process.env.{{SESSION_SECRET_ENV}} ?? 'dev-only-session-secret-{{APP_NAME}}-change-me!!' },
   // 결정 59: 세션 userId → 사용자 로드 배선. 이게 있어야 로그인 후
   // this.currentUser / this.requireAuth() 가 실제 사용자를 받는다.
-  auth: { loadUser, loginRedirect: '/session/new' },
+  auth: { loadUser, loginRedirect: '{{URL_PREFIX}}/session/new' },
 })

package/dist/templates/auth/dashboard.controller.ts.tpl

@@ -2,7 +2,7 @@
 import { controller } from 'gaonjs/web'
 
 export default controller({
-  // GET /dashboard — 로그인해야 볼 수 있는 보호 페이지. 비로그인은 로그인으로 보내진다.
+  // GET {{URL_PREFIX}}/dashboard — 로그인해야 볼 수 있는 보호 페이지. 비로그인은 로그인으로 보내진다.
   async show() {
     // 보호만 하고 페이지 데이터는 넘기지 않는다 — 사용자·csrf 는 자동 주입되고
     // (결정 116), 페이지는 useShared() 로 읽는다. requireAuth 로 게이트만 건다.

package/dist/templates/auth/dashboard.secure.controller.ts.tpl

@@ -0,0 +1,14 @@
+// 보호 라우트 예시(관리 앱) — gaon g auth --app {{APP_NAME}}. 로그인 + 역할로 지킨다(§7 · 결정 145·155).
+import { controller } from 'gaonjs/web'
+
+export default controller({
+  // GET {{URL_PREFIX}}/dashboard — 로그인만으론 부족한 관리 화면. 역할(role)로 인가한다.
+  async show() {
+    const user = this.requireAuth() // 인증(401): 로그인 여부
+    // 인가(403): 로그인한 일반 사용자는 막는다. domain/schema/users.ts 에 role 컬럼을 두고
+    // (예: role: t.string().default('user')) 아래를 실제 역할 규칙으로 바꾸세요.
+    // 지금은 role !== 'admin' 이면 403 — 관리 앱에 로그인 고객이 들어오는 위험 기본을 막는다.
+    this.authorize((user as { role?: string }).role === 'admin')
+    return this.render('Dashboard', {})
+  },
+})

package/dist/templates/auth/registration.controller.ts.tpl

@@ -3,11 +3,11 @@ import { controller, hashPassword } from 'gaonjs/web'
 import { User } from '../../../domain/models/User.js'
 
 export default controller({
-  // GET /registration/new — 회원가입 폼. csrf 는 자동 주입된다(결정 116).
+  // GET {{URL_PREFIX}}/registration/new — 회원가입 폼. csrf 는 자동 주입된다(결정 116).
   async new() {
     return this.render('Auth/Signup', { error: null as string | null })
   },
-  // POST /registration — 회원가입
+  // POST {{URL_PREFIX}}/registration — 회원가입
   async create() {
     const { name, email, password } = this.params({
       _row: {} as { name: string; email: string; password: string },
@@ -15,6 +15,6 @@ export default controller({
     const passwordDigest = await hashPassword(password)
     const user = await User.create({ name, email, passwordDigest })
     this.auth.login(user)
-    return this.redirect('/dashboard')
+    return this.redirect('{{URL_PREFIX}}/dashboard')
   },
 })

package/dist/templates/auth/session.controller.ts.tpl

@@ -3,26 +3,26 @@ import { controller, verifyPassword } from 'gaonjs/web'
 import { User } from '../../../domain/models/User.js'
 
 export default controller({
-  // GET /session/new — 로그인 폼. csrf 는 자동 주입되므로 넘기지 않는다(결정 116).
+  // GET {{URL_PREFIX}}/session/new — 로그인 폼. csrf 는 자동 주입되므로 넘기지 않는다(결정 116).
   async new() {
     return this.render('Auth/Login', { error: null as string | null })
   },
-  // POST /session — 로그인
+  // POST {{URL_PREFIX}}/session — 로그인
   async create() {
     const { email, password } = this.params({ _row: {} as { email: string; password: string } })
     const user = await User.where('email', '=', email).first()
     // passwordDigest 는 hidden 이지만 서버 코드에서는 투명하게 읽힌다(§4.2).
     if (user && (await verifyPassword(password, user.passwordDigest))) {
       this.auth.login(user)
-      return this.redirect('/dashboard')
+      return this.redirect('{{URL_PREFIX}}/dashboard')
     }
     return this.render('Auth/Login', {
       error: '이메일 또는 비밀번호가 올바르지 않습니다.' as string | null,
     })
   },
-  // DELETE /session — 로그아웃
+  // DELETE {{URL_PREFIX}}/session — 로그아웃
   async destroy() {
     this.auth.logout()
-    return this.redirect('/session/new')
+    return this.redirect('{{URL_PREFIX}}/session/new')
   },
 })

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

@@ -18,6 +18,12 @@ STORAGE_BUCKET={{PROJECT_NAME}}
 STORAGE_ACCESS_KEY={{PROJECT_NAME}}
 STORAGE_SECRET_KEY={{PROJECT_NAME}}_secret
 
+# 메일(§7 · M8) — docker-compose.yaml 의 mailpit 서비스와 정합(dev = MailPit sink · UI :8025).
+# 운영은 실 SMTP 호스트·자격증명·SMTP_SECURE=true 로 교체한다.
+SMTP_HOST=127.0.0.1
+SMTP_PORT=1025
+MAIL_FROM=no-reply@{{PROJECT_NAME}}.test
+
 # 세션 · 쿠키 서명 비밀 (32자 이상, 운영은 반드시 교체).
 SESSION_SECRET=change-me-to-a-32-char-random-secret!!
 COOKIE_SECRET=change-me-too-32-char-random-secret!!

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

@@ -27,6 +27,8 @@ v0.15+errata→v0.16→v0.17 · 결정 31~89)이며, 관례 문서는 **2층 구
 | 잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄 | `agents/async.md` |
 | 채널 · 프레즌스 · 허브 | `agents/realtime.md` |
 | 파일 스토리지 (`Storage.put/url` · s3Disk · presigned · CSP 자동 배선) | `agents/storage.md` |
+| 다국어 (`t()` · 카탈로그 · 요청별 로케일 · `this.setLocale` · 메시지 키 타입) | `agents/i18n.md` |
+| 메일 (`mail()` · `deliver(data, { locale })` · MailPit · 발송 경로) | `agents/mail.md` |
 | 테스트 작성·실행 (실 인프라 · `expectJobProcessed`) | `agents/testing.md` |
 | 보안 기본값 · 탈출구(v-html · raw SQL) 사용 | `agents/security.md` |
 | 페이로드 봉인 (`@gaonjs/seal` · wire/문서/WS 암호화 · 선택 플러그인) | `agents/seal.md` |
@@ -191,7 +193,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 작업마다 실행한다:
 
 ```bash
-gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
+gaon check        # .gaon 재생성 → typecheck + vue-tsc + build + doctor (기본 포함 · --no-doctor 로 뺌 · 결정 157)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
 gaon doctor       # 정적 검사 24종 (§2.2)
 ```

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

@@ -84,7 +84,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 ## 3. 개발 검증 루프 (작업마다 실행)
 
 ```bash
-gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
+gaon check                        # .gaon 재생성 → 타입검사+build+doctor (CI 한 번에 · --no-doctor 로 doctor 뺌)
 gaon doctor                       # 정적 검사 24종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```