@gaonjs/cli 0.55.0 → 0.57.0

package/dist/commands/dev.js

@@ -30,6 +30,7 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { loadDotEnv, VERSION } from '@gaonjs/core';
 import { registerTsResolve } from '../tsResolve.js';
+import { defaultNodeEnv } from '../nodeEnv.js';
 import { startDev, resolveDevLayout } from '../dev.js';
 import { generateTablesDts, watchDir } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
@@ -84,7 +85,11 @@ function spawnServe(args) {
         // 셸에서 Ctrl+C 를 누르면 자식도 같이 SIGINT 를 받는데(같은 프로세스
         // 그룹), serve 는 자체 handler 로 graceful 종료하므로 안전.
         stdio: ['ignore', 'pipe', 'pipe'],
-        env: { ...process.env },
+        // 결정 430: 부모의 **현재** env 가 아니라 dev 진입 시점 스냅샷을 준다. 부모 안에서
+        // 도는 라이브러리(vite build 는 이 프로세스에서 실행된다 · dev/build.ts)가 나중에
+        // process.env 를 만져도 자식이 흔들리지 않는다 — 최초 자식은 멀쩡한데 재기동된
+        // 자식만 오염되던 split-brain 을 구조로 제거한다.
+        env: args.env,
     });
     child.stdout?.on('data', (b) => args.console.pipe('serve', b, 'info'));
     child.stderr?.on('data', (b) => args.console.pipe('serve', b, 'error'));
@@ -104,7 +109,9 @@ function spawnProcess(args) {
     const child = spawn(node, [...nodeArgs, ...cmdArgs], {
         cwd: args.cwd,
         stdio: ['ignore', 'pipe', 'pipe'],
-        env: { ...process.env, ...args.extraEnv },
+        // 결정 430: spawnServe 와 같은 스냅샷 규칙 — hub 는 재기동하지 않으므로, 부모 env 를
+        // 그때그때 읽으면 hub 와 재기동된 serve·work 의 NODE_ENV 가 갈렸다(split-brain).
+        env: { ...args.env, ...args.extraEnv },
     });
     child.stdout?.on('data', (b) => args.console.pipe(args.kind, b, 'info'));
     child.stderr?.on('data', (b) => args.console.pipe(args.kind, b, 'error'));
@@ -164,6 +171,15 @@ export async function runDevCommand(opts = {}) {
     const signals = opts.signals ?? process;
     registerTsResolve();
     loadDotEnv(cwd);
+    // 결정 430: 모드는 명령이 정한다 — `gaon dev` 는 development. **vite 기동보다 먼저**
+    // 잡아야 한다: 아래 startFrontendBuild 가 vite.build 를 이 프로세스 안에서 부르는데,
+    // vite 의 resolveConfig(build)가 NODE_ENV 미설정이면 process.env.NODE_ENV 에
+    // 'production' 을 꽂는다(vite 7 config.js `isNodeEnvSet` 분기 · 2026-08-06 실측).
+    // 그러면 파일 저장으로 재기동된 serve 자식이 production 을 상속해 스캐폴드 dev
+    // 플레이스홀더 secret 이 prod 세션 게이트(결정 255)에 걸려 즉사했다.
+    defaultNodeEnv('development');
+    // 자식(serve·work·hub)에 물려줄 env 스냅샷 — 여기서 고정한다(결정 430).
+    const childEnv = { ...process.env };
     const consoleOut = createDevConsole({ json, timestamp: opts.timestamp });
     const startedAt = Date.now();
     consoleOut.log('dev', `gaon dev · 시작 (v${VERSION}) — ${cwd}`);
@@ -231,6 +247,7 @@ export async function runDevCommand(opts = {}) {
             port: opts.port,
             host: opts.host,
             console: consoleOut,
+            env: childEnv,
             onExit: (code, signal) => {
                 if (shuttingDown)
                     return;
@@ -257,11 +274,12 @@ export async function runDevCommand(opts = {}) {
             cwd,
             json,
             console: consoleOut,
+            env: childEnv,
             // dev 워커는 잡을 병렬 처리한다(기본 1 → DEV_WORKER_CONCURRENCY). 헤드오브라인
             // 블로킹을 없애 개발 반복을 빠르게 하고, 분산 락(중첩 방지) 같은 동시성 속성이
             // 단일 dev 워커에서도 관측되게 한다. 사용자가 GAON_WORKER_CONCURRENCY 를 이미
             // 주면 그 값을 존중한다(override 하지 않음).
-            extraEnv: process.env.GAON_WORKER_CONCURRENCY == null || process.env.GAON_WORKER_CONCURRENCY === ''
+            extraEnv: childEnv.GAON_WORKER_CONCURRENCY == null || childEnv.GAON_WORKER_CONCURRENCY === ''
                 ? { GAON_WORKER_CONCURRENCY: String(DEV_WORKER_CONCURRENCY) }
                 : undefined,
             onExit: (code, signal) => {
@@ -292,6 +310,7 @@ export async function runDevCommand(opts = {}) {
             cwd,
             json,
             console: consoleOut,
+            env: childEnv,
             onExit: (code, signal) => {
                 if (shuttingDown)
                     return;

package/dist/commands/test.js

@@ -94,8 +94,19 @@ async function provisionTestDatabases(cwd, json, onOutput) {
     if (dbs.length === 0)
         return true;
     const prepared = [];
+    // 결정 279·292: 문서형(mongodb)은 SQL 프로비저닝(CREATE DATABASE + 마이그레이션)이 없다 —
+    // 순회에서 건너뛰고 보고에만 남긴다. 이 skip 이 없으면 SQL 전용 deriveTestDatabaseConfig/
+    // ensureTestDatabaseExists 가 몽고 커넥션에 pg/mysql 드라이버로 붙으려다 throw 해,
+    // 몽고 커넥션이 하나라도 있는 프로젝트는 `gaon test` 가 테스트 실행 전에 즉사했다
+    // (testkit·`gaon db` 는 이미 건너뛰는데 CLI test 만 빠진 비대칭). 테스트 레인의 몽고
+    // 커넥션 자체는 connectTestDatabase(@gaonjs/config testkit)가 등록한다.
+    const skippedMongo = [];
     try {
         for (const [key, cfg] of dbs) {
+            if (cfg.adapter === 'mongodb') {
+                skippedMongo.push(key);
+                continue;
+            }
             const testCfg = deriveTestDatabaseConfig(cfg);
             await ensureTestDatabaseExists(testCfg);
             const res = await runDbMigrate({
@@ -130,10 +141,23 @@ async function provisionTestDatabases(cwd, json, onOutput) {
     finally {
         await destroyAllConnections();
     }
-    if (json)
-        writeOut(JSON.stringify({ kind: 'provisioned', dbs: prepared }) + '\n');
-    else
-        writeOut(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
+    if (json) {
+        writeOut(JSON.stringify({
+            kind: 'provisioned',
+            dbs: prepared,
+            skipped: skippedMongo.map((db) => ({ db, adapter: 'mongodb', reason: 'documental-no-migration' })),
+        }) + '\n');
+    }
+    else {
+        // SQL 커넥션이 하나도 없으면(문서형 전용 프로젝트) "준비 완료 ()" 대신 건너뜀만 알린다.
+        if (prepared.length > 0) {
+            writeOut(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
+        }
+        if (skippedMongo.length > 0) {
+            writeOut(`  gaon test · 문서형(mongodb) 커넥션 건너뜀: ${skippedMongo.join(', ')} — 문서형은 마이그레이션이 없습니다(§7.4).\n` +
+                `    → 테스트 레인의 몽고 커넥션은 test/setup.ts 의 connectTestDatabase() 가 <db>_test 로 등록합니다(결정 279).\n`);
+        }
+    }
     return true;
 }
 /**

package/dist/doctor/auth-wiring.js

@@ -12,6 +12,7 @@ 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';
+import { jwtSecretEnvFor } from '../generate.js';
 // 결정 140(12차 W1): 판정 전 주석/문자열을 지운다. `// session:` 주석이나 문자열
 // 안의 우연한 일치가 배선으로 오탐되면 보안 검사(세션·CSRF)가 통째로 skip 된다.
 /** 컨트롤러 소스가 인증 표면을 쓰는지 판정한다(단위 테스트 진입점). */
@@ -57,10 +58,12 @@ export async function checkAuthWiring(cwd) {
                 file: authFiles[0],
                 message: `인증 배선 누락: apps/${app} 컨트롤러(${authFiles.join(', ')})가 requireAuth/this.auth 를 쓰는데 ` +
                     `${acRel} 에 auth 배선이 없습니다. 이대로면 로그인해도 currentUser 가 항상 null 입니다(결정 59).\n` +
-                    `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
+                    `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요(세션 앱 · 정본):\n` +
                     `   session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' },\n` +
                     `   auth: { loadUser, loginRedirect: '/session/new' }  // import { loadUser } from './auth.js'\n` +
-                    `→ loadUser 가 없으면 \`gaon g auth --app ${app}\` 스캐폴드가 apps/${app}/auth.ts 에 만들어 줍니다.`,
+                    `→ API(JWT) 앱이라면 세션 대신 토큰 배선입니다(결정 337·338 — 세션·loginRedirect 없음):\n` +
+                    `   auth: { strategy: 'jwt', secret: process.env.${jwtSecretEnvFor(app)} ?? '32자 이상 dev 비밀', loadUser }\n` +
+                    `→ loadUser 가 없으면 \`gaon g auth --app ${app}\`(세션) 또는 \`gaon g auth --jwt --app ${app}\`(JWT) 스캐폴드가 apps/${app}/auth.ts 에 만들어 줍니다.`,
                 detail: { app, controllers: authFiles },
             });
         }

package/dist/doctor/channel-collision.d.ts

@@ -0,0 +1,9 @@
+import type { RuleReport } from './types.js';
+/**
+ * 소스가 default 를 다른 모듈에서 그대로 재수출만 하는지 판정하고 그 모듈 지정자를 낸다.
+ * `export { default } from '...'` · `export { default as default } from '...'` ·
+ * `export * from '...'` 를 인정한다(주석 제외 후 판정).
+ */
+export declare function reexportSpecifier(source: string): string | undefined;
+/** apps/ 를 훑어 앱간 동명 채널을 낸다. */
+export declare function checkChannelCollision(cwd: string): Promise<RuleReport>;

package/dist/doctor/channel-collision.js

@@ -0,0 +1,119 @@
+// @gaonjs/cli · doctor · 앱간 동명 채널 검사 (§7 실시간)
+//
+// 채널 이름은 **전역 네임스페이스**다. 브로드캐스트 subject(`gaon.chan.<이름>`)와
+// 프레즌스 KV 키(`presence.<이름>.<멤버>`) 어디에도 앱 프리픽스가 없다(async/keys.ts).
+// 그래서 `apps/web/channels/room.ts` 와 `apps/admin/channels/room.ts` 처럼 두 앱이
+// 같은 파일명(=채널명)으로 **각자** 채널을 정의하면:
+//   · 한쪽 앱에서 broadcast 한 메시지가 다른 앱 연결로도 팬아웃되고,
+//   · 접속자 목록(presence)이 두 앱 것으로 병합되며,
+//   · 두 정의의 authorize/presenceInfo 가 갈려 한쪽의 공개 규칙이 다른 앱의 비공개
+//     메시지를 새게 한다(연결이 어느 앱 WS 로 붙었느냐로 훅이 갈리기 때문).
+// 잡·리스너의 동명 등록은 런타임에 throw 로 막지만(결정 271), 채널은 앱별 맵에
+// 따로 담겨 런타임 충돌 신호가 없다 — 그래서 정적 검사로 잡는다.
+//
+// 의도적 공유의 탈출구: 정의를 `shared/channels/<이름>.ts` 하나에 두고 각 앱 채널
+// 파일이 **재수출**하면 통과한다(정의 하나 = 훅·인가 규칙 하나 · shared 는 앱을
+// 모르므로 의존 방향 4규칙에도 맞다).
+//
+// 판정은 소스 텍스트 기반(가벼운 정적 검사) — 채널 모듈을 실행하지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, dirname } from 'node:path';
+import { stripComments } from './source-scan.js';
+/**
+ * 소스가 default 를 다른 모듈에서 그대로 재수출만 하는지 판정하고 그 모듈 지정자를 낸다.
+ * `export { default } from '...'` · `export { default as default } from '...'` ·
+ * `export * from '...'` 를 인정한다(주석 제외 후 판정).
+ */
+export function reexportSpecifier(source) {
+    const src = stripComments(source);
+    const named = src.match(/export\s*\{\s*default(?:\s+as\s+default)?\s*\}\s*from\s*['"]([^'"]+)['"]/);
+    if (named)
+        return named[1];
+    const star = src.match(/export\s*\*\s*from\s*['"]([^'"]+)['"]/);
+    if (star)
+        return star[1];
+    return undefined;
+}
+/** 모듈 지정자를 파일 기준 절대경로로 해석한다(ESM `.js` → 소스 `.ts` 정규화). */
+function resolveSpecifier(fromFile, spec) {
+    if (!spec.startsWith('.'))
+        return undefined; // 패키지 지정자는 동일성 판정 불가.
+    const abs = resolve(dirname(fromFile), spec);
+    return abs.replace(/\.js$/, '.ts');
+}
+/** apps/ 를 훑어 앱간 동명 채널을 낸다. */
+export async function checkChannelCollision(cwd) {
+    const appsDir = join(cwd, 'apps');
+    // 채널 이름 → 정의 파일들.
+    const byName = new Map();
+    for (const app of await safeListDirs(appsDir)) {
+        const chDir = join(appsDir, app, 'channels');
+        for (const file of await safeListFiles(chDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const abs = join(chDir, file);
+            const name = file.slice(0, -3);
+            const spec = reexportSpecifier(await readFile(abs, 'utf8'));
+            const entry = {
+                app,
+                rel: relative(cwd, abs),
+                reexportTarget: spec ? resolveSpecifier(abs, spec) : undefined,
+            };
+            const list = byName.get(name);
+            if (list)
+                list.push(entry);
+            else
+                byName.set(name, [entry]);
+        }
+    }
+    const issues = [];
+    for (const [name, entries] of [...byName.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        if (entries.length < 2)
+            continue;
+        // readdir 순서에 보고가 흔들리지 않게 앱 이름으로 고정한다.
+        const files = [...entries].sort((a, b) => (a.app < b.app ? -1 : a.app > b.app ? 1 : 0));
+        // 전부 같은 모듈을 재수출하면 정의는 하나다 — 의도적 공유로 인정한다.
+        const targets = files.map((f) => f.reexportTarget);
+        if (targets.every((t) => t !== undefined && t === targets[0]))
+            continue;
+        const apps = files.map((f) => f.app).join(', ');
+        const list = files.map((f) => f.rel).join(' · ');
+        // 이름 변경을 권할 대상 — web 은 프리픽스 '/' 의 기본 앱이라 되도록 그대로 두고
+        // 비-web 앱 쪽 이름을 바꾸도록 제안한다(둘 다 비-web 이면 두 번째).
+        const target = files.find((f) => f.app !== 'web') ?? files[1];
+        const renamed = `${target.app}${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+        issues.push({
+            rule: 'channel-collision',
+            level: 'error',
+            file: files[0].rel,
+            message: `앱간 동명 채널 '${name}': ${apps} 앱이 각각 정의합니다(${list}).\n` +
+                `채널 이름은 전역입니다 — 브로드캐스트 subject(gaon.chan.${name})와 프레즌스 키에 앱 프리픽스가 ` +
+                `없어 두 앱의 연결이 같은 채널로 팬아웃되고 접속자 목록이 병합됩니다. 두 정의의 authorize 가 다르면 ` +
+                `한쪽의 공개 규칙으로 다른 앱 메시지가 샙니다.\n` +
+                `→ 앱마다 이름을 분리하세요: apps/${target.app}/channels/${renamed}.ts ` +
+                `(클라이언트 useChannel('${renamed}') 도 함께 바꿉니다).\n` +
+                `→ 일부러 공유하는 채널이면 정의를 shared/channels/${name}.ts 하나에 두고 각 앱 채널 파일에서 재수출하세요:\n` +
+                `   export { default } from '../../../shared/channels/${name}.js'`,
+            detail: { channel: name, apps: files.map((f) => f.app), files: files.map((f) => f.rel) },
+        });
+    }
+    return { rule: 'channel-collision', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/dotenv-node-env.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** 한 줄이 NODE_ENV 대입이면 그 값을 낸다. 주석·export 접두·따옴표를 흡수한다. */
+export declare function nodeEnvAssignment(line: string): string | undefined;
+/** 공유 `.env` 파일에 박힌 NODE_ENV 를 경고한다. */
+export declare function checkDotenvNodeEnv(cwd: string): Promise<RuleReport>;

package/dist/doctor/dotenv-node-env.js

@@ -0,0 +1,68 @@
+// @gaonjs/cli · doctor · `.env` 의 NODE_ENV 검사 (결정 430)
+//
+// **모드는 명령이 정한다** — `gaon dev` = development · `gaon serve` = production.
+// `.env`(와 `.env.local`·`.env.example`)는 dev·prod·테스트가 **공유**하는 파일이라, 여기에
+// NODE_ENV 를 박으면 그 값이 모든 실행 모드로 새어나간다:
+//   · `NODE_ENV=production` → `gaon dev` 가 production 으로 떠 세션 쿠키 Secure(비-TLS 로컬에서
+//     로그인 불가)·dev 플레이스홀더 secret 거부(결정 255)로 부팅이 죽고, `gaon db reset` 이 거부된다.
+//   · `NODE_ENV=development` → 운영 배포가 development 로 떠 prod 게이트(플레이스홀더 secret 거부·
+//     쿠키 Secure·락 in-memory 폴백 차단)가 통째로 안 걸린다. **부팅은 green, 보안만 꺼진다.**
+// 어느 쪽이든 무신호 파손이라 정적 검사로 짚는다. fail-closed 는 아니다(warn) — 기존 프로젝트를
+// 부팅 불가로 만들지 않고, 정당한 예외(컨테이너 이미지 안에서 `.env` 를 모드별로 생성하는 파이프라인)를
+// 남긴다. 모드별 오버레이(`.env.development`·`.env.production`)는 이미 모드로 갈리므로 검사 대상이 아니다.
+//
+// 판정은 라인 텍스트 기반 — `.env` 는 셸 문법이 아니라 KEY=VALUE 목록이다(주석 `#` 제외).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * 검사 대상 — **모드를 가리지 않는** 공유 env 파일만. `.env.development` 같은 오버레이는
+ * 이름 자체가 모드라 NODE_ENV 를 적어도 새지 않는다(core loadDotEnv 가 모드별로만 얹는다).
+ */
+const SHARED_ENV_FILES = ['.env', '.env.local', '.env.example'];
+/** 한 줄이 NODE_ENV 대입이면 그 값을 낸다. 주석·export 접두·따옴표를 흡수한다. */
+export function nodeEnvAssignment(line) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#'))
+        return undefined;
+    const m = trimmed.match(/^(?:export\s+)?NODE_ENV\s*=\s*(.*)$/);
+    if (!m)
+        return undefined;
+    // 값에서 인라인 주석·따옴표를 벗긴다(빈 값도 "설정됨" 으로 본다 — 빈 NODE_ENV 가
+    // vite 의 `!!process.env.NODE_ENV` 판정을 미설정으로 만들어 production 을 꽂는다).
+    const raw = m[1].replace(/\s+#.*$/, '').trim();
+    return raw.replace(/^['"]|['"]$/g, '');
+}
+/** 공유 `.env` 파일에 박힌 NODE_ENV 를 경고한다. */
+export async function checkDotenvNodeEnv(cwd) {
+    const issues = [];
+    for (const name of SHARED_ENV_FILES) {
+        let text;
+        try {
+            text = await readFile(join(cwd, name), 'utf8');
+        }
+        catch {
+            continue; // 없으면 통과(대부분의 프로젝트에 .env.local 은 없다).
+        }
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const value = nodeEnvAssignment(lines[i]);
+            if (value === undefined)
+                continue;
+            issues.push({
+                rule: 'dotenv-node-env',
+                level: 'warning',
+                file: name,
+                line: i + 1,
+                message: `${name} 에 NODE_ENV${value === '' ? '' : `=${value}`} 이(가) 설정돼 있습니다 — 이 파일은 개발·운영이 함께 읽습니다.\n` +
+                    `모드는 **명령이 정합니다**: gaon dev = development · gaon serve = production(결정 430).\n` +
+                    `여기에 값을 박으면 그 모드가 양쪽으로 샙니다 — production 이면 gaon dev 가 쿠키 Secure·` +
+                    `dev secret 거부로 죽고, development 면 운영 serve 에서 프로덕션 안전장치(플레이스홀더 secret 거부·` +
+                    `쿠키 Secure)가 통째로 꺼집니다(부팅은 green).\n` +
+                    `→ ${name} 에서 NODE_ENV 줄을 지우세요. 특정 모드에서만 필요한 값은 .env.development / .env.production ` +
+                    `오버레이에 두고, 일회성으로 바꿀 땐 명령 앞에 붙이세요: NODE_ENV=production gaon serve`,
+                detail: { file: name, line: i + 1, value },
+            });
+        }
+    }
+    return { rule: 'dotenv-node-env', issues };
+}

package/dist/doctor/fixers/index.d.ts

@@ -14,7 +14,7 @@ export declare const FIXERS: Partial<Record<DoctorRule, Fixer>>;
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 30종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다

package/dist/doctor/fixers/index.js

@@ -28,7 +28,7 @@ export const FIXERS = {
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 30종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다
@@ -175,4 +175,14 @@ export const FIXER_CAPABILITIES = [
         hasFixer: false,
         note: '수동 · 로케일 간 누락 키는 각 카탈로그(locales/*.json)에 채우세요 — 번역문은 사람이 작성합니다(결정 216).',
     },
+    {
+        rule: 'channel-collision',
+        hasFixer: false,
+        note: '수동 · 앱마다 채널 이름을 분리(파일명 + 클라이언트 useChannel 인자 동시 변경)하거나, 의도적 공유면 정의를 shared/channels/ 하나로 옮기고 각 앱에서 재수출하세요 — 어느 쪽인지는 설계 판단이라 자동 정정하지 않습니다.',
+    },
+    {
+        rule: 'dotenv-node-env',
+        hasFixer: false,
+        note: '수동 · 공유 .env 에서 NODE_ENV 줄을 지우세요 — 모드는 명령이 정합니다(gaon dev=development · gaon serve=production · 결정 430). 지웠을 때 어떤 모드로 돌리려던 것인지는 사람이 알아야 해서 자동 정정하지 않습니다.',
+    },
 ];

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return' | 'channel-collision' | 'dotenv-node-env';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -24,17 +24,25 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 28개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 30개 모두.
  */
 /**
- * doctor 정적 검사 28종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 30종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
 export declare const ALL_RULES: readonly DoctorRule[];
+/**
+ * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
+ * `Record<DoctorRule, …>` 라 **규칙을 늘리면 여기도 채워야 컴파일된다** — 손유지
+ * 산문 열거가 뒤처져 새 검사가 help 에서 통째로 빠지던 표류를 컴파일 에러로 바꾼다
+ * (channel-collision 편입 때 실제로 한 곳이 누락됐다).
+ */
+export declare const RULE_SUMMARIES: Record<DoctorRule, string>;
 export interface DoctorCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 28 검사를 조립한다:
+ * 30 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -30,6 +30,8 @@
  * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
  * 27) locale-parity (결정 216 · 13차 W4 · 로케일 간 키 부분 누락 = fallback 조용 노출 경고)
  * 28) render-return (결정 340 · this.render/redirect/json 호출만 하고 return 누락 = 무신호 204 경고)
+ * 29) channel-collision (§7 · 앱간 동명 채널 = 전역 subject·프레즌스 병합 error)
+ * 30) dotenv-node-env (결정 430 · 공유 .env 의 NODE_ENV = 모드 누출 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -70,6 +72,8 @@ import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
 import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
 import { checkLocaleParity } from './doctor/locale-parity.js';
+import { checkChannelCollision } from './doctor/channel-collision.js';
+import { checkDotenvNodeEnv } from './doctor/dotenv-node-env.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -97,13 +101,14 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 28개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 30개 모두.
  */
 /**
- * doctor 정적 검사 28종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 30종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -136,7 +141,47 @@ export const ALL_RULES = [
     'no-import-meta-env',
     'locale-parity',
     'render-return',
+    'channel-collision',
+    'dotenv-node-env',
 ];
+/**
+ * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
+ * `Record<DoctorRule, …>` 라 **규칙을 늘리면 여기도 채워야 컴파일된다** — 손유지
+ * 산문 열거가 뒤처져 새 검사가 help 에서 통째로 빠지던 표류를 컴파일 에러로 바꾼다
+ * (channel-collision 편입 때 실제로 한 곳이 누락됐다).
+ */
+export const RULE_SUMMARIES = {
+    'response-mixing': '응답 혼용',
+    'n-plus-one': 'N+1',
+    'dependency-direction': '의존 방향',
+    connections: '커넥션',
+    'migration-diff': '마이그 diff',
+    'shared-purity': 'shared 순수',
+    'no-auto-import': '자동 import',
+    'schema-filename': '스키마 파일명',
+    'agents-doc-index': 'AGENTS 색인',
+    'column-casing': '컬럼 casing',
+    'model-filename': '모델 파일명',
+    'page-filename': '페이지 파일명',
+    'auth-wiring': '인증 배선',
+    'ui-kit-wiring': 'UI 킷 배선',
+    'route-registration': '라우트 등록',
+    'static-collision': '정적 충돌',
+    'method-override': '_method',
+    'csrf-wiring': 'CSRF 배선',
+    'internal-anchor': '내부 앵커',
+    'pageprops-destructure': 'pageProps 구조분해',
+    'async-offload': '비동기 오프로드',
+    'page-layout-breakpoint': '페이지 레이아웃 브레이크포인트',
+    'link-button-nesting': 'Link>Button 중첩',
+    'seal-security': 'seal 클라 배선·보안 역전',
+    'schema-relations': '§4.5 관계',
+    'no-import-meta-env': 'import.meta.env',
+    'locale-parity': '로케일 커버리지',
+    'render-return': 'render return 누락',
+    'channel-collision': '앱간 동명 채널',
+    'dotenv-node-env': '.env NODE_ENV',
+};
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
     'n-plus-one': checkNPlusOne,
@@ -166,6 +211,8 @@ const CHECKERS = {
     'no-import-meta-env': checkNoImportMetaEnv,
     'locale-parity': checkLocaleParity,
     'render-return': checkRenderReturn,
+    'channel-collision': checkChannelCollision,
+    'dotenv-node-env': checkDotenvNodeEnv,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/generate.d.ts

@@ -32,6 +32,11 @@ export interface ScaffoldResult {
      */
     readonly incomplete: boolean;
 }
+/**
+ * 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭).
+ * doctor auth-wiring 의 JWT 수리 안내가 같은 이름을 제시해야 해 export 한다(단일 출처).
+ */
+export declare function jwtSecretEnvFor(app: string): string;
 /**
  * 결정 155·142: `g auth --app <앱>` 이 앱별 세션 secret 환경변수를 .env·.env.example
  * 에도 시드한다. web 은 SESSION_SECRET 이 프로젝트 스캐폴드(.env.example.tpl)에 이미

package/dist/generate.js

@@ -65,8 +65,11 @@ function devSessionSecretFor(app) {
 function envSecretPlaceholderFor(app) {
     return `change-me-to-a-32-char-${app}-session-secret!!`;
 }
-/** 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭). */
-function jwtSecretEnvFor(app) {
+/**
+ * 결정 338: 앱별 JWT secret 환경변수명 — '<APP>_JWT_SECRET' (세션 secret 관례와 대칭).
+ * doctor auth-wiring 의 JWT 수리 안내가 같은 이름을 제시해야 해 export 한다(단일 출처).
+ */
+export function jwtSecretEnvFor(app) {
     return `${app.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_JWT_SECRET`;
 }
 /** .env(.example)에 시드할 앱별 JWT secret 플레이스홀더(32자 이상 · 운영은 교체 — 결정 337 가드 대상). */
@@ -382,8 +385,13 @@ export function runGenerateAuthCommand(opts = {}) {
     const app = opts.app ?? 'web';
     // 결정 338: JWT 는 API 앱 전용(§7 · web 은 세션이 정본). 형식 불량은 즉시 수리 안내.
     if (opts.jwt && (opts.app === undefined || app === 'web')) {
+        // 결정 338: API(JWT) 앱은 이 명령 **하나**가 앱 폴더째 만든다(routes·컨트롤러·app.config).
+        // 이전 힌트는 `gaon g app api && gaon g auth --jwt --app api` 를 권했는데, 앞 명령이
+        // 만든 app.config.ts·Vue 프론트(pages/layouts) 때문에 뒤 명령이 JWT 배선을 자동 추가하지
+        // 못하고 incomplete → exit 1 로 끝났다(결정 361). API 앱에는 쓰지 않는 Vue 페이지까지
+        // 남는다 — 권하는 순서가 곧 실패 경로였던 셈이라 단독 실행을 정본으로 못박는다.
         process.stderr.write(`  ✗ gaon g auth --jwt: JWT 는 API 앱 전용입니다 — 대상 API 앱을 --app 으로 지정하세요(web 불가 · 세션이 정본).\n` +
-            `  → 예: gaon g app api && gaon g auth --jwt --app api\n`);
+            `  → 예: gaon g auth --jwt --app api  (이 명령 하나가 apps/api/ 를 통째로 만듭니다 — gaon g app 을 먼저 돌리지 마세요)\n`);
         return 1;
     }
     if (opts.jwt && opts.public) {

package/dist/index.js

@@ -27,7 +27,7 @@ import { runHubCommand } from "./hub.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
 import { runDbCommand } from "./commands/db.js";
-import { runDoctorCommand, ALL_RULES } from "./doctor.js";
+import { runDoctorCommand, ALL_RULES, RULE_SUMMARIES } from "./doctor.js";
 import { runMcpCommand } from "./commands/mcp.js";
 export { startDev, resolveDevLayout, regenerateGaonOnce, } from "./dev.js";
 export { runDevCommand } from "./commands/dev.js";
@@ -111,7 +111,9 @@ function renderHelp(version = VERSION) {
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all)",
         "    gaon test -- <인자>       `--` 뒤는 vitest 로 그대로 전달 (gaon 이 안 가로챔 · 예: gaon test -- --json --reporter=json)",
-        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지·render return 누락)`,
+        // 열거는 RULE_SUMMARIES(doctor.ts) 를 단일 출처로 쓴다 — 손유지 산문이 뒤처져
+        // 새 검사가 help 에서 빠지던 표류 방지(타입이 전수 채움을 강제).
+        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · ${ALL_RULES.map((r) => RULE_SUMMARIES[r]).join("·")})`,
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -149,7 +151,7 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 28종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 30종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
@@ -170,7 +172,7 @@ export function parseDoctorChecks(argv) {
     }
     // 결정 411: 모르는 이름은 여전히 무시하되(안전 방향 — 전체 검사로 넓어짐) **조용히**
     // 넘기지 않는다. 오타 하나가 "그 검사만 돌렸다" 는 착각으로 이어지고, 전부 오타면
-    // 28종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
+    // 30종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
     if (unknown.length > 0) {
         process.stderr.write(`  ! 알 수 없는 검사 이름 무시: ${unknown.join(", ")}\n` +
             `    → 지원 이름은 gaon doctor --json 의 rule 값 또는 gaon help 참고` +
@@ -470,7 +472,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 28 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 30 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {