@gaonjs/cli 0.32.0 → 0.33.0

package/dist/commands/build.d.ts

@@ -0,0 +1,11 @@
+export interface BuildCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+}
+export interface BuildCommandResult {
+    readonly ok: boolean;
+    readonly apps: string[];
+    readonly error?: string;
+}
+/** `gaon build` 진입점. .gaon 재생성 + 전 앱 vite build. */
+export declare function runBuildCommand(opts?: BuildCommandOptions): Promise<number>;

package/dist/commands/build.js

@@ -0,0 +1,49 @@
+// @gaonjs/cli · `gaon build` — 멀티 앱 프론트 프로덕션 빌드 (결정 146 · 12차 W2)
+//
+// `gaon gen`(.gaon 재생성) 뒤 apps/* 를 순회해 앱마다 root=apps/<앱>·outDir=dist/<앱>·
+// base=/<앱>/ 로 vite build 한다. 예전 스캐폴드 build 스크립트(`gaon gen && vite build`)는
+// apps/web 하나만 빌드해 둘째 앱(admin)의 dist 가 안 생기거나 base 없이 404 였다 —
+// gaon g app 으로 늘린 앱이 별도 손배선 없이 빌드 파이프라인에 자동 편입되게 한다.
+import { regenerateProjectGaon } from './gen.js';
+import { buildAllApps, listFrontendApps } from '../dev/build.js';
+/** `gaon build` 진입점. .gaon 재생성 + 전 앱 vite build. */
+export async function runBuildCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const log = (line) => {
+        if (!json)
+            process.stdout.write(line + '\n');
+    };
+    try {
+        // 1) .gaon 재생성 — build 산출이 routes.manifest 값 import 를 타므로 fresh 여야 한다(규칙 3).
+        await regenerateProjectGaon(cwd);
+        // 2) 프론트 앱이 없으면(API 전용) 조용히 통과.
+        const apps = await listFrontendApps(cwd);
+        if (apps.length === 0) {
+            const result = { ok: true, apps: [] };
+            if (json)
+                process.stdout.write(JSON.stringify({ command: 'build', ...result }) + '\n');
+            else
+                log('빌드할 프론트 앱(apps/<앱>/index.html)이 없습니다 — 건너뜁니다.');
+            return 0;
+        }
+        // 3) 앱별 빌드.
+        log(`gaon build — ${apps.length}개 앱: ${apps.join(', ')}`);
+        await buildAllApps(cwd, { onLog: json ? undefined : (l) => process.stdout.write(l + '\n') });
+        const result = { ok: true, apps };
+        if (json)
+            process.stdout.write(JSON.stringify({ command: 'build', ...result }) + '\n');
+        else
+            log(`✓ 빌드 완료 — ${apps.map((a) => `dist/${a}`).join(' · ')}`);
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const result = { ok: false, apps: [], error: msg };
+        if (json)
+            process.stdout.write(JSON.stringify({ command: 'build', ...result }) + '\n');
+        else
+            process.stderr.write(`✗ gaon build 실패: ${msg}\n`);
+        return 1;
+    }
+}

package/dist/commands/check.js

@@ -33,6 +33,7 @@ import { generateRoutesDts } from '@gaonjs/web';
 import { runDoctorCommand } from '../doctor.js';
 import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
+import { listFrontendApps, verifyAppDist } from '../dev/build.js';
 /**
  * 프로젝트 스크립트 존재 여부. pnpm/npm 어느 쪽이든 `scripts.<name>` 을
  * 정의해 두면 우선 사용한다.
@@ -78,6 +79,17 @@ async function runStep(step, cwd) {
         const cmd = 'pnpm';
         const args = ['run', scriptName];
         const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        // 결정 146(12차 W2): build 가 성공했으면 **등록된 앱마다** dist/<앱>/index.html 과
+        // 그 문서가 참조하는 에셋이 실제로 존재하는지 검증한다. build 스크립트가 통과해도
+        // 둘째 앱(admin)의 dist 가 안 생기거나 에셋이 404 면 여기서 잡는다("build passed 인데
+        // /admin 은 빈 화면" 사각 제거 · curl data-page 만으로 못 보던 지점).
+        if (step === 'build' && exitCode === 0) {
+            const verify = await verifyBuildOutput(cwd);
+            if (!verify.ok) {
+                return { step, status: 'failed', command: `${cmd} ${args.join(' ')}`, exitCode, output: output + '\n' + verify.message };
+            }
+            return { step, status: 'passed', command: `${cmd} ${args.join(' ')}`, exitCode, output: output + '\n' + verify.message };
+        }
         return {
             step,
             status: exitCode === 0 ? 'passed' : 'failed',
@@ -159,6 +171,35 @@ async function runStep(step, cwd) {
             '→ 프론트 프로덕션 빌드를 검사에 포함하려면 package.json 에 "build": "vite build" 를 정의하세요.',
     };
 }
+/**
+ * build 산출 검증(결정 146 · 12차 W2). 등록된 프론트 앱마다 dist/<앱>/index.html 과
+ * 그 문서가 참조하는 로컬 에셋이 존재하는지 확인한다. 하나라도 빠지면 ok=false.
+ */
+async function verifyBuildOutput(cwd) {
+    const apps = await listFrontendApps(cwd);
+    if (apps.length === 0)
+        return { ok: true, message: '프론트 앱이 없어 dist 검증을 건너뜁니다.' };
+    const problems = [];
+    const okApps = [];
+    for (const app of apps) {
+        const r = await verifyAppDist(cwd, app);
+        if (!r.indexExists) {
+            problems.push(`✗ apps/${app}: dist/${app}/index.html 이 없습니다 — 이 앱이 빌드되지 않았습니다.\n` +
+                `  → build 가 apps/${app} 를 순회 빌드하는지 확인하세요(gaon build · 결정 146).`);
+        }
+        else if (r.missing.length > 0) {
+            problems.push(`✗ apps/${app}: index.html 이 참조하는 에셋이 dist/${app} 에 없습니다: ${r.missing.join(', ')}\n` +
+                `  → base(${app === 'web' ? '/' : `/${app}/`}) 주입이 빠졌을 수 있습니다(비-루트 앱은 /<앱>/ base 필요).`);
+        }
+        else {
+            okApps.push(app);
+        }
+    }
+    if (problems.length > 0) {
+        return { ok: false, message: `build 산출 검증 실패(결정 146):\n${problems.join('\n')}` };
+    }
+    return { ok: true, message: `build 산출 검증 통과 — 앱별 dist: ${okApps.map((a) => `dist/${a}`).join(' · ')}` };
+}
 /** doctor 는 이미 있는 명령을 재사용 — cwd 만 넘긴다. json 은 상위에서. */
 async function runDoctorStep(cwd) {
     try {

package/dist/dev/build.d.ts

@@ -0,0 +1,34 @@
+/** 앱의 URL base — web 은 루트('/'), 그 외는 '/<app>/'(결정 146). vite build 시 주입. */
+export declare function appBase(app: string): string;
+/** apps/* 중 프론트 진입(index.html)이 있는 앱 이름들. web 을 먼저(루트 앱 관례). */
+export declare function listFrontendApps(cwd: string): Promise<string[]>;
+/** vite.config 를 프로젝트 루트·앱 루트 순으로 찾는다(configFile 명시용 · vue 플러그인 보장). */
+export declare function findViteConfig(cwd: string, appRoot: string): string | undefined;
+export interface BuildAppOptions {
+    /** watch 모드(dev) — RollupWatcher 를 담은 핸들을 돌려준다(close 로 정리). */
+    readonly watch?: boolean;
+    /** 통합 콘솔 로그 훅(생략 = vite 가 stdout 으로 직접 출력). */
+    readonly onLog?: (line: string, level: 'info' | 'warn' | 'error') => void;
+}
+export interface BuildAppHandle {
+    /** watch 모드에서 감시를 종료한다. non-watch 는 no-op. */
+    close(): Promise<void>;
+}
+/** 한 앱을 vite 로 빌드한다(programmatic · configFile 명시 → vue 플러그인·alias 보장). */
+export declare function buildApp(cwd: string, app: string, opts?: BuildAppOptions): Promise<BuildAppHandle>;
+/** 등록된 프론트 앱을 전부 빌드한다(build 커맨드·게이트 공용). 빌드한 앱 이름을 돌려준다. */
+export declare function buildAllApps(cwd: string, opts?: BuildAppOptions): Promise<string[]>;
+/** 한 앱의 dist 검증 결과. missing 가 비어 있지 않으면 게이트 실패(결정 146). */
+export interface DistVerifyResult {
+    readonly app: string;
+    readonly indexExists: boolean;
+    /** index.html 이 참조하는데 실제 파일이 없는 로컬 에셋 경로(base 기준). */
+    readonly missing: string[];
+}
+/**
+ * 앱의 dist/<앱>/index.html 과 그 문서가 참조하는 로컬 에셋(script src·link href)이
+ * 실제로 존재하는지 검증한다(결정 146 · gaon check build 게이트). base(/<앱>/)로 시작하는
+ * 참조만 검사한다(외부 URL 제외). curl data-page 만으로는 못 보던 "문서는 뜨는데 스크립트
+ * 404" 를 정면으로 막는다.
+ */
+export declare function verifyAppDist(cwd: string, app: string): Promise<DistVerifyResult>;

package/dist/dev/build.js

@@ -0,0 +1,144 @@
+// @gaonjs/cli · dev/build — 멀티 앱 프론트 빌드 파이프라인 (결정 146 · 12차 W2)
+//
+// gaon new 프로젝트는 앱이 하나 이상일 수 있다(gaon g app admin). 각 앱은 자기
+// prefix 아래로 서빙되고(web→'/' · admin→'/admin/'), serve 는 앱별 dist/<앱> 를
+// 기대한다(결정 67). 그런데 예전 파이프라인은 apps/web 하나만 빌드해(vite.config
+// root 하드코딩) 둘째 앱의 dist 가 안 생기고, 생겨도 base 가 없어 index.html 이
+// 절대경로 `/assets/*` 를 박아 비-루트 앱에서 404 였다. 이 모듈이 apps/* 를 순회해
+// 앱마다 root=apps/<앱>·outDir=dist/<앱>·base=/<앱>/ 로 빌드한다(결정 146).
+//
+// vite 는 **프로그램적 build()** 로 부른다 — configFile 을 명시로 넘겨야 vue 플러그인·
+// @shared alias 가 로드된다(positional root 만 주면 앱 폴더에 vite.config 가 없어
+// vue 플러그인이 빠지는 함정 · 결정 146). inline root/base/outDir 가 configFile 을
+// 덮어써 앱별 override 가 확실하다.
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+/** 앱의 URL base — web 은 루트('/'), 그 외는 '/<app>/'(결정 146). vite build 시 주입. */
+export function appBase(app) {
+    return app === 'web' ? '/' : `/${app}/`;
+}
+/** apps/* 중 프론트 진입(index.html)이 있는 앱 이름들. web 을 먼저(루트 앱 관례). */
+export async function listFrontendApps(cwd) {
+    const appsDir = join(resolve(cwd), 'apps');
+    let entries;
+    try {
+        entries = (await readdir(appsDir, { withFileTypes: true }));
+    }
+    catch {
+        return [];
+    }
+    const apps = entries
+        .filter((e) => e.isDirectory() && existsSync(join(appsDir, e.name, 'index.html')))
+        .map((e) => e.name);
+    return apps.sort((a, b) => (a === 'web' ? -1 : b === 'web' ? 1 : a.localeCompare(b)));
+}
+/** vite.config 를 프로젝트 루트·앱 루트 순으로 찾는다(configFile 명시용 · vue 플러그인 보장). */
+export function findViteConfig(cwd, appRoot) {
+    for (const dir of [appRoot, resolve(cwd)]) {
+        for (const name of ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']) {
+            const p = join(dir, name);
+            if (existsSync(p))
+                return p;
+        }
+    }
+    return undefined;
+}
+/** 한 앱을 vite 로 빌드한다(programmatic · configFile 명시 → vue 플러그인·alias 보장). */
+export async function buildApp(cwd, app, opts = {}) {
+    const root = resolve(cwd);
+    const appRoot = join(root, 'apps', app);
+    const vite = await loadVite();
+    const result = await vite.build({
+        configFile: findViteConfig(root, appRoot),
+        root: appRoot,
+        base: appBase(app),
+        // onLog 있으면 vite 출력을 그 훅으로 라우팅(customLogger 가 stdout 대신 훅으로).
+        // 없으면(예: `gaon build --json`) 완전히 침묵 — vite 진행 로그가 stdout 의 JSON 을
+        // 오염시키면 안 된다(클린룸이 마지막 줄을 JSON 으로 파싱 · 결정 146 실측).
+        logLevel: opts.onLog ? 'info' : 'silent',
+        customLogger: opts.onLog ? makeLogger(opts.onLog) : undefined,
+        build: {
+            outDir: join(root, 'dist', app),
+            emptyOutDir: true,
+            watch: opts.watch ? {} : null,
+        },
+    });
+    const watcher = result;
+    if (opts.watch && watcher && typeof watcher.close === 'function') {
+        return { close: async () => void (await watcher.close()) };
+    }
+    return { close: async () => { } };
+}
+/** 등록된 프론트 앱을 전부 빌드한다(build 커맨드·게이트 공용). 빌드한 앱 이름을 돌려준다. */
+export async function buildAllApps(cwd, opts = {}) {
+    const apps = await listFrontendApps(cwd);
+    for (const app of apps) {
+        opts.onLog?.(`▶ vite build — apps/${app} → dist/${app} (base=${appBase(app)})`, 'info');
+        await buildApp(cwd, app, { onLog: opts.onLog });
+    }
+    return apps;
+}
+/**
+ * 앱의 dist/<앱>/index.html 과 그 문서가 참조하는 로컬 에셋(script src·link href)이
+ * 실제로 존재하는지 검증한다(결정 146 · gaon check build 게이트). base(/<앱>/)로 시작하는
+ * 참조만 검사한다(외부 URL 제외). curl data-page 만으로는 못 보던 "문서는 뜨는데 스크립트
+ * 404" 를 정면으로 막는다.
+ */
+export async function verifyAppDist(cwd, app) {
+    const distDir = join(resolve(cwd), 'dist', app);
+    const indexPath = join(distDir, 'index.html');
+    if (!existsSync(indexPath))
+        return { app, indexExists: false, missing: [] };
+    const html = await readFile(indexPath, 'utf8');
+    const base = appBase(app);
+    const missing = [];
+    const refs = new Set();
+    // <script ... src="..."> · <link ... href="..."> 의 값 추출.
+    for (const m of html.matchAll(/<(?:script|link)\b[^>]*\b(?:src|href)\s*=\s*["']([^"']+)["']/gi)) {
+        refs.add(m[1]);
+    }
+    for (const ref of refs) {
+        // 이 앱 base 로 시작하는 로컬 에셋만 검사(외부·절대 URL·data: 제외).
+        if (!ref.startsWith(base))
+            continue;
+        const rel = ref.slice(base.length); // base 를 벗겨 dist 상대 경로로.
+        const file = join(distDir, rel.split('?')[0].split('#')[0]);
+        if (!existsSync(file))
+            missing.push(ref);
+    }
+    return { app, indexExists: true, missing };
+}
+async function loadVite() {
+    try {
+        return await import('vite');
+    }
+    catch (err) {
+        throw new Error(`[gaon build · vite] vite 모듈을 찾을 수 없습니다.\n` +
+            `→ 프로젝트 루트에서 설치하세요: pnpm add -D vite @vitejs/plugin-vue\n` +
+            `원인: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** vite 로거 어댑터 — 라인을 통합 콘솔 훅으로 흘린다(필요 메서드만). */
+function makeLogger(onLog) {
+    const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    let hasWarned = false;
+    const seen = new WeakSet();
+    return {
+        info: (m) => onLog(strip(m), 'info'),
+        warn: (m) => {
+            hasWarned = true;
+            onLog(strip(m), 'warn');
+        },
+        warnOnce: (m) => {
+            hasWarned = true;
+            onLog(strip(m), 'warn');
+        },
+        error: (m) => onLog(strip(m), 'error'),
+        clearScreen: () => { },
+        hasErrorLogged: (e) => seen.has(e),
+        get hasWarned() {
+            return hasWarned;
+        },
+    };
+}

package/dist/dev/frontend-build.d.ts

@@ -1,5 +1,5 @@
 export interface FrontendBuildHandle {
-    /** watch 빌드 프로세스를 종료한다. */
+    /** watch 빌드(모든 앱)를 종료한다. */
     close(): void;
 }
 export interface StartFrontendBuildOptions {
@@ -8,7 +8,7 @@ export interface StartFrontendBuildOptions {
     readonly onLog: (line: string, level: 'info' | 'warn' | 'error') => void;
 }
 /**
- * vite build --watch 를 띄운다. 프론트가 없거나 vite 가 없으면 아무 것도 하지
- * 않고 no-op 핸들을 돌려준다(dev 는 계속 진행).
+ * apps/* 를 순회해 앱마다 vite watch 빌드를 띄운다. 프론트가 없거나 vite 가 없으면
+ * 아무 것도 하지 않고 no-op 핸들을 돌려준다(dev 는 계속 진행 · fail-open).
  */
 export declare function startFrontendBuild(opts: StartFrontendBuildOptions): FrontendBuildHandle;

package/dist/dev/frontend-build.js

@@ -1,5 +1,5 @@
 /**
- * @gaonjs/cli · dev/frontend-build — 프론트 번들 watch 빌드 (결정 67 · M9-C)
+ * @gaonjs/cli · dev/frontend-build — 멀티 앱 프론트 번들 watch 빌드 (결정 67 · 결정 146)
  *
  * `gaon dev` 는 서버(serve)를 재시작 방식으로 띄운다(§dev.ts). 프론트 번들은
  * serve 가 dist/<앱>/index.html 을 매 요청 읽어 문서 셸에 이어 붙이므로
@@ -7,50 +7,55 @@
  * watch 모드로 함께 돌린다. 진짜 HMR(모듈 교체)은 v1 어댑터 범위 밖이라(§6.4)
  * "저장 → 재빌드 → 새로고침" 루프를 제공한다.
  *
- * fail-open: apps/web/index.html·vite 가 없으면 조용히 건너뛴다(프론트 없는
- * API 전용 프로젝트도 gaon dev 가 동작해야 한다). vite 실행 실패는 통합
- * 콘솔에 알리되 dev 전체를 막지 않는다.
+ * 결정 146(12차 W2): apps/* 를 순회해 **앱마다** watch 빌드한다(root=apps/<앱>·
+ * outDir=dist/<앱>·base=/<앱>/). 예전엔 apps/web 하나만 감시해 둘째 앱(admin)의
+ * dist 가 dev 에서 갱신되지 않았다. 프로그램적 build(configFile 명시)로 vue 플러그인
+ * 누락 함정을 피한다.
+ *
+ * fail-open: 프론트 진입(index.html)·vite 가 없으면 조용히 건너뛴다(프론트 없는
+ * API 전용 프로젝트도 gaon dev 가 동작해야 한다). vite 실패는 통합 콘솔에 알리되
+ * dev 전체를 막지 않는다.
  */
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-/** 프로젝트에 프론트 진입 HTML(apps/web/index.html)이 있는가. */
-function hasFrontend(cwd) {
-    return existsSync(join(cwd, 'apps', 'web', 'index.html'));
-}
-/** cwd 의 로컬 vite bin 을 찾는다(없으면 undefined — 건너뜀). */
-function resolveViteBin(cwd) {
-    const bin = join(cwd, 'node_modules', '.bin', 'vite');
-    return existsSync(bin) ? bin : undefined;
-}
+import { resolve } from 'node:path';
+import { appBase, buildApp, listFrontendApps } from './build.js';
 /**
- * vite build --watch 를 띄운다. 프론트가 없거나 vite 가 없으면 아무 것도 하지
- * 않고 no-op 핸들을 돌려준다(dev 는 계속 진행).
+ * apps/* 를 순회해 앱마다 vite watch 빌드를 띄운다. 프론트가 없거나 vite 가 없으면
+ * 아무 것도 하지 않고 no-op 핸들을 돌려준다(dev 는 계속 진행 · fail-open).
  */
 export function startFrontendBuild(opts) {
     const cwd = resolve(opts.cwd);
-    if (!hasFrontend(cwd)) {
-        opts.onLog('프론트 진입 HTML(apps/web/index.html)이 없어 vite 빌드를 건너뜁니다.', 'info');
-        return { close() { } };
-    }
-    const bin = resolveViteBin(cwd);
-    if (!bin) {
-        opts.onLog('vite 를 찾지 못해 프론트 watch 빌드를 건너뜁니다 → pnpm add -D vite @vitejs/plugin-vue', 'warn');
-        return { close() { } };
-    }
-    const child = spawn(bin, ['build', '--watch'], {
-        cwd,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        env: { ...process.env },
+    const watchers = [];
+    let closed = false;
+    void (async () => {
+        const apps = await listFrontendApps(cwd);
+        if (apps.length === 0) {
+            opts.onLog('프론트 진입 HTML(apps/<앱>/index.html)이 없어 vite watch 빌드를 건너뜁니다.', 'info');
+            return;
+        }
+        for (const app of apps) {
+            if (closed)
+                break;
+            opts.onLog(`▶ vite build --watch — apps/${app} → dist/${app} (base=${appBase(app)})`, 'info');
+            try {
+                const handle = await buildApp(cwd, app, { watch: true, onLog: opts.onLog });
+                if (closed) {
+                    await handle.close();
+                    break;
+                }
+                watchers.push(handle);
+            }
+            catch (err) {
+                opts.onLog(`vite watch 빌드를 건너뜁니다(apps/${app}): ${err instanceof Error ? err.message : String(err)}`, 'warn');
+            }
+        }
+    })().catch((err) => {
+        opts.onLog(`프론트 watch 빌드 오류: ${err instanceof Error ? err.message : String(err)}`, 'error');
     });
-    child.stdout?.on('data', (b) => opts.onLog(b.toString().trimEnd(), 'info'));
-    child.stderr?.on('data', (b) => opts.onLog(b.toString().trimEnd(), 'error'));
-    child.on('error', (err) => opts.onLog(`vite 실행 실패: ${err.message}`, 'error'));
-    opts.onLog('▶ vite build --watch — 프론트 번들 감시 (dist/web)', 'info');
     return {
         close() {
-            if (child.exitCode === null && child.signalCode === null)
-                child.kill('SIGTERM');
+            closed = true;
+            for (const w of watchers)
+                void w.close();
         },
     };
 }

package/dist/doctor/async-offload.d.ts

@@ -1,5 +1,7 @@
 import type { RuleReport } from './types.js';
-/** app.config 소스가 JWT/API 앱인가 (외부 HTTP arm 제외 대상 · csrf-wiring 과 동일 판정). */
+/** app.config 소스가 JWT/API 앱인가 (외부 HTTP arm 제외 대상 · csrf-wiring 과 동일 판정).
+ *  결정 140(12차 W1): jwt 판정을 usesJwtStrategy 한 곳으로 통일 — 주석의
+ *  `// strategy: 'jwt'` 오탐이 offload 검사를 잘못 끄지 않도록. */
 export declare function isApiApp(appConfigSource: string): boolean;
 /** 파일이 메일 SDK 를 직접 import 하는가(단위 테스트 진입점). */
 export declare function importsMailSdk(source: string): boolean;

package/dist/doctor/async-offload.js

@@ -28,6 +28,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import ts from 'typescript';
+import { usesJwtStrategy } from './auth-wiring.js';
 // ── 검출 시그니처 ─────────────────────────────────────────────────────
 /** 메일 SDK 모듈 import (컨트롤러 = 잡 발행만 · async.md 함정 · async-flow forbidden 동일 집합). */
 const MAIL_SDK_IMPORT = /import\s+[\s\S]*?\bfrom\s+['"](?:nodemailer|resend|@sendgrid\/mail|mailgun[.\-/][^'"]*|mailgun)['"]/;
@@ -44,9 +45,11 @@ const EXTERNAL_HTTP = [
     // axios('https://...') · axios.get('https://...') · axios({ url: 'https://...' })
     /\baxios\s*(?:\.\s*(?:get|post|put|patch|delete|request|head)\s*)?\(\s*(?:\{[\s\S]*?\burl\s*:\s*)?[`'"]https?:\/\/(?!localhost|127\.0\.0\.1)/i,
 ];
-/** app.config 소스가 JWT/API 앱인가 (외부 HTTP arm 제외 대상 · csrf-wiring 과 동일 판정). */
+/** app.config 소스가 JWT/API 앱인가 (외부 HTTP arm 제외 대상 · csrf-wiring 과 동일 판정).
+ *  결정 140(12차 W1): jwt 판정을 usesJwtStrategy 한 곳으로 통일 — 주석의
+ *  `// strategy: 'jwt'` 오탐이 offload 검사를 잘못 끄지 않도록. */
 export function isApiApp(appConfigSource) {
-    return /strategy\s*:\s*['"]jwt['"]/.test(appConfigSource);
+    return usesJwtStrategy(appConfigSource);
 }
 /** 파일이 메일 SDK 를 직접 import 하는가(단위 테스트 진입점). */
 export function importsMailSdk(source) {

package/dist/doctor/auth-wiring.d.ts

@@ -1,9 +1,11 @@
 import type { RuleReport } from './types.js';
 /** 컨트롤러 소스가 인증 표면을 쓰는지 판정한다(단위 테스트 진입점). */
 export declare function usesAuthSurface(source: string): boolean;
-/** app.config.ts 소스에 auth 배선이 있는지(얕은 텍스트 판정). */
+/** app.config.ts 소스에 auth 배선이 있는지(주석/문자열 제외 후 판정). */
 export declare function hasAuthWiring(source: string): boolean;
-/** app.config.ts 소스에 session 배선이 있는지(얕은 텍스트 판정). */
+/** app.config.ts 소스에 session 배선이 있는지(주석/문자열 제외 후 판정). */
 export declare function hasSessionWiring(source: string): boolean;
+/** app.config.ts 소스가 JWT 전략(strategy:'jwt')인지(주석 제외 후 판정 · 문자열 내용 보존). */
+export declare function usesJwtStrategy(source: string): boolean;
 /** apps/ 를 훑어 인증 배선 누락을 낸다. */
 export declare function checkAuthWiring(cwd: string): Promise<RuleReport>;

package/dist/doctor/auth-wiring.js

@@ -11,17 +11,24 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { stripComments, stripCommentsAndStrings } from './source-scan.js';
+// 결정 140(12차 W1): 판정 전 주석/문자열을 지운다. `// session:` 주석이나 문자열
+// 안의 우연한 일치가 배선으로 오탐되면 보안 검사(세션·CSRF)가 통째로 skip 된다.
 /** 컨트롤러 소스가 인증 표면을 쓰는지 판정한다(단위 테스트 진입점). */
 export function usesAuthSurface(source) {
-    return /this\.requireAuth\s*\(|this\.auth\.login\s*\(|this\.currentUser\b/.test(source);
+    return /this\.requireAuth\s*\(|this\.auth\.login\s*\(|this\.currentUser\b/.test(stripCommentsAndStrings(source));
 }
-/** app.config.ts 소스에 auth 배선이 있는지(얕은 텍스트 판정). */
+/** app.config.ts 소스에 auth 배선이 있는지(주석/문자열 제외 후 판정). */
 export function hasAuthWiring(source) {
-    return /\bauth\s*:/.test(source);
+    return /\bauth\s*:/.test(stripCommentsAndStrings(source));
 }
-/** app.config.ts 소스에 session 배선이 있는지(얕은 텍스트 판정). */
+/** app.config.ts 소스에 session 배선이 있는지(주석/문자열 제외 후 판정). */
 export function hasSessionWiring(source) {
-    return /\bsession\s*:/.test(source);
+    return /\bsession\s*:/.test(stripCommentsAndStrings(source));
+}
+/** app.config.ts 소스가 JWT 전략(strategy:'jwt')인지(주석 제외 후 판정 · 문자열 내용 보존). */
+export function usesJwtStrategy(source) {
+    return /strategy\s*:\s*['"]jwt['"]/.test(stripComments(source));
 }
 /** apps/ 를 훑어 인증 배선 누락을 낸다. */
 export async function checkAuthWiring(cwd) {
@@ -42,7 +49,7 @@ export async function checkAuthWiring(cwd) {
         const acPath = join(appsDir, app, 'app.config.ts');
         const acRel = relative(cwd, acPath);
         const acSource = existsSync(acPath) ? await readFile(acPath, 'utf8') : undefined;
-        const jwt = acSource != null && /strategy\s*:\s*['"]jwt['"]/.test(acSource);
+        const jwt = acSource != null && usesJwtStrategy(acSource);
         if (acSource == null || !hasAuthWiring(acSource)) {
             issues.push({
                 rule: 'auth-wiring',

package/dist/doctor/csrf-wiring.d.ts

@@ -1,5 +1,7 @@
 import type { RuleReport } from './types.js';
-/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점). */
+/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점).
+ *  결정 140(12차 W1): 주석/문자열 안의 우연한 일치가 CSRF 검사를 왜곡하지 않도록
+ *  판정 전 정규화한다(여는 따옴표 구분자는 보존되어 라우트 매칭은 유지). */
 export declare function hasStateChangingRoutes(routesSource: string): boolean;
 /** apps/ 를 훑어 CSRF/세션 미배선(비-GET 라우트 + session 없음)을 경고로 낸다. */
 export declare function checkCsrfWiring(cwd: string): Promise<RuleReport>;

package/dist/doctor/csrf-wiring.js

@@ -14,14 +14,18 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { hasSessionWiring } from './auth-wiring.js';
-/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점). */
+import { hasSessionWiring, usesJwtStrategy } from './auth-wiring.js';
+import { stripCommentsAndStrings } from './source-scan.js';
+/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점).
+ *  결정 140(12차 W1): 주석/문자열 안의 우연한 일치가 CSRF 검사를 왜곡하지 않도록
+ *  판정 전 정규화한다(여는 따옴표 구분자는 보존되어 라우트 매칭은 유지). */
 export function hasStateChangingRoutes(routesSource) {
+    const src = stripCommentsAndStrings(routesSource);
     // r.post('/x', ...) · r.put/patch/delete — 메서드 + 경로 문자열.
-    if (/\.\s*(post|put|patch|delete)\s*\(\s*['"]/.test(routesSource))
+    if (/\.\s*(post|put|patch|delete)\s*\(\s*['"]/.test(src))
         return true;
     // resource(s)('posts') — 리소스 라우트는 create/update/destroy(POST/PUT/DELETE)를 만든다.
-    if (/\.\s*resources?\s*\(\s*['"]/.test(routesSource))
+    if (/\.\s*resources?\s*\(\s*['"]/.test(src))
         return true;
     return false;
 }
@@ -40,7 +44,7 @@ export async function checkCsrfWiring(cwd) {
         const acRel = relative(cwd, acPath);
         const acSource = existsSync(acPath) ? await readFile(acPath, 'utf8') : undefined;
         // JWT/API 앱은 토큰 인증 — CSRF 대상 아님(제외).
-        const jwt = acSource != null && /strategy\s*:\s*['"]jwt['"]/.test(acSource);
+        const jwt = acSource != null && usesJwtStrategy(acSource);
         if (jwt)
             continue;
         if (acSource != null && hasSessionWiring(acSource))

package/dist/doctor/seal-security.js

@@ -10,10 +10,13 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { stripComments, stripCommentsAndStrings } from './source-scan.js';
+// 결정 140(12차 W1): 판정 전 주석/문자열을 지운다 — 주석의 `seal: {` 나 문자열 안의
+// 우연한 일치가 검사를 왜곡하지 않도록.
 /** app.config.ts 소스에 seal 토글(true 또는 { … })이 켜져 있는지 판정한다(단위 테스트 진입점). */
 export function hasSealEnabled(appConfigSource) {
     // seal: true · seal: { except: [...] } — false/생략은 제외.
-    return /\bseal\s*:\s*(true|\{)/.test(appConfigSource);
+    return /\bseal\s*:\s*(true|\{)/.test(stripCommentsAndStrings(appConfigSource));
 }
 /**
  * 결정 121(§3.1): seal 앱의 main.ts 가 seal 클라이언트를 배선했는지 판정한다(단위 테스트 진입점).
@@ -22,19 +25,22 @@ export function hasSealEnabled(appConfigSource) {
  * (seal-browser-e2e 로 실측). import + sealClient 전달을 둘 다 확인한다.
  */
 export function hasSealClientWired(mainSource) {
-    const imported = /import[^\n]*@gaonjs\/seal\/client/.test(mainSource);
+    // import 경로 문자열을 봐야 하므로 문자열 내용은 보존(주석만 제거).
+    const src = stripComments(mainSource);
+    const imported = /import[^\n]*@gaonjs\/seal\/client/.test(src);
     // createGaonApp(...) 호출 안에 sealClient 가 실제로 전달됐는지(멀티라인 객체 허용).
-    const passed = /createGaonApp\s*\([\s\S]*\bsealClient\b/.test(mainSource);
+    const passed = /createGaonApp\s*\([\s\S]*\bsealClient\b/.test(src);
     return imported && passed;
 }
 /** gaon.config.ts 소스에서 명시적으로 꺼진 보안 방어층 이름을 뽑는다(rateLimit·securityHeaders·cors). */
 export function disabledDefenses(gaonConfigSource) {
+    const src = stripCommentsAndStrings(gaonConfigSource);
     const off = [];
-    if (/\brateLimit\s*:\s*false/.test(gaonConfigSource))
+    if (/\brateLimit\s*:\s*false/.test(src))
         off.push('rateLimit');
-    if (/\bsecurityHeaders\s*:\s*false/.test(gaonConfigSource))
+    if (/\bsecurityHeaders\s*:\s*false/.test(src))
         off.push('securityHeaders');
-    if (/\bcors\s*:\s*false/.test(gaonConfigSource))
+    if (/\bcors\s*:\s*false/.test(src))
         off.push('cors');
     return off;
 }

package/dist/doctor/source-scan.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 주석을 지운 소스를 돌려준다(문자열·코드는 보존 · 라인 번호 유지).
+ * 문자열 **내용**을 봐야 하는 탐지기(예: `strategy: 'jwt'` · import 경로)에 쓴다.
+ */
+export declare function stripComments(source: string): string;
+/**
+ * 주석 + 문자열/템플릿 리터럴 내용을 지운 소스를 돌려준다(구분자·라인 보존).
+ * 프로퍼티 키·키워드만 보는 탐지기(예: `session:` · `auth:` · `rateLimit: false`)에
+ * 쓴다 — 주석도 문자열도 키를 위장하지 못한다.
+ */
+export declare function stripCommentsAndStrings(source: string): string;

package/dist/doctor/source-scan.js

@@ -0,0 +1,70 @@
+// @gaonjs/cli · doctor · 소스 정규화 유틸 (12차 W1 · 결정 140)
+//
+// 탐지기가 정규식으로 소스를 볼 때 **주석·문자열 안의 우연한 일치**를 배선으로
+// 오탐하지 않도록, TS 스캐너로 토큰을 훑어 주석/문자열을 안전하게 지운다.
+//
+// 왜 스캐너인가(regex 스트립이 아니라): 보안 탐지기(auth·csrf·seal)는 오탐이
+// 검사 skip = 취약점 노출로 이어진다(12차 W1 · gaon g app 스캐폴드의 주석
+// `//   session: { ... }` 가 hasSessionWiring 을 만족시켜 CSRF/세션 검사를
+// 통째로 건너뛴 P0). regex 기반 주석 스트립은 문자열 안의 `//` 를 잘못 지우는
+// 등 경계에서 새므로, 정확한 토큰 경계가 필요한 보안 탐지기는 스캐너로 지운다.
+// (connections.ts·schema-relations.ts 가 이미 TS AST 를 쓰는 것과 같은 결.)
+//
+// 라인/컬럼(개행)은 보존한다 — 탐지기가 라인 번호를 그대로 보고할 수 있게.
+import ts from 'typescript';
+function isCommentKind(k) {
+    return k === ts.SyntaxKind.SingleLineCommentTrivia || k === ts.SyntaxKind.MultiLineCommentTrivia;
+}
+function isStringKind(k) {
+    return (k === ts.SyntaxKind.StringLiteral ||
+        k === ts.SyntaxKind.NoSubstitutionTemplateLiteral ||
+        k === ts.SyntaxKind.TemplateHead ||
+        k === ts.SyntaxKind.TemplateMiddle ||
+        k === ts.SyntaxKind.TemplateTail);
+}
+/** 개행만 남기고 나머지 문자는 공백으로 — 라인 번호를 보존한다. */
+function blankKeepLines(text) {
+    return text.replace(/[^\n]/g, ' ');
+}
+/**
+ * 문자열/템플릿 토큰의 **내용**만 비우고 구분자(따옴표·백틱·`${`·`}`)는 남긴다.
+ * `'jwt'` → `'   '` · `''` → `''`. 프로퍼티 키·구분자에 걸린 탐지기(예: 라우트
+ * `.post('...')` 의 여는 따옴표)는 여전히 매칭되지만, 문자열 내용이 키를 위장하는
+ * 오탐은 막는다. 개행은 보존한다.
+ */
+function blankStringContent(text) {
+    if (text.length <= 2)
+        return text;
+    return text[0] + blankKeepLines(text.slice(1, -1)) + text[text.length - 1];
+}
+function scanTransform(source, strings) {
+    // skipTrivia=false 로 주석·공백까지 토큰으로 받아 원문을 무손실 재구성한다.
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, 
+    /* skipTrivia */ false, ts.LanguageVariant.Standard, source);
+    let out = '';
+    for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+        const text = scanner.getTokenText();
+        if (isCommentKind(token))
+            out += blankKeepLines(text);
+        else if (strings && isStringKind(token))
+            out += blankStringContent(text);
+        else
+            out += text;
+    }
+    return out;
+}
+/**
+ * 주석을 지운 소스를 돌려준다(문자열·코드는 보존 · 라인 번호 유지).
+ * 문자열 **내용**을 봐야 하는 탐지기(예: `strategy: 'jwt'` · import 경로)에 쓴다.
+ */
+export function stripComments(source) {
+    return scanTransform(source, /* strings */ false);
+}
+/**
+ * 주석 + 문자열/템플릿 리터럴 내용을 지운 소스를 돌려준다(구분자·라인 보존).
+ * 프로퍼티 키·키워드만 보는 탐지기(예: `session:` · `auth:` · `rateLimit: false`)에
+ * 쓴다 — 주석도 문자열도 키를 위장하지 못한다.
+ */
+export function stripCommentsAndStrings(source) {
+    return scanTransform(source, /* strings */ true);
+}

package/dist/generate.d.ts

@@ -28,7 +28,7 @@ export declare function patchRoutes(existing: string): string | null;
  *  · defineAppConfig 객체 리터럴을 못 찾으면 null (안전 · 상위에서 경고 폴백).
  * 성공 시 loadUser import 도 함께 보장한다.
  */
-export declare function patchAppConfigAddAuth(existing: string): string | null;
+export declare function patchAppConfigAddAuth(existing: string, app?: string): string | null;
 /** 스캐폴드를 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip 한다. routes.ts 는 패치. */
 export declare function writeAuthScaffold(cwd: string, opts?: AuthScaffoldOptions): ScaffoldResult;
 export interface GenerateAuthOptions {

package/dist/generate.js

@@ -19,11 +19,38 @@ import { authUiKitFiles, writeUiKitFiles } from './uikit.js';
 // ── 템플릿 로드·치환 ───────────────────────────────────────────
 // 템플릿은 이 모듈과 같은 위치의 templates/auth/ 에 있다(빌드가 dist 로 복사).
 const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'auth');
-/** 템플릿 파일을 읽어 토큰을 치환한다. {{APP_NAME}} 는 Vue 의 {{ }} 보간과
- *  겹치지 않는 고정 리터럴이라 단순 replaceAll 로 안전하다. */
+/**
+ * 앱의 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!!`;
+}
+/** 템플릿 파일을 읽어 토큰을 치환한다. {{APP_NAME}}·{{URL_PREFIX}}·
+ *  {{SESSION_SECRET_ENV}} 는 Vue 의 {{ }} 보간과 겹치지 않는 고정 리터럴이라
+ *  단순 replaceAll 로 안전하다(결정 141). */
 function renderTemplate(name, app) {
     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));
 }
 /** 템플릿 파일 → 생성 경로 매핑(라우트 제외 — 라우트는 패치로 처리). */
 const TEMPLATES = [
@@ -76,18 +103,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/);
@@ -124,7 +163,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 +173,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 {
@@ -191,11 +231,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,8 @@ 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 { 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,8 @@ 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 { runNewCommand } from "./commands/new.js";
 export { runConsoleCommand } from "./commands/console.js";
 export { runTestCommand } from "./commands/test.js";
@@ -102,6 +105,7 @@ function renderHelp(version = VERSION) {
         "    gaon serve --workers <n|auto>      node:cluster 워커 다중화 (env WEB_CONCURRENCY · 기본 1)",
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-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 관계)",
@@ -258,6 +262,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.

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>
@@ -47,7 +47,7 @@ const form = useForm({ email: '', password: '', _csrf: shared.csrf })
         </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>
+          <Link href="{{URL_PREFIX}}/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</Link>
         </p>
       </CardContent>
     </Card>

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/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/agents/async.md.tpl

@@ -186,15 +186,19 @@ export const PlaceOrder = service(async (input: { name: string }) => {
 ```
 
 - 트랜잭션 안의 `emit` 은 `AsyncLocalStorage` 로 투명하게 감지돼
-  아웃박스에 스테이징된다(별도 API 호출 불필요).
-- 저수준 원시는 `runInTransaction(db, fn)`(커넥션을 넘긴다) — `service()`
-  가 내부에서 이를 쓴다. 대부분의 도메인 코드는 `service()` 본문에서
-  emit 하거나, "커밋 후 즉시 발행"이면 `afterCommit(fn)`(§서비스)을 쓴다.
+  아웃박스에 스테이징된다(별도 API 호출 불필요). `service()` 본문의 emit 이
+  같은 트랜잭션으로 `_gaon_outbox` 에 적재되고, 롤백 시 적재도 취소된다
+  (결정 144 · 12차 W3 — 표준 부팅 `gaon serve`·`gaon work` 가 이 배선을
+  자동으로 한다 · 앱 개발자가 부팅 코드를 짤 필요 없다).
+- 대부분의 도메인 코드는 `service()` 본문에서 emit 하거나, "커밋 후 즉시
+  발행"이면 `afterCommit(fn)`(§서비스)을 쓴다. 저수준 원시 `runInTransaction(db, fn)`
+  (커넥션을 직접 넘긴다)은 프레임웍 밖에서 트랜잭션을 손수 열 때만 쓰는 탈출구다.
 - 릴레이(`gaon work` 내장)가 `SKIP LOCKED` 로 아웃박스를 폴링해 발행
   한다 (기본 폴 1000ms · 배치 100).
 - at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이
   흡수한다.
-- 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 워커 기동 시 보장된다.
+- 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 `gaon serve`·`gaon work`
+  기동 시 보장된다(결정 144 · nats 설정이 있을 때).
 - 발행 완료 행은 릴레이가 **자동 정리(purge)** 한다 — 기본 7일 보존 후 삭제
   (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격은 `gaon work` 의
   `outboxRetentionMs`·`outboxPurgeIntervalMs` 로 조정한다(운영 상세는

package/dist/templates/project/agents/security.md.tpl

@@ -43,8 +43,14 @@
 ### 2. 세션·CSRF·JWT
 
 - 세션은 앱별 완전 분리 (v0.15 §7 · Fastify 캡슐화 스코프): 쿠키
-  이름(`<app>_sid`) · 서명 secret · Redis 키 prefix · 쿠키 path 가
-  앱 단위로 갇힌다.
+  이름(`<app>_sid`) · 서명 secret · Redis 키 prefix 가 앱 단위로 갇힌다.
+  (쿠키 path 는 `/` — 프리픽스·서브도메인 양쪽 접근에서 쿠키가 실리려면
+  정적 path 는 `/` 여야 한다 · 결정 142. 분리는 위 세 축으로 완성된다.)
+- **멀티 앱 인증**: 둘째 앱은 `gaon g app admin` → `gaon g auth --app admin`
+  으로 만든다 — 스캐폴드가 로그인/리다이렉트 URL 에 앱 프리픽스(`/admin/...`)를
+  자동으로 붙이고, 세션 secret 을 **앱별 env** `<APP>_SESSION_SECRET`(예:
+  `ADMIN_SESSION_SECRET`)로 분리 배선한다(결정 141 · 앱별 세션 완전 분리).
+  운영 배포 시 그 env 를 web 과 **다르게** 설정할 것.
 - CSRF: 세션 앱은 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 CSRF
   강제. `api()` 클라이언트는 `<meta name="csrf-token">` 을 자동으로
   읽어 `X-CSRF-Token` 헤더에 붙인다 (`packages/vue/src/api.ts:184`).
@@ -55,6 +61,14 @@
   라우트가 있는데 `app.config.ts` 에 session 이 없으면 `gaon doctor` 의
   `csrf-wiring` 이 경고한다(JWT/API 앱은 토큰 인증이라 CSRF 대상 제외).
 - JWT 는 API 앱 전용 옵션. 세션 쿠키가 기본 (v0.15 §7 · v0.11 확정).
+- **인증(requireAuth) 과 인가(authorize) 는 별개 축** (결정 145):
+  - `this.requireAuth()` = **로그인 여부** — 비로그인이면 401(세션 앱은 로그인 페이지 리다이렉트).
+  - `this.authorize(condition)` = **권한 여부** — 조건이 거짓이면 **403**. 존재 자체를
+    숨겨야 하면 `this.authorize(condition, { notFound: true })` → 404. 조건은 호출자가
+    계산한다(예: `this.authorize(this.currentUser?.role === 'admin')`) — v1 은 정책 객체·
+    역할 DSL 을 두지 않는다(리치 authz 는 v1.1 백로그).
+  - 실시간 채널의 `authorize` 는 **구독 인가 전용**(§realtime) — HTTP 인가는 `this.authorize`.
+  - 손으로 403 을 throw 하거나 인가를 `notFound()` 로 우회하지 말 것 — `this.authorize` 가 The One Way.
 
 ### 3. 시크릿
 

package/dist/templates/project/agents/testing.md.tpl

@@ -101,6 +101,11 @@ DB 테스트는 손으로 커넥션을 배선하지 않는다 — `gaon test`
   테스트에서도 그대로 돈다. 스토리지 s3 버킷은 `<bucket>-test`, 로컬 root 는
   `<root>-test` 로 격리되고(compose `createbuckets` 가 `<PROJECT>-test` 버킷을 만든다),
   메일은 MailPit(캡처 sink) 그대로다.
+- `connectTestDatabase` 는 **잡·이벤트 전송(NATS)도 배선**한다(결정 143 · `config.nats`
+  있을 때) — 서비스가 `.later()`·`emit()` 하는 코드가 테스트에서도 운영과 똑같이 돈다.
+  수동 `configureJobs` 는 필요 없다. `expectJobProcessed` 는 **자기 nats 만** 임시로
+  쓰고 끝나면 하네스 배선을 복원하므로, 그 nats 를 `close()` 해도 다음 테스트의
+  `.later()` 가 깨지지 않는다(결정 143).
 
 스캐폴드가 심어 주는 `test/setup.ts`(수정 불필요):
 

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

@@ -9,7 +9,7 @@
   },
   "scripts": {
     "dev": "gaon dev",
-    "build": "gaon gen && vite build",
+    "build": "gaon build",
     "serve": "gaon serve",
     "work": "gaon work",
     "hub": "gaon hub",

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

@@ -1,12 +1,13 @@
 // vite.config.ts — 프론트엔드 빌드/개발 서버 설정 (v0.16 §6.4).
 //
 // The One Way: gaon dev 가 Vite 를 middlewareMode 로 붙여 Fastify 한 포트로
-// 서빙한다(§CLAUDE.md 6 · 이 파일의 server 옵션은 그때 재정의된다). vite
-// build 는 이 파일을 그대로 사용한다.
+// 서빙한다(§CLAUDE.md 6 · 이 파일의 server 옵션은 그때 재정의된다).
 //
-// 앱이 하나 이상이면 각 앱마다 vite.config.ts 를 두는 것이 아니라, 이 루트
-// 파일 하나가 root 를 apps/<앱> 으로 잡고 여러 번 실행된다(gaon dev 가 앱별
-// Vite 서버를 띄운다). 관례가 곧 배치.
+// 멀티 앱: 각 앱마다 vite.config 를 두지 않는다. `gaon build`·`gaon dev` 가 이 루트
+// 파일 하나를 **configFile 로 명시**하고(vue 플러그인·@shared alias 보장 · 결정 146),
+// 앱마다 root=apps/<앱>·outDir=dist/<앱>·base=/<앱>/(web 은 '/') 를 덮어써 순회 빌드한다.
+// 아래 root·build.outDir 는 apps/web 단독 실행(직접 `vite` 호출) 시의 기본값일 뿐,
+// gaon 파이프라인이 앱별로 재정의한다. gaon g app 으로 늘린 앱은 자동 편입된다.
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.8.0",
+    "@gaonjs/async": "0.9.0",
     "@gaonjs/core": "0.2.1",
-    "@gaonjs/config": "0.12.0",
-    "@gaonjs/web": "0.14.0",
-    "@gaonjs/mail": "0.1.3",
-    "@gaonjs/data": "0.14.0"
+    "@gaonjs/config": "0.13.0",
+    "@gaonjs/data": "0.15.0",
+    "@gaonjs/web": "0.15.0",
+    "@gaonjs/mail": "0.1.3"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""