@gaonjs/cli 0.13.2 → 0.15.0

package/dist/commands/dev.d.ts

@@ -36,6 +36,8 @@ export interface DevCommandOptions {
     readonly noVueTsc?: boolean;
     /** Docker 자동 기동 끄기(개별 debug · 사용자가 이미 띄운 경우). */
     readonly noDocker?: boolean;
+    /** 프론트 watch 빌드(vite build --watch) 끄기(개별 debug). */
+    readonly noVite?: boolean;
     /** 통합 콘솔 타임스탬프 표시. */
     readonly timestamp?: boolean;
     /** 시그널(테스트 주입 · 기본 process). */

package/dist/commands/dev.js

@@ -30,6 +30,7 @@ import { createDevConsole } from '../dev/console.js';
 import { ensureInfra, composeDown } from '../dev/docker.js';
 import { startTscWatchers, killChild } from '../dev/tsc.js';
 import { startRestartWatcher } from '../dev/watcher.js';
+import { startFrontendBuild } from '../dev/frontend-build.js';
 /**
  * gaon 셀프 경로를 찾는다. 부모가 gaon 으로 실행됐다면 argv[1] 이
  * gaonjs/dist/cli.js (또는 개발 시 packages/gaonjs/src/cli.ts). 자식
@@ -53,7 +54,9 @@ function resolveSelfCliEntry() {
  */
 function spawnServe(args) {
     const { node, args: nodeArgs } = resolveSelfCliEntry();
-    const serveArgs = ['serve'];
+    // --dev: dev 전용 진단 라우트(/_gaon/health)를 켠다(결정 69). gaon dev 의
+    // serve 자식만 이 플래그를 받으므로 운영 serve 에는 진단이 노출되지 않는다.
+    const serveArgs = ['serve', '--dev'];
     if (args.json)
         serveArgs.push('--json');
     if (args.port != null)
@@ -148,6 +151,15 @@ export async function runDevCommand(opts = {}) {
     }
     // ── 2) .gaon 재생성 워처 ─────────────────────────────────────────
     const regen = await startGaonRegen({ cwd, console: consoleOut });
+    // ── 2') 프론트 번들 watch 빌드(결정 67) ─────────────────────────
+    //   serve 가 dist/<앱>/index.html 을 문서 셸로 읽으므로 dev 에서 dist 를
+    //   최신으로 유지한다. 프론트 없는 프로젝트면 no-op.
+    const frontend = opts.noVite
+        ? undefined
+        : startFrontendBuild({
+            cwd,
+            onLog: (line, level) => consoleOut.log('vite', line, level),
+        });
     // ── 3) tsc / vue-tsc 워치 ────────────────────────────────────────
     const tsc = opts.noTsc && opts.noVueTsc
         ? undefined
@@ -243,6 +255,7 @@ export async function runDevCommand(opts = {}) {
                     if (tsc) {
                         await tsc.stop();
                     }
+                    frontend?.close();
                     regen.close();
                     if (stopDocker && composeFile) {
                         consoleOut.log('docker', '--stop-docker · compose down 실행');

package/dist/dev/console.d.ts

@@ -13,7 +13,7 @@
  * 정책상 chalk 는 쓰지 않는다 — 필요한 코드만 직접 쓴다.
  */
 /** 콘솔이 구분하는 로그 소스. */
-export type DevSource = 'dev' | 'docker' | 'serve' | 'watcher' | 'tsc' | 'vue-tsc';
+export type DevSource = 'dev' | 'docker' | 'serve' | 'watcher' | 'tsc' | 'vue-tsc' | 'vite';
 /** 로그 레벨 — human 은 색상 강조, json 은 필드로 실린다. */
 export type DevLevel = 'info' | 'warn' | 'error';
 export interface DevConsoleOptions {

package/dist/dev/console.js

@@ -26,6 +26,7 @@ const SOURCE_COLOR = {
     watcher: '\x1b[36m', // cyan — 파일 감시
     tsc: '\x1b[33m', // yellow — 타입 검사
     'vue-tsc': '\x1b[95m', // bright magenta — vue 전용
+    vite: '\x1b[92m', // bright green — 프론트 빌드
 };
 /** stdout.isTTY 여부 자동 감지(테스트에서는 stream.isTTY 를 봄). */
 function detectTty(stream) {

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

@@ -0,0 +1,14 @@
+export interface FrontendBuildHandle {
+    /** watch 빌드 프로세스를 종료한다. */
+    close(): void;
+}
+export interface StartFrontendBuildOptions {
+    readonly cwd: string;
+    /** 통합 콘솔 로그 훅. */
+    readonly onLog: (line: string, level: 'info' | 'warn' | 'error') => void;
+}
+/**
+ * vite build --watch 를 띄운다. 프론트가 없거나 vite 가 없으면 아무 것도 하지
+ * 않고 no-op 핸들을 돌려준다(dev 는 계속 진행).
+ */
+export declare function startFrontendBuild(opts: StartFrontendBuildOptions): FrontendBuildHandle;

package/dist/dev/frontend-build.js

@@ -0,0 +1,56 @@
+/**
+ * @gaonjs/cli · dev/frontend-build — 프론트 번들 watch 빌드 (결정 67 · M9-C)
+ *
+ * `gaon dev` 는 서버(serve)를 재시작 방식으로 띄운다(§dev.ts). 프론트 번들은
+ * serve 가 dist/<앱>/index.html 을 매 요청 읽어 문서 셸에 이어 붙이므로
+ * (packages/web frontend.ts), dev 에서 그 dist 를 최신으로 유지하려면 vite 를
+ * watch 모드로 함께 돌린다. 진짜 HMR(모듈 교체)은 v1 어댑터 범위 밖이라(§6.4)
+ * "저장 → 재빌드 → 새로고침" 루프를 제공한다.
+ *
+ * fail-open: apps/web/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;
+}
+/**
+ * vite build --watch 를 띄운다. 프론트가 없거나 vite 가 없으면 아무 것도 하지
+ * 않고 no-op 핸들을 돌려준다(dev 는 계속 진행).
+ */
+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 },
+    });
+    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');
+        },
+    };
+}

package/dist/dev/health.d.ts

@@ -0,0 +1,72 @@
+import { type GaonNats, type StreamStat } from '@gaonjs/async';
+import type { GaonConfig } from '@gaonjs/config';
+/** registerDevHealth 가 프로브에 쓰는 컨텍스트(serve 가 채운다). */
+export interface DevHealthContext {
+    readonly cwd: string;
+    readonly config: GaonConfig;
+    readonly apps: readonly {
+        readonly name: string;
+        readonly dir: string;
+    }[];
+    readonly nats?: GaonNats;
+    readonly port: number;
+    readonly host: string;
+}
+export interface WebHealth {
+    readonly host: string;
+    readonly port: number;
+    readonly node: string;
+    readonly gaonjs: string;
+    readonly apps: readonly {
+        readonly name: string;
+        readonly prefix: string;
+    }[];
+}
+export type DatabaseHealth = {
+    readonly configured: false;
+} | {
+    readonly configured: true;
+    readonly connected: boolean;
+    readonly adapter?: string;
+    readonly tables?: number;
+    readonly tableNames?: readonly string[];
+    readonly migrations?: number;
+    readonly error?: string;
+};
+export type HubHealth = {
+    readonly configured: false;
+} | {
+    readonly configured: true;
+    readonly connected: boolean;
+    readonly streams?: readonly StreamStat[];
+    readonly error?: string;
+};
+export interface DoctorHealth {
+    readonly checks: number;
+    readonly passed: number;
+    readonly warnings: number;
+    readonly errors: number;
+    readonly level: 'pass' | 'warn' | 'error';
+    /** 사전 검사 실패(프로젝트 아님 등)면 코드. */
+    readonly fatal?: string;
+}
+export interface GaonHealth {
+    readonly ok: boolean;
+    readonly env: string;
+    readonly web: WebHealth;
+    readonly database: DatabaseHealth;
+    readonly hub: HubHealth;
+    readonly doctor: DoctorHealth;
+    /** 랜딩 코드 블록용 — 실 routes.ts 원문(dev only). */
+    readonly routes: {
+        readonly path: string;
+        readonly source: string;
+    } | null;
+}
+/**
+ * 라이브 헬스 스냅샷을 계산한다. 순수 조회(부작용 없음) — 각 프로브는 독립
+ * try/catch 라 하나가 실패해도 전체가 죽지 않는다.
+ */
+export declare function computeHealth(ctx: DevHealthContext): Promise<GaonHealth>;
+/** dev 전용 진단 라우트 경로. serve(--dev)가 이 경로에 computeHealth 를 건다. */
+export declare const DEV_HEALTH_PATH = "/_gaon/health";

package/dist/dev/health.js

@@ -0,0 +1,154 @@
+/**
+ * @gaonjs/cli · dev 전용 라이브 헬스 엔드포인트 (결정 69 · W10)
+ *
+ * `GET /_gaon/health` — 방금 `gaon new` 로 만든 앱이 "실제로 살아 있는지" 를
+ * 랜딩(Home/Index.vue)이 라이브로 보여주기 위한 dev 전용 진단 소스다.
+ *
+ * dev-only by construction:
+ *   `gaon dev` 는 `gaon serve` 를 자식으로 띄우고(commands/dev.ts), 그때
+ *   serve 에 `--dev` 를 넘긴다. serve 는 `--dev` 일 때만 이 라우트를 등록한다
+ *   (serve.ts). 운영 `gaon serve`(플래그 없음)는 등록조차 하지 않으므로
+ *   production 에 노출되지 않는다(§CLAUDE.md 6 · handover-w10 §3.5·§5).
+ *
+ * 층 배치: 이 모듈은 doctor(computeDoctorResult)·data introspection·async
+ * 스트림 통계를 import 하므로 **cli 층**에 둔다. web/config 에 두면
+ * cli→web/config→cli 역방향 사이클이 된다(handover-w10 §5-3).
+ *
+ * 모든 프로브는 개별 try/catch — 하나가 실패해도 나머지 카드는 채운다.
+ * 조회 실패를 0/true 로 가장하지 않는다(결정 60 · 과대 약속 금지).
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VERSION } from '@gaonjs/core';
+import { getConnection, hasConnection, snapshotFromDb, postgresDialect, MIGRATIONS_TABLE, } from '@gaonjs/data';
+import { streamStats } from '@gaonjs/async';
+import { computeDoctorResult } from '../doctor.js';
+/** web 앱은 관례상 프리픽스 '/', 그 외는 '/<앱>'(dispatch.prefixFor 와 정합). */
+function prefixFor(name) {
+    return name === 'web' ? '/' : `/${name}`;
+}
+async function probeDatabase(config) {
+    const main = config.db?.main;
+    if (!main)
+        return { configured: false };
+    const adapter = main.adapter;
+    try {
+        if (!hasConnection('main')) {
+            return { configured: true, connected: false, adapter, error: '커넥션 미등록' };
+        }
+        const db = getConnection('main');
+        // introspect 자체가 실 쿼리 — DB 가 죽어 있으면 여기서 throw → connected:false.
+        const snap = await snapshotFromDb(db, postgresDialect);
+        const tableNames = Object.keys(snap)
+            .filter((t) => t !== MIGRATIONS_TABLE)
+            .sort();
+        let migrations = 0;
+        try {
+            const row = await db
+                .selectFrom(MIGRATIONS_TABLE)
+                .select((eb) => eb.fn.countAll().as('c'))
+                .executeTakeFirst();
+            migrations = Number(row?.c ?? 0);
+        }
+        catch {
+            // _gaon_migrations 미생성(마이그레이션 이력 없음) — 0.
+            migrations = 0;
+        }
+        return {
+            configured: true,
+            connected: true,
+            adapter,
+            tables: tableNames.length,
+            tableNames,
+            migrations,
+        };
+    }
+    catch (err) {
+        return {
+            configured: true,
+            connected: false,
+            adapter,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function probeHub(config, nats) {
+    if (!config.nats)
+        return { configured: false };
+    if (!nats)
+        return { configured: true, connected: false };
+    const connected = !nats.nc.isClosed();
+    if (!connected)
+        return { configured: true, connected: false };
+    try {
+        const streams = await streamStats(nats);
+        return { configured: true, connected: true, streams };
+    }
+    catch (err) {
+        return {
+            configured: true,
+            connected: true,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function probeDoctor(cwd) {
+    try {
+        const result = await computeDoctorResult({ cwd });
+        if (result.fatal) {
+            return { checks: 0, passed: 0, warnings: 0, errors: 0, level: 'error', fatal: result.fatal.code };
+        }
+        const passed = result.passed.length;
+        const warnings = result.warnings.length;
+        const errors = result.errors.length;
+        const level = errors > 0 ? 'error' : warnings > 0 ? 'warn' : 'pass';
+        return { checks: passed + warnings + errors, passed, warnings, errors, level };
+    }
+    catch (err) {
+        return {
+            checks: 0,
+            passed: 0,
+            warnings: 0,
+            errors: 0,
+            level: 'error',
+            fatal: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** 랜딩 코드 블록용 routes.ts 원문. web 앱 우선, 없으면 첫 앱. 실패는 null. */
+function readRoutesSource(ctx) {
+    const web = ctx.apps.find((a) => a.name === 'web') ?? ctx.apps[0];
+    if (!web)
+        return null;
+    const path = join(web.dir, 'routes.ts');
+    try {
+        return { path: `apps/${web.name}/routes.ts`, source: readFileSync(path, 'utf8') };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 라이브 헬스 스냅샷을 계산한다. 순수 조회(부작용 없음) — 각 프로브는 독립
+ * try/catch 라 하나가 실패해도 전체가 죽지 않는다.
+ */
+export async function computeHealth(ctx) {
+    const [database, hub, doctor] = await Promise.all([
+        probeDatabase(ctx.config),
+        probeHub(ctx.config, ctx.nats),
+        probeDoctor(ctx.cwd),
+    ]);
+    const web = {
+        host: ctx.host,
+        port: ctx.port,
+        node: process.version,
+        gaonjs: VERSION,
+        apps: ctx.apps.map((a) => ({ name: a.name, prefix: prefixFor(a.name) })),
+    };
+    const ok = doctor.level !== 'error' &&
+        (database.configured === false || database.connected) &&
+        (hub.configured === false || hub.connected);
+    return { ok, env: process.env.NODE_ENV ?? 'development', web, database, hub, doctor, routes: readRoutesSource(ctx) };
+}
+/** dev 전용 진단 라우트 경로. serve(--dev)가 이 경로에 computeHealth 를 건다. */
+export const DEV_HEALTH_PATH = '/_gaon/health';

package/dist/dev/index.d.ts

@@ -12,5 +12,7 @@ export { startTscWatchers, killChild } from './tsc.js';
 export type { TscWatcherOptions, TscWatcherHandle } from './tsc.js';
 export { startRestartWatcher, isRestartChange, resolveWatchRoots } from './watcher.js';
 export type { RestartWatcherOptions, RestartWatcherHandle } from './watcher.js';
+export { startFrontendBuild } from './frontend-build.js';
+export type { FrontendBuildHandle, StartFrontendBuildOptions } from './frontend-build.js';
 export { createGaonViteServer } from './vite.js';
 export type { GaonViteServer, CreateGaonViteServerOptions } from './vite.js';

package/dist/dev/index.js

@@ -8,5 +8,7 @@ export { createDevConsole } from './console.js';
 export { findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, } from './docker.js';
 export { startTscWatchers, killChild } from './tsc.js';
 export { startRestartWatcher, isRestartChange, resolveWatchRoots } from './watcher.js';
+// 프론트 번들 watch 빌드 (결정 67)
+export { startFrontendBuild } from './frontend-build.js';
 // Vite dev server 프로그램적 기동 (M3-runtime) — dev.ts 배선은 M1 이 통합.
 export { createGaonViteServer } from './vite.js';

package/dist/doctor.d.ts

@@ -52,6 +52,18 @@ export interface DoctorFixReport {
     /** 실제로 편집이 일어났는지(--yes 여부). */
     readonly applied: boolean;
 }
+/**
+ * doctor 검사를 실행해 결과만 반환한다 — **stdout 에 아무것도 쓰지 않는다.**
+ * runDoctorCommand 는 CLI 진입점이라 결과를 stdout 으로 흘리지만, 프로그램에서
+ * (예: dev 헬스 엔드포인트가) 결과가 필요할 때는 이 함수를 쓴다.
+ *
+ * fatal(프로젝트 아님 · TS API 없음)도 write 없이 DoctorResult.fatal 로 담아
+ * 반환한다. --fix 는 다루지 않는다(읽기 전용).
+ */
+export declare function computeDoctorResult(opts?: {
+    readonly cwd?: string;
+    readonly checks?: readonly DoctorRule[];
+}): Promise<DoctorResult>;
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
  *

package/dist/doctor.js

@@ -92,6 +92,55 @@ const CHECKERS = {
     'page-filename': checkPageFilename,
     'auth-wiring': checkAuthWiring,
 };
+/**
+ * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는
+ * 계속 — 그 규칙만 error 리포트로 대체한다(부분 결과 확보).
+ */
+async function runRules(root, rules) {
+    const reports = [];
+    for (const rule of rules) {
+        const fn = CHECKERS[rule];
+        try {
+            reports.push(await fn(root));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            reports.push({
+                rule,
+                issues: [
+                    {
+                        rule,
+                        level: 'error',
+                        message: `${rule} 검사 중 예외 발생: ${msg}\n` +
+                            `→ 나머지 규칙만 임시로 실행하려면 '--check=<다른 규칙>' 를 쓰세요.`,
+                        detail: { thrown: msg },
+                    },
+                ],
+            });
+        }
+    }
+    return reports;
+}
+/**
+ * doctor 검사를 실행해 결과만 반환한다 — **stdout 에 아무것도 쓰지 않는다.**
+ * runDoctorCommand 는 CLI 진입점이라 결과를 stdout 으로 흘리지만, 프로그램에서
+ * (예: dev 헬스 엔드포인트가) 결과가 필요할 때는 이 함수를 쓴다.
+ *
+ * fatal(프로젝트 아님 · TS API 없음)도 write 없이 DoctorResult.fatal 로 담아
+ * 반환한다. --fix 는 다루지 않는다(읽기 전용).
+ */
+export async function computeDoctorResult(opts = {}) {
+    const root = resolve(opts.cwd ?? process.cwd());
+    if (!detectProject(root)) {
+        return { passed: [], warnings: [], errors: [], fatal: fatalNoProject(root) };
+    }
+    if (!checkTypeScriptApi()) {
+        const installed = ts.version;
+        return { passed: [], warnings: [], errors: [], fatal: fatalTsApiMissing(installed) };
+    }
+    const rules = opts.checks && opts.checks.length ? opts.checks : ALL_RULES;
+    return makeResult(await runRules(root, rules));
+}
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
  *
@@ -139,30 +188,7 @@ export async function runDoctorCommand(opts = {}) {
         return result;
     }
     const rules = opts.checks && opts.checks.length ? opts.checks : ALL_RULES;
-    const reports = [];
-    for (const rule of rules) {
-        const fn = CHECKERS[rule];
-        try {
-            reports.push(await fn(root));
-        }
-        catch (err) {
-            // 규칙 하나가 크래시해도 나머지 규칙 실행은 계속한다. 사용자는
-            // 크래시 대신 어느 규칙이 왜 실패했는지 안내받는다.
-            const msg = err instanceof Error ? err.message : String(err);
-            reports.push({
-                rule,
-                issues: [
-                    {
-                        rule,
-                        level: 'error',
-                        message: `${rule} 검사 중 예외 발생: ${msg}\n` +
-                            `→ 나머지 규칙만 임시로 실행하려면 '--check=<다른 규칙>' 를 쓰세요.`,
-                        detail: { thrown: msg },
-                    },
-                ],
-            });
-        }
-    }
+    const reports = await runRules(root, rules);
     const baseResult = makeResult(reports);
     // --fix 가 없으면 종전 동작 그대로.
     if (!opts.fix) {

package/dist/generate.js

@@ -32,8 +32,11 @@ const TEMPLATES = [
     { 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` },
-    { tpl: 'Login.vue.tpl', out: (a) => `apps/${a}/pages/auth/Login.vue` },
-    { tpl: 'Signup.vue.tpl', out: (a) => `apps/${a}/pages/auth/Signup.vue` },
+    // 결정 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)는 두 번째 부팅 경로를

package/dist/index.d.ts

@@ -10,12 +10,13 @@ export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthComma
 export { runGenerateCommand, planScaffold, parseGenerateArgs, type GenerateType, type GenerateOptions, type GenerateResult, } from "./commands/g.js";
 export { runHubCommand, type HubCommandOptions } from "./hub.js";
 export { runServeCommand, type ServeCommandOptions } from "./serve.js";
+export { computeHealth, DEV_HEALTH_PATH, type DevHealthContext, type GaonHealth, } from "./dev/health.js";
 export { runWorkCommand, type WorkCommandOptions } from "./work.js";
 export { runJobsCommand, type JobsCommandOptions } from "./jobs.js";
 export { runDbSeedCommand, loadSeed, type DbSeedOptions, type DbSeedResult } from "./db.js";
 export { runDbCommand, type DbSubcommand, type DbCommandOptions, } from "./commands/db.js";
 export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, type DbDiffOptions, type DbDiffResult, type DbMigrateOptions, type DbMigrateResult, type DbResetOptions, type DbResetResult, type ResolveDbOptions, type ResolvedDbTarget, } from "./db/index.js";
-export { runDoctorCommand, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, type DoctorResult, type DoctorResultWithFix, type DoctorCheck, type DoctorLevel, type DoctorRule, type RuleReport, type DoctorIssue, type LegacyDoctorResult, type ActionUsage, type ResponseKind, type DoctorCommandOptions, type FixOutcome, type DoctorFixReport, } from "./doctor.js";
+export { runDoctorCommand, computeDoctorResult, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, type DoctorResult, type DoctorResultWithFix, type DoctorCheck, type DoctorLevel, type DoctorRule, type RuleReport, type DoctorIssue, type LegacyDoctorResult, type ActionUsage, type ResponseKind, type DoctorCommandOptions, type FixOutcome, type DoctorFixReport, } from "./doctor.js";
 export { FIXERS, FIXER_CAPABILITIES, fixDependencyDirection, fixDomainToSharedTypeOnly, type Fixer, type FixerCapability, type FixerPlan, } from "./doctor/fixers/index.js";
 export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {

package/dist/index.js

@@ -36,12 +36,15 @@ export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthComma
 export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
 export { runServeCommand } from "./serve.js";
+// dev 전용 라이브 헬스(결정 69). serve(--dev)가 등록하고, 브라우저 e2e 층이
+// serve --dev 를 재현하기 위해 재사용한다.
+export { computeHealth, DEV_HEALTH_PATH, } from "./dev/health.js";
 export { runWorkCommand } from "./work.js";
 export { runJobsCommand } from "./jobs.js";
 export { runDbSeedCommand, loadSeed } from "./db.js";
 export { runDbCommand, } from "./commands/db.js";
 export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, } from "./db/index.js";
-export { runDoctorCommand, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
+export { runDoctorCommand, computeDoctorResult, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
 export { FIXERS, FIXER_CAPABILITIES, fixDependencyDirection, fixDomainToSharedTypeOnly, } from "./doctor/fixers/index.js";
 export { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
@@ -191,7 +194,9 @@ export function runCli(argv, opts = {}) {
         const hostIdx = argv.indexOf("--host");
         const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
         const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
-        void runServeCommand({ json: argv.includes("--json"), port, host }).catch((err) => {
+        // --dev: dev 전용 진단 라우트(/_gaon/health) 등록. gaon dev 가 자식
+        // serve 에 넘긴다(결정 69 · dev-only by construction).
+        void runServeCommand({ json: argv.includes("--json"), port, host, dev: argv.includes("--dev") }).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
             process.exitCode = 1;

package/dist/serve.d.ts

@@ -5,6 +5,12 @@ export interface ServeCommandOptions {
     readonly port?: number;
     /** 리슨 호스트. 우선순위: 옵션 > config.web.host > '0.0.0.0'. */
     readonly host?: string;
+    /**
+     * dev 모드(gaon dev 자식). true 면 dev 전용 진단 라우트(/_gaon/health)를
+     * 등록한다. 운영 serve 는 이 플래그 없이 실행되어 진단 라우트가 노출되지
+     * 않는다(결정 69 · dev-only by construction).
+     */
+    readonly dev?: boolean;
     /** 프로세스 시그널(테스트 주입). 기본 process. */
     readonly signals?: {
         on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;

package/dist/serve.js

@@ -14,6 +14,7 @@
 import { loadDotEnv } from '@gaonjs/core';
 import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
 import { registerTsResolve } from './tsResolve.js';
+import { computeHealth, DEV_HEALTH_PATH } from './dev/health.js';
 function humanEvent(e) {
     switch (e.kind) {
         case 'starting': {
@@ -54,6 +55,14 @@ export async function runServeCommand(opts = {}) {
     const port = opts.port ??
         config.web?.port ??
         (process.env.PORT ? Number(process.env.PORT) : 3000);
+    // dev 전용 진단 라우트(결정 69). listen 전에 등록한다 — 운영 serve 는
+    // opts.dev 가 없어 등록되지 않으므로 /_gaon/health 는 production 에 없다.
+    // wired.app 은 여기서 FastifyInstance 로 해상되므로(cli 는 fastify 타입을
+    // 직접 의존하지 않는다) 라우트 등록은 serve 층에서 인라인으로 한다.
+    if (opts.dev) {
+        const healthCtx = { cwd, config, apps: wired.apps, nats: wired.nats, port, host };
+        wired.app.get(DEV_HEALTH_PATH, async () => computeHealth(healthCtx));
+    }
     await wired.app.listen({ host, port });
     const displayHost = host === '0.0.0.0' ? 'localhost' : host;
     emit({ kind: 'listening', host, port, url: `http://${displayHost}:${port}` });

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

@@ -5,7 +5,7 @@ import { User } from '../../../domain/models/User.js'
 export default controller({
   // GET /registration/new — 회원가입 폼
   async new() {
-    return this.render('auth/Signup', { error: null as string | null, csrf: this.csrfToken() })
+    return this.render('Auth/Signup', { error: null as string | null, csrf: this.csrfToken() })
   },
   // POST /registration — 회원가입
   async create() {

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

@@ -5,7 +5,7 @@ import { User } from '../../../domain/models/User.js'
 export default controller({
   // GET /session/new — 로그인 폼
   async new() {
-    return this.render('auth/Login', { error: null as string | null, csrf: this.csrfToken() })
+    return this.render('Auth/Login', { error: null as string | null, csrf: this.csrfToken() })
   },
   // POST /session — 로그인
   async create() {
@@ -16,7 +16,7 @@ export default controller({
       this.auth.login(user)
       return this.redirect('/dashboard')
     }
-    return this.render('auth/Login', {
+    return this.render('Auth/Login', {
       error: '이메일 또는 비밀번호가 올바르지 않습니다.' as string | null,
       csrf: this.csrfToken(),
     })

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

@@ -36,7 +36,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 9. **실시간은 v1 포함**(§7): 웹서버 ↔ 허브는 TCP 지속 연결 · NATS 는
    broadcast 전용(errata E-2). 운영 프로세스는 serve·work·hub 3종.
 10. **인증·폼은 Inertia SPA**(§6 · SSR 아님). 로그인/회원가입은
-    `this.render('auth/Login')` + `Inertia.post()` → 서버 redirect.
+    `this.render('Auth/Login')` + `Inertia.post()` → 서버 redirect.
     REST + `fetch()` 는 API 앱(JWT) 전용.
 11. **컴포저블·레이아웃**(errata E-5): 컴포저블은 컴포넌트와 대칭
     (`apps/<앱>/composables/` + `shared/composables/`, `use` 접두사).

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

@@ -456,6 +456,11 @@ gaon db seed          # domain/seed.ts 실행
   잡으므로 이 함정 자체가 없다 — **손작성 마이그는 diff 로 표현 못 하는 것에만**
   쓴다(rename·백필·수동 DDL).
 
+  **단, 요구받은 마이그레이션을 생략하라는 뜻이 아니다** (결정 66). 지시나 리뷰가
+  마이그레이션 파일을 명시적으로 요구하면 만들되, 위 방식(참조 대상을 같은
+  파일에서 `ifNotExists()` 로 함께 보장)으로 함정을 피한다. 이 규칙은 마이그를
+  **쓸지 말지**가 아니라 **어떻게 쓸지**를 정한다.
+
 - **손작성 마이그는 `db/migrations/<파일명>.ts`** 에 두고 `up(db)`·`down(db)`
   (Kysely) 를 export 한다. **파일명이 곧 버전 키** — `0001_add_posts.ts`
   시퀀스든 `20260724_add_posts.ts` 타임스탬프든 사전순 정렬이 안정적이면 된다