@gaonjs/cli 0.35.0 → 0.37.1

package/dist/commands/check.js

@@ -2,15 +2,15 @@
  * @gaonjs/cli · `gaon check` — 통합 검증 (M9-G · v0.15 §13.5)
  *
  * 배포 · CI · AI 에이전트가 한 번에 신뢰할 수 있는 검사 묶음. 사용자의
- * package.json 관례를 그대로 재사용한다 — `pnpm typecheck` · `pnpm vue-tsc`
- * · `pnpm build`. 스크립트가 없으면 폴백으로 로컬 바이너리를 직접 부른다
- * (`node_modules/.bin/tsc --noEmit` · `node_modules/.bin/vue-tsc --noEmit`
- * · `pnpm -r build` → `npm run build`).
+ * package.json 스크립트를 그대로 재사용하되, **프로젝트 선언 pm** 으로 돌린다
+ * (결정 170 · `<pm> run <name>` — pnpm/npm/yarn). 스크립트가 없으면 폴백으로
+ * 로컬 바이너리를 직접 부른다(`node_modules/.bin/tsc --noEmit` ·
+ * `node_modules/.bin/vue-tsc --noEmit`).
  *
  * The One Way — 하나의 명령이 4 검사를 순서대로 돌린다(결정 157 · doctor 기본 포함):
- *   1) typecheck (pnpm typecheck 또는 tsc --noEmit)
- *   2) vue-tsc   (pnpm vue-tsc 또는 vue-tsc --noEmit)
- *   3) build     (pnpm build)
+ *   1) typecheck (<pm> run typecheck 또는 tsc --noEmit)
+ *   2) vue-tsc   (<pm> run vue-tsc 또는 vue-tsc --noEmit)
+ *   3) build     (<pm> run build)
  *   4) doctor    (기본 포함 · 규칙 5 등 doctor 규칙 · --no-doctor 로 뺌 · 코어 재사용)
  *
  * 옵션 최소:
@@ -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>` 을
  * 정의해 두면 우선 사용한다.
@@ -77,8 +79,11 @@ async function runStep(step, cwd) {
     // 1) 사용자 스크립트가 정의돼 있으면 그걸 쓴다(한 곳에서 관리).
     const scriptName = step;
     if (hasScript(cwd, scriptName)) {
-        const cmd = 'pnpm';
-        const args = ['run', scriptName];
+        // 결정 170: pnpm 하드코딩 대신 프로젝트 선언 pm 으로 실행(npm/yarn 스캐폴드
+        // 대응 · pm 해상은 공유 `pm.ts` 단일 소스). build/typecheck/vue-tsc 는 잔여
+        // 인자가 없어 `<pm> run <name>` 만 — pnpm·npm·yarn(classic) 동일 동작.
+        const cmd = detectPackageManager(cwd);
+        const args = scriptRunArgs(cmd, scriptName);
         const { exitCode, output } = await runSubprocess(cwd, cmd, args);
         // 결정 146(12차 W2): build 가 성공했으면 **등록된 앱마다** dist/<앱>/index.html 과
         // 그 문서가 참조하는 에셋이 실제로 존재하는지 검증한다. build 스크립트가 통과해도
@@ -246,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.js

@@ -27,6 +27,7 @@ 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';
@@ -88,6 +89,7 @@ async function startGaonRegen(args) {
         regenerateTables: generateTablesDts,
         regenerateRoutes: generateRoutesDts,
         regenerateMessages: generateMessagesDts,
+        regenerateEnv: generateEnvDts,
         watch: watchDir,
         log: (e) => {
             if (e.kind === 'ready') {
@@ -101,7 +103,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 워처 종료');

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.d.ts

@@ -8,7 +8,13 @@ export interface NewCommandOptions {
     readonly skipInstall?: boolean;
     /** git init · 첫 커밋 스킵(테스트·기존 git 저장소에 삽입). */
     readonly skipGit?: boolean;
-    /** 패키지 매니저. 기본 pnpm(모노레포 관례 정합). */
+    /**
+     * 초기 `install` 을 돌릴 패키지 매니저(`--package-manager <pm>` · 별칭 `--pm`).
+     * 기본 pnpm(모노레포 관례 정합). blessed 툴체인(Dockerfile·pnpm-workspace)은
+     * The One Way 로 pnpm 을 유지하지만, package.json 의 `packageManager` 필드는
+     * 선택한 pm 에 맞춰 적는다 — 항상 pnpm 을 적으면 `--pm yarn` 시 yarn 1.22
+     * corepack enforcement 가 install 을 거부한다(결정 169 · 167 개정).
+     */
     readonly packageManager?: 'pnpm' | 'npm' | 'yarn';
     /**
      * (테스트 훅) 템플릿의 gaonjs 의존성 버전. 미지정 시 파사드(gaonjs)

package/dist/commands/new.js

@@ -22,7 +22,7 @@ import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readFileSync } from 'node:fs';
-import { renderProjectFiles } from '../templates/index.js';
+import { renderProjectFiles, PACKAGE_MANAGER_PINS, } from '../templates/index.js';
 import { writeUiKitScaffold } from '../uikit.js';
 import { regenerateProjectGaon } from './gen.js';
 /** 이름 유효성 — npm 패키지명 규칙(단순 부분)만 검사. */
@@ -172,7 +172,20 @@ export async function runNewCommand(name, opts = {}) {
     // 파일 생성 — 실패 시 부분 생성물이 남지 않도록 폴더를 정리하지는 않는다
     // (사용자가 원인 파악 후 rm -rf 로 지우도록). 정상 흐름에서는 문제 없음.
     const gaonjsVersion = opts.gaonjsVersion ?? detectGaonjsVersion();
-    const files = renderProjectFiles({ projectName: name, gaonjsVersion });
+    // 결정 169: packageManager 필드 = 선택한 pm 의 corepack 핀. 항상 pnpm 을
+    // 적던 옛 관례는 --pm yarn 시 yarn 1.22 corepack 이 install 을 거부시켰다.
+    const files = renderProjectFiles({
+        projectName: name,
+        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.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>;

package/dist/doctor/no-import-meta-env.js

@@ -0,0 +1,98 @@
+// @gaonjs/cli · doctor · `.vue` 의 import.meta.env 직접 사용 검출 (결정 198 · F-9 옵션 ② · error)
+//
+// `.vue`(SFC)에서 `import.meta.env.*` 를 직접 쓰면 vue-tsc 가 SFC 가상 모듈을 nodenext
+// CommonJS 출력으로 분류해 **TS1470**(`import.meta` 는 CommonJS 출력 파일에서 불가)로
+// 거부한다 — `gaon check` 가 red 지만 에러 문구가 원인·수리를 안 알려준다(F-9). 이 검사가
+// 그 지점을 먼저 잡아 수리 안내(`env` 접근자)를 준다. 값은 소스 텍스트 기반(주석 제외).
+//
+// 정답 경로(결정 198 · A/B): 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로
+// 읽는다 — `VITE_API_URL` → `env.API_URL`(접두 제거·타입드) · 내장은 `env.dev/prod/mode/
+// baseUrl`. `.env` 의 VITE_* 키가 `.gaon/env.d.ts` 로 물성화돼 없는 키는 컴파일 에러.
+// `.ts`(main.ts 의 import.meta.glob 등)는 ESM 출력이라 문제없어 검사 대상이 아니다 — .vue 만.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const blankKeepLines = (m) => m.replace(/[^\n]/g, ' ');
+// import.meta 는 `<script>` 에서만 유효하다(템플릿 보간·프로즈에는 못 쓴다). SFC 의 `<template>`
+// 텍스트가 "import.meta.env 미사용" 같은 프로즈로 언급하면 오탐이 되므로, 스캔 전 `<script>`
+// 블록 외 영역을 공백으로 지운다(줄바꿈 보존 → 라인 번호 유지). .ts 는 전체가 스크립트다.
+function scriptOnlyKeepLines(source, isVue) {
+    if (!isVue)
+        return source;
+    const kept = blankKeepLines(source); // 전체를 공백으로 시작 → script 블록만 복원.
+    const chars = kept.split('');
+    for (const m of source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)) {
+        const inner = m[1];
+        const start = (m.index ?? 0) + m[0].indexOf(inner);
+        for (let i = 0; i < inner.length; i++)
+            chars[start + i] = inner[i];
+    }
+    return chars.join('');
+}
+// 주석을 공백으로 치환하되 줄바꿈은 보존한다(라인 번호 유지) — "쓰지 말라" 설명 주석 오탐 방지.
+function stripCommentsKeepLines(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, blankKeepLines)
+        .replace(/<!--[\s\S]*?-->/g, blankKeepLines)
+        .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1 + ' '.repeat(_m.length - p1.length));
+}
+// import.meta.env 사용(공백 허용 · .env·[·글자 접근 모두). 문자열/식별자 오탐 최소화 위해
+// `import.meta` 뒤 `.env` 또는 `['env']`/`["env"]` 만 잡는다.
+const IMPORT_META_ENV = /import\s*\.\s*meta\s*(?:\.\s*env\b|\[\s*['"]env['"]\s*\])/;
+/** 소스(.vue)에 import.meta.env 코드 사용이 있는지(단위 테스트 진입점 · 스크립트만·주석 제외). */
+export function usesImportMetaEnv(source) {
+    return IMPORT_META_ENV.test(stripCommentsKeepLines(scriptOnlyKeepLines(source, true)));
+}
+/** apps/·shared/ 의 .vue 를 훑어 import.meta.env 직접 사용을 error 로 낸다(결정 198). */
+export async function checkNoImportMetaEnv(cwd) {
+    const issues = [];
+    for (const base of ['apps', 'shared']) {
+        for (const abs of await walkVue(join(cwd, base))) {
+            const source = await readFile(abs, 'utf8').catch(() => '');
+            const stripped = stripCommentsKeepLines(scriptOnlyKeepLines(source, true));
+            const rel = relative(cwd, abs);
+            for (const line of stripped.split('\n').map((l, i) => ({ l, i }))) {
+                if (!IMPORT_META_ENV.test(line.l))
+                    continue;
+                issues.push({
+                    rule: 'no-import-meta-env',
+                    level: 'error',
+                    file: rel,
+                    line: line.i + 1,
+                    message: `\`.vue\` 에서 import.meta.env 직접 사용: ${rel}:${line.i + 1}. SFC 는 nodenext 아래 ` +
+                        `CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부합니다(gaon check red · F-9).\n` +
+                        `→ 클라 공개 환경변수는 \`env\` 접근자로 읽으세요: \`import { env } from 'gaonjs/vue'\` 후 ` +
+                        `\`env.API_URL\`(= .env 의 VITE_API_URL · 접두 제거) · 내장은 \`env.dev/prod/mode/baseUrl\`. ` +
+                        `없는 키는 \`.gaon/env.d.ts\`(.env 스캔 생성)로 컴파일 타임에 잡힙니다(결정 198).`,
+                    detail: { file: rel, line: line.i + 1 },
+                });
+            }
+        }
+    }
+    return { rule: 'no-import-meta-env', issues };
+}
+/** dir 하위 .vue(node_modules·.gaon 제외) 절대경로. */
+async function walkVue(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-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';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-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';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -24,6 +24,15 @@ export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
+/**
+ * 실행할 검사 이름. 지정 없음(undefined) = 26개 모두.
+ */
+/**
+ * doctor 정적 검사 26종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
+ * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
+ */
+export declare const ALL_RULES: readonly DoctorRule[];
 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 확장)
  *
- * 25 검사를 조립한다:
+ * 26 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -27,6 +27,7 @@
  * 23) link-button-nesting (결정 113 · Link 로 Button 감싸기 = <a><button> 중첩 경고)
  * 24) seal-security (결정 121 · seal 클라 배선 · 보안 역전)
  * 25) schema-relations (§4.5 · 결정 134 · 커넥션 가로지르는 belongsTo·관계 · 대상 부재 error)
+ * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -64,6 +65,7 @@ import { checkAsyncOffload } from './doctor/async-offload.js';
 import { checkSealSecurity } from './doctor/seal-security.js';
 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 { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -92,9 +94,14 @@ export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-bu
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 23개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 26개 모두.
  */
-const ALL_RULES = [
+/**
+ * doctor 정적 검사 26종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
+ * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
+ */
+export const ALL_RULES = [
     'response-mixing',
     'n-plus-one',
     'dependency-direction',
@@ -120,6 +127,7 @@ const ALL_RULES = [
     'link-button-nesting',
     'seal-security',
     'schema-relations',
+    'no-import-meta-env',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -147,6 +155,7 @@ const CHECKERS = {
     'link-button-nesting': checkLinkButtonNesting,
     'seal-security': checkSealSecurity,
     'schema-relations': checkSchemaRelations,
+    'no-import-meta-env': checkNoImportMetaEnv,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/env-gen.d.ts

@@ -0,0 +1,12 @@
+/** `.env` 본문에서 `VITE_*` 키를 접두 제거해 뽑는다(중복 제거·정렬). */
+export declare function parseViteEnvKeys(content: string): string[];
+/** VITE_ 키 유니온을 gaonjs/vue augment d.ts 로 렌더한다. 값 타입은 Vite 관례상 string. */
+export declare function renderEnvDts(keys: readonly string[]): string;
+/** `.env` 가 없을 때의 수리 안내 오류 메시지(결정 198 · C). */
+export declare function missingEnvError(envFile: string): string;
+/**
+ * `.env` 에서 .gaon/env.d.ts 를 생성한다. `.env` 가 없으면 **throw**(결정 198 · C ·
+ * 프론트 앱 전제). 이 함수를 부르는 쪽(orchestrator)이 프론트 앱 유무로 호출을
+ * 게이트하므로, API-only·스키마 전용 프로젝트는 여기 도달하지 않는다. 생성했으면 true.
+ */
+export declare function generateEnvDts(envFile: string, out: string): boolean;

package/dist/env-gen.js

@@ -0,0 +1,63 @@
+// @gaonjs/cli · .gaon/env.d.ts 생성기 (결정 198 · F-9 옵션 ②)
+//
+// tables·routes·messages 에 이은 .gaon 파이프라인의 클라이언트 환경변수 축. `.env`
+// 의 `VITE_*` 키(Vite 표준 공개 접두)를 스캔해 `gaonjs/vue` 의 GaonClientEnv 를
+// augment 한다 — `.vue`·클라 `.ts` 에서 `env.<없는키>` 를 컴파일 타임에 잡는다.
+// 생성 파일은 타입만 담는다(규칙 3). 지정자는 파사드 서브패스 `gaonjs/vue`(결정 56·
+// 158 동형 · 사용자는 gaonjs 하나만 의존하므로 @gaonjs/vue 는 루트에서 미해석).
+//
+// 결정 198 · C(회원님): 타입 출처는 `.env`(.env.example 아님). 프론트 앱이 있는데
+// `.env` 가 없으면 gen/dev/build/check 가 **명확 오류**를 낸다 — `.env` 는 앱 실행
+// 전제라, 없으면 설정 부재를 조용히 넘기지 않고 노출한다(우회 X · §7.5.3).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const VITE_PREFIX = 'VITE_';
+// KEY=value 라인에서 키만 뽑는다(export 접두 · 앞 공백 허용). 값·따옴표는 안 본다.
+const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** `.env` 본문에서 `VITE_*` 키를 접두 제거해 뽑는다(중복 제거·정렬). */
+export function parseViteEnvKeys(content) {
+    const keys = new Set();
+    for (const line of content.split(/\r?\n/)) {
+        const m = ENV_LINE.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (key.startsWith(VITE_PREFIX) && key.length > VITE_PREFIX.length) {
+            keys.add(key.slice(VITE_PREFIX.length));
+        }
+    }
+    return [...keys].sort();
+}
+/** VITE_ 키 유니온을 gaonjs/vue augment d.ts 로 렌더한다. 값 타입은 Vite 관례상 string. */
+export function renderEnvDts(keys) {
+    const body = keys.length > 0
+        ? keys.map((k) => `    readonly ${k}: string`).join('\n')
+        : `    // (.env 에 VITE_* 공개 변수 없음 — 내장 필드 env.dev/mode/... 만 사용 가능)`;
+    return (`// 이 파일은 gaon 이 .env 의 VITE_* 키에서 생성한다 — 직접 수정하지 마세요.\n` +
+        `// 결정 198 · F-9 옵션 ②: 클라이언트 공개 환경변수 타입 브리지(gaonjs/vue env).\n` +
+        // gaonjs/vue 서브패스로 augment 해야 사용자 프로젝트에서 병합된다(결정 56·158 동형).
+        `declare module 'gaonjs/vue' {\n` +
+        `  interface GaonClientEnv {\n${body}\n  }\n` +
+        `}\n` +
+        `export {}\n`);
+}
+/** `.env` 가 없을 때의 수리 안내 오류 메시지(결정 198 · C). */
+export function missingEnvError(envFile) {
+    return (`클라이언트 환경변수 타입을 생성할 수 없습니다 — ${envFile} 가 없습니다.\n` +
+        `→ 프로젝트 루트에 .env 를 만드세요:  cp .env.example .env\n` +
+        `   (\`VITE_*\` 접두 변수만 클라 번들·env 접근자에 노출됩니다 · 그 외는 서버-only)`);
+}
+/**
+ * `.env` 에서 .gaon/env.d.ts 를 생성한다. `.env` 가 없으면 **throw**(결정 198 · C ·
+ * 프론트 앱 전제). 이 함수를 부르는 쪽(orchestrator)이 프론트 앱 유무로 호출을
+ * 게이트하므로, API-only·스키마 전용 프로젝트는 여기 도달하지 않는다. 생성했으면 true.
+ */
+export function generateEnvDts(envFile, out) {
+    if (!existsSync(envFile)) {
+        throw new Error(missingEnvError(envFile));
+    }
+    const keys = parseViteEnvKeys(readFileSync(envFile, 'utf8'));
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, renderEnvDts(keys), 'utf8');
+    return true;
+}

package/dist/index.d.ts

@@ -53,5 +53,22 @@ export interface RunOptions {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export declare function parseDoctorChecks(argv: readonly string[]): DoctorRule[] | undefined;
+/** `gaon new` argv 파싱 결과. name 부재·pm 오타를 호출부가 분기 처리한다. */
+export interface ParsedNewArgs {
+    /** 프로젝트 이름(첫 위치 인자). 부재 시 undefined. */
+    readonly name?: string;
+    /** 검증 통과한 패키지 매니저. 미지정 시 undefined(호출부가 pnpm 기본). */
+    readonly packageManager?: "pnpm" | "npm" | "yarn";
+    /** pm 값이 주어졌으나 pnpm·npm·yarn 이 아닐 때 그 원문(에러 안내용). */
+    readonly unknownPm?: string;
+}
+/**
+ * `gaon new <name>` 의 인자를 파싱한다.
+ * 패키지 매니저 플래그: `--package-manager <pm>`(정본) · `--pm <pm>`(별칭) ·
+ * 둘 다 `=` 형(`--package-manager=npm`)도 허용. 값을 취하는 플래그이므로
+ * 이름 위치 인자를 고를 때 그 값을 건너뛴다 — `gaon new --pm npm demo` 의
+ * npm 이 프로젝트 이름으로 오인되지 않도록(결정 167 · O-1 근본 fix).
+ */
+export declare function parseNewArgs(rest: readonly string[]): ParsedNewArgs;
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export declare function runCli(argv: readonly string[], opts?: RunOptions): void;