@gaonjs/cli 0.36.0 → 0.38.0

package/dist/commands/check.d.ts

@@ -49,15 +49,6 @@ export interface CheckReport {
     readonly regen: CheckRegen;
     readonly steps: readonly CheckStepResult[];
 }
-/**
- * 결정 170: 프로젝트가 선언한 패키지 매니저를 감지한다. `gaon new` 는
- * package.json 의 `packageManager` 필드(corepack 핀 · 결정 169)에 선택 pm 을
- * 기록하므로, `gaon check` 가 사용자 스크립트(예 build)를 돌릴 때 그 pm 으로
- * 실행해야 한다 — pnpm 하드코딩은 npm/yarn 로 스캐폴드한 프로젝트에서 pnpm 이
- * "This project is configured to use npm" 로 실행을 거부해 build 단계가 깨진다.
- * 우선순위: packageManager 필드 → 락파일 → pnpm(기본).
- */
-export declare function detectPackageManager(cwd: string): 'pnpm' | 'npm' | 'yarn';
 /**
  * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
  * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만

package/dist/commands/check.js

@@ -35,6 +35,8 @@ import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
 import { listFrontendApps, verifyAppDist } from '../dev/build.js';
 import { generateMessagesDts } from '../messages-gen.js';
+import { generateEnvDts } from '../env-gen.js';
+import { detectPackageManager, scriptRunArgs } from '../pm.js';
 /**
  * 프로젝트 스크립트 존재 여부. pnpm/npm 어느 쪽이든 `scripts.<name>` 을
  * 정의해 두면 우선 사용한다.
@@ -54,35 +56,6 @@ function hasScript(cwd, name) {
 function binExists(cwd, name) {
     return existsSync(join(cwd, 'node_modules', '.bin', name));
 }
-/**
- * 결정 170: 프로젝트가 선언한 패키지 매니저를 감지한다. `gaon new` 는
- * package.json 의 `packageManager` 필드(corepack 핀 · 결정 169)에 선택 pm 을
- * 기록하므로, `gaon check` 가 사용자 스크립트(예 build)를 돌릴 때 그 pm 으로
- * 실행해야 한다 — pnpm 하드코딩은 npm/yarn 로 스캐폴드한 프로젝트에서 pnpm 이
- * "This project is configured to use npm" 로 실행을 거부해 build 단계가 깨진다.
- * 우선순위: packageManager 필드 → 락파일 → pnpm(기본).
- */
-export function detectPackageManager(cwd) {
-    const pkgPath = join(cwd, 'package.json');
-    if (existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-            const pm = pkg.packageManager?.split('@')[0];
-            if (pm === 'pnpm' || pm === 'npm' || pm === 'yarn')
-                return pm;
-        }
-        catch {
-            // 파싱 실패는 락파일/기본으로 폴백
-        }
-    }
-    if (existsSync(join(cwd, 'pnpm-lock.yaml')))
-        return 'pnpm';
-    if (existsSync(join(cwd, 'yarn.lock')))
-        return 'yarn';
-    if (existsSync(join(cwd, 'package-lock.json')))
-        return 'npm';
-    return 'pnpm';
-}
 /**
  * 단일 서브 프로세스를 spawn 해서 stdout+stderr 를 모으고 exit 코드를
  * 돌려준다. 실행 실패(파일 없음)는 exit 127 로 매핑.
@@ -107,9 +80,10 @@ async function runStep(step, cwd) {
     const scriptName = step;
     if (hasScript(cwd, scriptName)) {
         // 결정 170: pnpm 하드코딩 대신 프로젝트 선언 pm 으로 실행(npm/yarn 스캐폴드
-        // 대응). `<pm> run <name>` 는 pnpm·npm·yarn(classic) 셋 다 동일하게 동작한다.
+        // 대응 · pm 해상은 공유 `pm.ts` 단일 소스). build/typecheck/vue-tsc 는 잔여
+        // 인자가 없어 `<pm> run <name>` 만 — pnpm·npm·yarn(classic) 동일 동작.
         const cmd = detectPackageManager(cwd);
-        const args = ['run', scriptName];
+        const args = scriptRunArgs(cmd, scriptName);
         const { exitCode, output } = await runSubprocess(cwd, cmd, args);
         // 결정 146(12차 W2): build 가 성공했으면 **등록된 앱마다** dist/<앱>/index.html 과
         // 그 문서가 참조하는 에셋이 실제로 존재하는지 검증한다. build 스크립트가 통과해도
@@ -277,6 +251,7 @@ async function regenerateGaon(cwd) {
             regenerateTables: generateTablesDts,
             regenerateRoutes: generateRoutesDts,
             regenerateMessages: generateMessagesDts,
+            regenerateEnv: generateEnvDts,
         });
         return { status: 'done', tables: result.tables, apps: result.apps };
     }

package/dist/commands/dev.d.ts

@@ -5,9 +5,16 @@
  *   1) Docker Compose  — pg · redis · nats · mailpit · minio 자동 up -d
  *   2) .gaon 워처       — tables.d.ts · routes.d.ts 재생성 (기존 M3)
  *   3) serve 자식       — 실 웹 서버(Fastify) · 소스 변경 시 재시작
- *   4) tsc / vue-tsc    — --watch 모드 · 타입 에러 즉시 리포트
- *   5) restart 워처     — apps/ · domain/ · packages/ 변경 → serve 재시작
- *   6) 통합 콘솔        — [source] 태그·색상별 · JSON 모드 지원
+ *   4) work 자식        — 워커(잡·리스너·아웃박스·스케줄) · 소스 변경 시 재시작 (결정 211)
+ *   5) hub 자식         — 실시간 허브(프레즌스 권위·중계) (결정 211)
+ *   6) tsc / vue-tsc    — --watch 모드 · 타입 에러 즉시 리포트
+ *   7) restart 워처     — apps/ · domain/ · packages/ 변경 → serve·work 재시작
+ *   8) 통합 콘솔        — [source] 태그·색상별 · JSON 모드 지원
+ *
+ * 운영 프로세스 3종(serve·work·hub · §7)을 dev 에서 모두 내장 기동한다
+ * (Rails-like all-in-one · 결정 211). 이전에는 serve 만 떠 잡·이벤트·아웃박스·
+ * 크론이 dev 에서 조용히 처리되지 않았다(work 부재) — work.ts·hub.ts 주석이
+ * 이미 "dev 가 내장 실행" 이라 명시했으나 실제로는 미배선이던 드리프트를 닫는다.
  *
  * The One Way: `gaon dev` 하나로 전부 · 옵션은 개별 debug 용만 노출.
  * fail-closed: Docker 없으면 명확 안내(§7.5.3), 목업 대체 절대 X (§9).
@@ -38,6 +45,10 @@ export interface DevCommandOptions {
     readonly noDocker?: boolean;
     /** 프론트 watch 빌드(vite build --watch) 끄기(개별 debug). */
     readonly noVite?: boolean;
+    /** 워커(work) 자동 기동 끄기(개별 debug · 결정 211). 기본 기동. */
+    readonly noWork?: boolean;
+    /** 실시간 허브(hub) 자동 기동 끄기(개별 debug · 결정 211). 기본 기동. */
+    readonly noHub?: boolean;
     /** 통합 콘솔 타임스탬프 표시. */
     readonly timestamp?: boolean;
     /** 시그널(테스트 주입 · 기본 process). */

package/dist/commands/dev.js

@@ -5,9 +5,16 @@
  *   1) Docker Compose  — pg · redis · nats · mailpit · minio 자동 up -d
  *   2) .gaon 워처       — tables.d.ts · routes.d.ts 재생성 (기존 M3)
  *   3) serve 자식       — 실 웹 서버(Fastify) · 소스 변경 시 재시작
- *   4) tsc / vue-tsc    — --watch 모드 · 타입 에러 즉시 리포트
- *   5) restart 워처     — apps/ · domain/ · packages/ 변경 → serve 재시작
- *   6) 통합 콘솔        — [source] 태그·색상별 · JSON 모드 지원
+ *   4) work 자식        — 워커(잡·리스너·아웃박스·스케줄) · 소스 변경 시 재시작 (결정 211)
+ *   5) hub 자식         — 실시간 허브(프레즌스 권위·중계) (결정 211)
+ *   6) tsc / vue-tsc    — --watch 모드 · 타입 에러 즉시 리포트
+ *   7) restart 워처     — apps/ · domain/ · packages/ 변경 → serve·work 재시작
+ *   8) 통합 콘솔        — [source] 태그·색상별 · JSON 모드 지원
+ *
+ * 운영 프로세스 3종(serve·work·hub · §7)을 dev 에서 모두 내장 기동한다
+ * (Rails-like all-in-one · 결정 211). 이전에는 serve 만 떠 잡·이벤트·아웃박스·
+ * 크론이 dev 에서 조용히 처리되지 않았다(work 부재) — work.ts·hub.ts 주석이
+ * 이미 "dev 가 내장 실행" 이라 명시했으나 실제로는 미배선이던 드리프트를 닫는다.
  *
  * The One Way: `gaon dev` 하나로 전부 · 옵션은 개별 debug 용만 노출.
  * fail-closed: Docker 없으면 명확 안내(§7.5.3), 목업 대체 절대 X (§9).
@@ -27,11 +34,18 @@ import { startDev, resolveDevLayout } from '../dev.js';
 import { generateTablesDts, watchDir } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
 import { generateMessagesDts } from '../messages-gen.js';
+import { generateEnvDts } from '../env-gen.js';
 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';
+/**
+ * dev 워커의 기본 큐 동시성(결정 211). 운영 기본은 1(보수적)이나 dev 는
+ * 잡을 병렬 처리해 반복을 빠르게 하고 동시성 속성(분산 락 등)을 단일
+ * 워커에서도 관측하게 한다. 사용자가 GAON_WORKER_CONCURRENCY 를 주면 존중.
+ */
+const DEV_WORKER_CONCURRENCY = 4;
 /**
  * gaon 셀프 경로를 찾는다. 부모가 gaon 으로 실행됐다면 argv[1] 이
  * gaonjs/dist/cli.js (또는 개발 시 packages/gaonjs/src/cli.ts). 자식
@@ -77,6 +91,26 @@ function spawnServe(args) {
     child.on('exit', (code, signal) => args.onExit(code, signal));
     return child;
 }
+/**
+ * 운영 프로세스(work·hub)를 하나 띄운다(결정 211). serve 와 동일하게 셀프 CLI
+ * 진입점을 재사용해 사용자 환경에서 강제 폴백 없이 같은 gaon 을 다시 부른다.
+ * stdout/stderr 을 통합 콘솔의 해당 소스 태그로 파이프한다.
+ */
+function spawnProcess(args) {
+    const { node, args: nodeArgs } = resolveSelfCliEntry();
+    const cmdArgs = [args.kind];
+    if (args.json)
+        cmdArgs.push('--json');
+    const child = spawn(node, [...nodeArgs, ...cmdArgs], {
+        cwd: args.cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.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'));
+    child.on('exit', (code, signal) => args.onExit(code, signal));
+    return child;
+}
 /**
  * .gaon 재생성 파이프라인(M3)을 띄운다. 로그는 통합 콘솔로 흘리고,
  * 이 모듈은 층분리를 위해 startDev 를 그대로 재사용한다.
@@ -88,6 +122,7 @@ async function startGaonRegen(args) {
         regenerateTables: generateTablesDts,
         regenerateRoutes: generateRoutesDts,
         regenerateMessages: generateMessagesDts,
+        regenerateEnv: generateEnvDts,
         watch: watchDir,
         log: (e) => {
             if (e.kind === 'ready') {
@@ -101,7 +136,14 @@ async function startGaonRegen(args) {
                     : `.gaon 재생성 대상 없음 (domain/schema · apps/* 확인)`);
             }
             else if (e.kind === 'regen') {
-                args.console.log('watcher', e.target === 'tables' ? '↻ tables.d.ts 재생성' : `↻ ${e.app}/.gaon/routes.d.ts 재생성`);
+                const label = e.target === 'tables'
+                    ? '↻ tables.d.ts 재생성'
+                    : e.target === 'messages'
+                        ? '↻ messages.d.ts 재생성'
+                        : e.target === 'env'
+                            ? '↻ env.d.ts 재생성'
+                            : `↻ ${e.app}/.gaon/routes.d.ts 재생성`;
+                args.console.log('watcher', label);
             }
             else {
                 args.console.log('watcher', '.gaon 워처 종료');
@@ -202,6 +244,69 @@ export async function runDevCommand(opts = {}) {
         });
     };
     serveChild = startServe();
+    // ── 4') work 자식(잡·리스너·아웃박스·스케줄 · 결정 211) ─────────────
+    //   work 는 도메인(잡·리스너·스케줄)을 로드하므로 serve 와 같은 파일 변경에
+    //   재시작한다. NATS 부재(예: --no-docker + 외부 NATS 없음)면 연결 실패로
+    //   종료하는데, 이는 dev 를 죽이지 않고 안내만 남긴다(fail-soft).
+    let workChild;
+    const abnormalHint = (kind) => `${kind} 자식이 비정상 종료 — NATS 가 떴는지 확인하세요(compose 재사용 또는 --no-${kind} 로 끌 수 있음).`;
+    const startWork = () => {
+        consoleOut.log('work', '▶ work 자식 프로세스 spawn');
+        return spawnProcess({
+            kind: 'work',
+            cwd,
+            json,
+            console: consoleOut,
+            // dev 워커는 잡을 병렬 처리한다(기본 1 → DEV_WORKER_CONCURRENCY). 헤드오브라인
+            // 블로킹을 없애 개발 반복을 빠르게 하고, 분산 락(중첩 방지) 같은 동시성 속성이
+            // 단일 dev 워커에서도 관측되게 한다. 사용자가 GAON_WORKER_CONCURRENCY 를 이미
+            // 주면 그 값을 존중한다(override 하지 않음).
+            extraEnv: process.env.GAON_WORKER_CONCURRENCY == null || process.env.GAON_WORKER_CONCURRENCY === ''
+                ? { GAON_WORKER_CONCURRENCY: String(DEV_WORKER_CONCURRENCY) }
+                : undefined,
+            onExit: (code, signal) => {
+                if (shuttingDown)
+                    return;
+                if (restartInFlight)
+                    return;
+                if (code === 0 || signal === 'SIGTERM' || signal === 'SIGINT')
+                    return;
+                consoleOut.log('work', abnormalHint('work'), 'warn');
+            },
+        });
+    };
+    if (opts.noWork !== true) {
+        workChild = startWork();
+    }
+    else {
+        consoleOut.log('work', '--no-work · 워커 자동 기동 비활성화');
+    }
+    // ── 4'') hub 자식(실시간 프레즌스 권위·중계 · 결정 211) ─────────────
+    //   hub 는 사용자 도메인 코드를 로드하지 않는(인프라 라우팅) 프로세스라
+    //   파일 변경에 재시작하지 않는다 — 시작 시 한 번 띄우고 종료 때만 내린다.
+    let hubChild;
+    const startHub = () => {
+        consoleOut.log('hub', '▶ hub 자식 프로세스 spawn');
+        return spawnProcess({
+            kind: 'hub',
+            cwd,
+            json,
+            console: consoleOut,
+            onExit: (code, signal) => {
+                if (shuttingDown)
+                    return;
+                if (code === 0 || signal === 'SIGTERM' || signal === 'SIGINT')
+                    return;
+                consoleOut.log('hub', abnormalHint('hub'), 'warn');
+            },
+        });
+    };
+    if (opts.noHub !== true) {
+        hubChild = startHub();
+    }
+    else {
+        consoleOut.log('hub', '--no-hub · 허브 자동 기동 비활성화');
+    }
     const restartServe = async (changed) => {
         if (shuttingDown)
             return;
@@ -212,12 +317,20 @@ export async function runDevCommand(opts = {}) {
         consoleOut.log('watcher', `↻ 재시작 — ${summary}`);
         restartInFlight = (async () => {
             try {
+                // serve·work 를 함께 재시작한다(둘 다 도메인/앱 코드를 로드).
+                const killers = [];
                 if (serveChild && serveChild.exitCode === null && serveChild.signalCode === null) {
-                    await killChild(serveChild, 3000);
+                    killers.push(killChild(serveChild, 3000));
                 }
+                if (workChild && workChild.exitCode === null && workChild.signalCode === null) {
+                    killers.push(killChild(workChild, 3000));
+                }
+                await Promise.all(killers);
                 if (shuttingDown)
                     return;
                 serveChild = startServe();
+                if (opts.noWork !== true)
+                    workChild = startWork();
             }
             finally {
                 restartInFlight = undefined;
@@ -237,7 +350,8 @@ export async function runDevCommand(opts = {}) {
             ? `▶ 재시작 워치 — ${restartWatcher.roots.map((r) => shortenPath(r, cwd)).join(', ')}`
             : `▶ 재시작 워치 — 감시 대상 없음(apps/ · domain/ 등 확인)`);
     }
-    consoleOut.log('dev', `준비 완료 — 부팅 ${Date.now() - startedAt}ms (Ctrl+C 로 종료)`);
+    const procs = ['serve', opts.noWork !== true && 'work', opts.noHub !== true && 'hub'].filter(Boolean).join(' · ');
+    consoleOut.log('dev', `준비 완료 — 부팅 ${Date.now() - startedAt}ms · 프로세스 ${procs} (Ctrl+C 로 종료)`);
     // ── 6) SIGINT/SIGTERM → graceful ────────────────────────────────
     await new Promise((resolvePromise) => {
         const stop = () => {
@@ -249,11 +363,15 @@ export async function runDevCommand(opts = {}) {
             consoleOut.log('dev', '종료 신호 수신 — 정리 중...');
             void (async () => {
                 try {
-                    // 순서: 재시작 워처 → serve → tsc → .gaon 워처 → Docker(옵션)
+                    // 순서: 재시작 워처 → serve·work·hub → tsc → .gaon 워처 → Docker(옵션)
                     restartWatcher?.close();
-                    if (serveChild) {
-                        await killChild(serveChild, 5000);
-                    }
+                    // serve·work·hub 는 서로 독립이라 병렬로 내린다. work 은 graceful
+                    // drain(진행 중 잡 대기)에 시간이 더 걸릴 수 있어 상한을 넉넉히 준다.
+                    await Promise.all([
+                        serveChild ? killChild(serveChild, 5000) : Promise.resolve(),
+                        workChild ? killChild(workChild, 8000) : Promise.resolve(),
+                        hubChild ? killChild(hubChild, 5000) : Promise.resolve(),
+                    ]);
                     if (tsc) {
                         await tsc.stop();
                     }

package/dist/commands/gen.d.ts

@@ -11,6 +11,8 @@ export interface GenResult {
     readonly tables: boolean;
     /** routes.d.ts·routes.manifest.ts 를 재생성한 앱 이름. */
     readonly apps: readonly string[];
+    /** env.d.ts 를 재생성했는가(프론트 앱 존재 · 결정 198). */
+    readonly env?: boolean;
     /** 실패 시 에러 + 수리 안내. */
     readonly error?: string;
 }

package/dist/commands/gen.js

@@ -16,6 +16,7 @@
 import { generateTablesDts } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
 import { generateMessagesDts } from '../messages-gen.js';
+import { generateEnvDts } from '../env-gen.js';
 import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
 /**
@@ -26,13 +27,14 @@ import { registerTsResolve } from '../tsResolve.js';
 export async function regenerateProjectGaon(cwd) {
     const layout = resolveDevLayout(cwd);
     if (!layout.schemaDir && layout.apps.length === 0 && !layout.localesDir) {
-        return { tables: false, apps: [], messages: false, skipped: true };
+        return { tables: false, apps: [], messages: false, env: false, skipped: true };
     }
     registerTsResolve();
     const result = await regenerateGaonOnce(layout, {
         regenerateTables: generateTablesDts,
         regenerateRoutes: generateRoutesDts,
         regenerateMessages: generateMessagesDts,
+        regenerateEnv: generateEnvDts,
     });
     return { ...result, skipped: false };
 }
@@ -46,7 +48,7 @@ export async function runGenCommand(opts = {}) {
     let result;
     try {
         const r = await regenerateProjectGaon(cwd);
-        result = { ok: true, skipped: r.skipped, tables: r.tables, apps: r.apps };
+        result = { ok: true, skipped: r.skipped, tables: r.tables, apps: r.apps, env: r.env };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -75,6 +77,8 @@ export async function runGenCommand(opts = {}) {
         for (const app of result.apps) {
             parts.push(`apps/${app}/.gaon/routes.d.ts`, `apps/${app}/.gaon/routes.manifest.ts`);
         }
+        if (result.env)
+            parts.push('.gaon/env.d.ts');
         process.stdout.write(`  ✓ gaon gen — ${parts.join(', ')}\n`);
     }
     return result.ok ? 0 : 1;

package/dist/commands/new.js

@@ -179,6 +179,13 @@ export async function runNewCommand(name, opts = {}) {
         gaonjsVersion,
         packageManager: PACKAGE_MANAGER_PINS[pm],
     });
+    // 결정 198(F-9 ②): env.d.ts 축은 `.env` 를 타입 출처로 요구한다(프론트 앱 전제). 스캐폴드가
+    // `.env.example` 만 남기면 `gaon new` 직후 `gaon check` 가 `.env` 부재로 실패한다 — 첫 실행이
+    // 바로 green 이도록 `.env.example` 내용 그대로 `.env` 도 함께 심는다(.gitignore 로 커밋 제외).
+    const envExample = files.find((f) => f.path === '.env.example');
+    if (envExample && !files.some((f) => f.path === '.env')) {
+        files.push({ path: '.env', contents: envExample.contents });
+    }
     let filesCreated = 0;
     try {
         mkdirSync(root, { recursive: true });

package/dist/commands/test.d.ts

@@ -6,6 +6,7 @@ export interface TestCommandOptions {
 }
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
- * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ * user script 경로는 프로젝트 선언 pm 으로 실행하며(결정 170), 인자 전달 관례는
+ * pm 별로 갈린다(pnpm·npm = `--` 분리 · yarn classic = 직접) — `scriptRunArgs`.
  */
 export declare function runTestCommand(args?: readonly string[], opts?: TestCommandOptions): Promise<number>;

package/dist/commands/test.js

@@ -12,7 +12,8 @@
  *   (기본)         둘 다 실행
  *
  * 실행 경로 우선순위:
- *   1) 사용자 package.json 의 `test` 스크립트가 있으면 `pnpm test -- <args>`
+ *   1) 사용자 package.json 의 `test` 스크립트가 있으면 `<pm> run test`(결정 170 ·
+ *      프로젝트 선언 pm · 인자 전달은 pnpm/npm `--` · yarn classic 직접)
  *   2) 로컬 node_modules/.bin/vitest 가 있으면 직접 spawn(`run` 모드)
  *   3) 둘 다 없으면 exit 127 + 설치 안내
  *
@@ -26,6 +27,7 @@ import { loadGaonConfig } from '@gaonjs/config';
 import { deriveTestDatabaseConfig, ensureTestDatabaseExists, destroyAllConnections, } from '@gaonjs/data';
 import { registerTsResolve } from '../tsResolve.js';
 import { runDbMigrate } from '../db/migrate.js';
+import { detectPackageManager, scriptRunArgs } from '../pm.js';
 /** 사용자 프로젝트에 `test` 스크립트가 있는지. */
 function hasTestScript(cwd) {
     const pkgPath = join(cwd, 'package.json');
@@ -118,7 +120,8 @@ async function provisionTestDatabases(cwd, json) {
 }
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
- * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ * user script 경로는 프로젝트 선언 pm 으로 실행하며(결정 170), 인자 전달 관례는
+ * pm 별로 갈린다(pnpm·npm = `--` 분리 · yarn classic = 직접) — `scriptRunArgs`.
  */
 export async function runTestCommand(args = [], opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
@@ -135,9 +138,12 @@ export async function runTestCommand(args = [], opts = {}) {
     let cmd;
     let spawnArgs;
     if (hasTestScript(cwd)) {
-        cmd = 'pnpm';
-        // pnpm test -- <extras> — `--` 로 뒤 인자를 스크립트에 전달.
-        spawnArgs = ['test', ...(passthrough.length ? ['--', ...passthrough] : [])];
+        // 결정 170 W1: pnpm 하드코딩 대신 프로젝트 선언 pm 으로 test 스크립트 실행
+        // (npm/yarn 스캐폴드 대응 · 공유 `pm.ts` 단일 소스). passthrough(필터 등)는
+        // pnpm·npm 은 `--` 로, yarn(classic)은 `--` 없이 전달 — scriptRunArgs 가 처리.
+        const pm = detectPackageManager(cwd);
+        cmd = pm;
+        spawnArgs = scriptRunArgs(pm, 'test', passthrough);
     }
     else {
         const vitestBin = join(cwd, 'node_modules', '.bin', 'vitest');

package/dist/dev/console.d.ts

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

package/dist/dev/console.js

@@ -23,6 +23,8 @@ const SOURCE_COLOR = {
     dev: '\x1b[35m', // magenta — 오케스트레이터
     docker: '\x1b[34m', // blue — 인프라
     serve: '\x1b[32m', // green — 웹 서버
+    work: '\x1b[93m', // bright yellow — 워커(잡·리스너·아웃박스·스케줄)
+    hub: '\x1b[94m', // bright blue — 실시간 허브
     watcher: '\x1b[36m', // cyan — 파일 감시
     tsc: '\x1b[33m', // yellow — 타입 검사
     'vue-tsc': '\x1b[95m', // bright magenta — vue 전용

package/dist/dev.d.ts

@@ -15,6 +15,12 @@ export interface DevLayout {
     readonly localesDir?: string;
     /** .gaon/messages.d.ts */
     readonly messagesOut: string;
+    /** 프론트 진입(index.html)이 있는 앱이 하나라도 있는가 — env 축 적용 조건(결정 198). */
+    readonly hasFrontendApps: boolean;
+    /** 프로젝트 루트 `.env`(env 축 타입 출처 · 결정 198 · C). */
+    readonly envFile: string;
+    /** .gaon/env.d.ts */
+    readonly envOut: string;
 }
 export interface DevDeps {
     readonly layout: DevLayout;
@@ -22,6 +28,8 @@ export interface DevDeps {
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
     /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
     regenerateMessages?(localesDir: string, out: string): unknown;
+    /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
+    regenerateEnv?(envFile: string, out: string): unknown;
     watch(dir: string, opts: WatchOptions): WatchHandle;
     log(event: DevEvent): void;
     onError(err: Error): void;
@@ -32,7 +40,7 @@ export type DevEvent = {
     readonly apps: string[];
 } | {
     readonly kind: 'regen';
-    readonly target: 'tables' | 'routes' | 'messages';
+    readonly target: 'tables' | 'routes' | 'messages' | 'env';
     readonly app?: string;
 } | {
     readonly kind: 'stopped';
@@ -52,6 +60,8 @@ export interface RegenDeps {
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
     /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
     regenerateMessages?(localesDir: string, out: string): unknown;
+    /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
+    regenerateEnv?(envFile: string, out: string): unknown;
 }
 export interface RegenResult {
     /** tables.d.ts 를 재생성했는가(domain/schema 존재 시에만). */
@@ -60,6 +70,8 @@ export interface RegenResult {
     readonly apps: readonly string[];
     /** messages.d.ts 를 재생성했는가(locales/ 존재 · 결정 158 · W2). */
     readonly messages: boolean;
+    /** env.d.ts 를 재생성했는가(프론트 앱 존재 · 결정 198 · F-9 ②). */
+    readonly env: boolean;
 }
 /**
  * 워처 없이 .gaon 타입 브리지를 1회 전체 재생성한다. `gaon check` 처럼

package/dist/dev.js

@@ -42,6 +42,13 @@ export async function startDev(deps) {
         await deps.regenerateMessages(layout.localesDir, layout.messagesOut);
         deps.log({ kind: 'regen', target: 'messages' });
     }
+    // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts(VITE_* 타입 브리지). `.env` 부재는
+    // regenerateEnv 가 throw(수리 안내) → dev 부팅 실패로 노출한다. `.env` 변경은 build-time
+    // 이라(Vite 가 서버 재시작으로 반영) 연속 워치는 두지 않는다 — 초기 1회 재생성으로 충분.
+    if (layout.hasFrontendApps && deps.regenerateEnv) {
+        await deps.regenerateEnv(layout.envFile, layout.envOut);
+        deps.log({ kind: 'regen', target: 'env' });
+    }
     // 2) 스키마 워치 → tables.d.ts 재생성.
     if (layout.schemaDir) {
         const schemaDir = layout.schemaDir;
@@ -105,7 +112,12 @@ export async function regenerateGaonOnce(layout, deps) {
     if (layout.localesDir && deps.regenerateMessages) {
         messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut)) === true;
     }
-    return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name), messages };
+    // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts. `.env` 부재는 throw(수리 안내).
+    let env = false;
+    if (layout.hasFrontendApps && deps.regenerateEnv) {
+        env = (await deps.regenerateEnv(layout.envFile, layout.envOut)) === true;
+    }
+    return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name), messages, env };
 }
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export function resolveDevLayout(cwd) {
@@ -113,11 +125,16 @@ export function resolveDevLayout(cwd) {
     const schemaDirPath = join(root, 'domain', 'schema');
     const appsDir = join(root, 'apps');
     const apps = [];
+    // env 축 적용 조건(결정 198) — 프론트 진입(index.html)을 가진 앱이 하나라도 있는가.
+    // API-only(index.html 없음)·스키마 전용 프로젝트는 클라 env 접근자를 안 쓰므로 제외한다.
+    let hasFrontendApps = false;
     if (existsSync(appsDir)) {
         for (const entry of readdirSync(appsDir, { withFileTypes: true })) {
             if (!entry.isDirectory())
                 continue;
             const appDir = join(appsDir, entry.name);
+            if (existsSync(join(appDir, 'index.html')))
+                hasFrontendApps = true;
             if (!existsSync(join(appDir, 'routes.ts')))
                 continue;
             apps.push({
@@ -134,6 +151,9 @@ export function resolveDevLayout(cwd) {
         apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
         localesDir: existsSync(localesDirPath) ? localesDirPath : undefined,
         messagesOut: join(root, '.gaon', 'messages.d.ts'),
+        hasFrontendApps,
+        envFile: join(root, '.env'),
+        envOut: join(root, '.gaon', 'env.d.ts'),
     };
 }
 // runDevCommand · DevCommandOptions 는 M9-C 에서 commands/dev.ts 로 이동.

package/dist/doctor/no-import-meta-env.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** 소스(.vue)에 import.meta.env 코드 사용이 있는지(단위 테스트 진입점 · 스크립트만·주석 제외). */
+export declare function usesImportMetaEnv(source: string): boolean;
+/** apps/·shared/ 의 .vue 를 훑어 import.meta.env 직접 사용을 error 로 낸다(결정 198). */
+export declare function checkNoImportMetaEnv(cwd: string): Promise<RuleReport>;