@gaonjs/cli 0.3.0 → 0.5.0

package/dist/dev/tsc.js

@@ -0,0 +1,127 @@
+/**
+ * @gaonjs/cli · dev/tsc — tsc / vue-tsc watch 스포너 (M9-C)
+ *
+ * `gaon dev` 는 백그라운드에서 두 개의 타입 검사기를 --watch 모드로 띄운다:
+ *   - tsc      : 프로젝트 전체 TS 소스 (packages/*, apps/*, domain/*)
+ *   - vue-tsc  : .vue 템플릿 포함 타입 검사
+ *
+ * 두 프로세스 모두 stdout/stderr 를 통합 콘솔로 파이프 — 타입 에러가 나는
+ * 순간 개발자가 즉시 알 수 있다. tsconfig.json 은 프로젝트 관례대로 cwd
+ * 의 것을 쓴다(없으면 스킵). SIGINT 시 두 자식을 확실히 종료한다.
+ *
+ * 무의존 원칙 — child_process.spawn 만 쓴다. node_modules/.bin 을 우선
+ * 탐색하고, 없으면 npx 로 폴백한다(사용자 환경 편차 방어).
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+/** node_modules/.bin/<name> 이 있으면 그 경로, 없으면 undefined. */
+function findLocalBin(cwd, name) {
+    const local = resolve(cwd, 'node_modules', '.bin', name);
+    if (existsSync(local))
+        return local;
+    // 모노레포 루트로 한 단계 위 탐색(사용자 프로젝트가 workspace 인 경우).
+    const parent = resolve(cwd, '..', '..', 'node_modules', '.bin', name);
+    if (existsSync(parent))
+        return parent;
+    return undefined;
+}
+/** tsc 또는 vue-tsc 를 --watch 로 띄운다. bin 을 못 찾으면 undefined. */
+function spawnWatcher(source, cwd, project, onLine) {
+    const bin = findLocalBin(cwd, source);
+    if (!bin)
+        return undefined;
+    // --noEmit 은 워치도 지원(파일만 검사). --pretty false 로 색상 코드를
+    // 우리 콘솔에 맡긴다(중복 색상 방지).
+    const args = ['--noEmit', '--watch', '--preserveWatchOutput', '--pretty', 'false', '-p', project];
+    const child = spawn(bin, args, {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, FORCE_COLOR: '0' },
+    });
+    const forward = (chunk, level) => {
+        if (!onLine)
+            return;
+        for (const line of chunk.toString('utf8').split('\n')) {
+            const t = line.trimEnd();
+            if (t.length === 0)
+                continue;
+            onLine(source, t, level);
+        }
+    };
+    child.stdout?.on('data', (b) => forward(b, 'info'));
+    child.stderr?.on('data', (b) => forward(b, 'error'));
+    return child;
+}
+/**
+ * tsc + vue-tsc 워처 두 개를 띄운다. project 파일이 없으면 스킵.
+ * 개별 워처를 끄는 옵션(no-tsc · no-vue-tsc)은 호출자가 결정한다.
+ */
+export function startTscWatchers(opts) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const project = opts.project ?? join(cwd, 'tsconfig.json');
+    const children = [];
+    if (!existsSync(project)) {
+        // 사용자 프로젝트가 아직 tsconfig 를 갖고 있지 않으면 조용히 스킵.
+        // (신규 프로젝트 초기 상태 방어 — 에러가 아니라 no-op.)
+        return { stop: async () => { }, children };
+    }
+    if (opts.enableTsc !== false) {
+        const c = spawnWatcher('tsc', cwd, project, opts.onLine);
+        if (c) {
+            children.push(c);
+            c.on('exit', (code) => opts.onExit?.('tsc', code));
+        }
+        else {
+            opts.onLine?.('tsc', `tsc 를 찾지 못했습니다 (node_modules/.bin/tsc). → pnpm install 후 다시 시도하세요.`, 'error');
+        }
+    }
+    if (opts.enableVueTsc !== false) {
+        const c = spawnWatcher('vue-tsc', cwd, project, opts.onLine);
+        if (c) {
+            children.push(c);
+            c.on('exit', (code) => opts.onExit?.('vue-tsc', code));
+        }
+        else {
+            // vue-tsc 는 프론트가 Vue 가 아니면 없을 수 있음 — 정보성 로그.
+            opts.onLine?.('vue-tsc', `vue-tsc 를 찾지 못했습니다 (node_modules/.bin/vue-tsc). Vue 프로젝트라면 pnpm install 로 설치하세요.`, 'info');
+        }
+    }
+    return {
+        children,
+        async stop() {
+            // SIGTERM → 2초 유예 → SIGKILL. tsc/vue-tsc 는 SIGTERM 에 잘 반응한다.
+            await Promise.all(children.map((c) => killChild(c, 2000)));
+        },
+    };
+}
+/** SIGTERM 후 timeoutMs 안에 안 죽으면 SIGKILL. */
+export function killChild(child, timeoutMs) {
+    return new Promise((resolvePromise) => {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            resolvePromise();
+            return;
+        }
+        const to = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* 이미 죽었으면 무시 */
+                }
+            }
+        }, timeoutMs);
+        child.once('exit', () => {
+            clearTimeout(to);
+            resolvePromise();
+        });
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            clearTimeout(to);
+            resolvePromise();
+        }
+    });
+}

package/dist/dev/watcher.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @gaonjs/cli · dev/watcher — 서버 재시작 트리거 워처 (M9-C)
+ *
+ * `gaon dev` 오케스트레이터는 서버 코드(apps/*, domain/*, gaon.config.ts,
+ * packages/*)의 변경을 감시해 서버 자식 프로세스를 재시작한다. 이 모듈은
+ * "무엇을 감시하고, 무엇을 무시할지"만 결정한다 — 재시작 정책은 호출자가
+ * 콜백에서 처리한다(관심사 분리).
+ *
+ * .gaon 파이프라인(tables.d.ts · routes.d.ts 재생성)은 별도(dev.ts 의
+ * startDev) 라 여기선 다루지 않는다. 그쪽 파일들은 이 워처의 무시 목록에
+ * 들어있어 재시작이 유발되지 않는다(무한 루프 방지).
+ *
+ * 무의존 — @gaonjs/data 의 watchDir 프리미티브(node:fs.watch 기반)를 재사용.
+ */
+export interface RestartWatcherOptions {
+    /** 프로젝트 루트(기본 process.cwd). */
+    readonly cwd?: string;
+    /**
+     * 변경이 감지되면 호출. changed 는 감시 루트 기준 상대경로 목록이다.
+     * 호출자가 여기서 서버 자식을 재시작한다.
+     */
+    readonly onRestart: (changed: string[]) => void | Promise<void>;
+    /** 에러 훅. 생략 시 무시(런타임을 죽이지 않기 위함). */
+    readonly onError?: (err: Error) => void;
+    /** debounce(ms). 저장 폭풍을 한 배치로 묶기 위해. 기본 200ms. */
+    readonly debounceMs?: number;
+}
+export interface RestartWatcherHandle {
+    /** 감시 목록(진단 · 테스트용). */
+    readonly roots: readonly string[];
+    close(): void;
+}
+/**
+ * 재시작을 유발하는 변경인가.
+ *   - 확장자가 RESTART_EXTS 중 하나
+ *   - 경로 조각에 IGNORE_SEGMENTS 가 없음
+ *   - .test.ts / .spec.ts 는 서버 실행에 영향 없으니 무시
+ *   - .d.ts 는 생성물이므로 무시(스캐폴드/재생성이 만듦)
+ */
+export declare function isRestartChange(rel: string): boolean;
+/**
+ * 감시할 루트 후보를 프로젝트 관례로 해석한다. 존재하는 것만 담아 반환.
+ */
+export declare function resolveWatchRoots(cwd: string): string[];
+/**
+ * 서버 재시작 워처를 띄운다. 각 루트에 대해 recursive watcher 를 하나씩
+ * 걸고, 필터로 재시작 파일만 통과시킨다. 파일 하나(gaon.config.ts)를 감시할
+ * 때도 watchDir 은 부모 디렉터리를 잡고 filter 로 걸러낸다.
+ */
+export declare function startRestartWatcher(opts: RestartWatcherOptions): RestartWatcherHandle;

package/dist/dev/watcher.js

@@ -0,0 +1,95 @@
+/**
+ * @gaonjs/cli · dev/watcher — 서버 재시작 트리거 워처 (M9-C)
+ *
+ * `gaon dev` 오케스트레이터는 서버 코드(apps/*, domain/*, gaon.config.ts,
+ * packages/*)의 변경을 감시해 서버 자식 프로세스를 재시작한다. 이 모듈은
+ * "무엇을 감시하고, 무엇을 무시할지"만 결정한다 — 재시작 정책은 호출자가
+ * 콜백에서 처리한다(관심사 분리).
+ *
+ * .gaon 파이프라인(tables.d.ts · routes.d.ts 재생성)은 별도(dev.ts 의
+ * startDev) 라 여기선 다루지 않는다. 그쪽 파일들은 이 워처의 무시 목록에
+ * 들어있어 재시작이 유발되지 않는다(무한 루프 방지).
+ *
+ * 무의존 — @gaonjs/data 의 watchDir 프리미티브(node:fs.watch 기반)를 재사용.
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { watchDir } from '@gaonjs/data';
+// 재시작을 유발하는 확장자. 다른 것(이미지 · 마크다운 등)은 무시.
+const RESTART_EXTS = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs', '.json', '.vue'];
+// 재시작을 유발하지 않는 경로 조각(생성물 · 캐시 · 테스트 산출물).
+const IGNORE_SEGMENTS = ['.gaon', 'node_modules', 'dist', '.git', 'coverage', '.turbo'];
+/**
+ * 재시작을 유발하는 변경인가.
+ *   - 확장자가 RESTART_EXTS 중 하나
+ *   - 경로 조각에 IGNORE_SEGMENTS 가 없음
+ *   - .test.ts / .spec.ts 는 서버 실행에 영향 없으니 무시
+ *   - .d.ts 는 생성물이므로 무시(스캐폴드/재생성이 만듦)
+ */
+export function isRestartChange(rel) {
+    if (!rel)
+        return false;
+    const norm = rel.replace(/\\/g, '/');
+    for (const seg of IGNORE_SEGMENTS) {
+        if (norm.startsWith(`${seg}/`) || norm.includes(`/${seg}/`) || norm === seg)
+            return false;
+    }
+    if (norm.endsWith('.d.ts'))
+        return false;
+    if (/\.(test|spec)\.[cm]?[tj]sx?$/.test(norm))
+        return false;
+    return RESTART_EXTS.some((ext) => norm.endsWith(ext));
+}
+/**
+ * 감시할 루트 후보를 프로젝트 관례로 해석한다. 존재하는 것만 담아 반환.
+ */
+export function resolveWatchRoots(cwd) {
+    const root = resolve(cwd);
+    const candidates = [
+        join(root, 'apps'),
+        join(root, 'domain'),
+        join(root, 'shared'),
+        join(root, 'packages'),
+        join(root, 'gaon.config.ts'),
+        join(root, 'gaon.config.js'),
+    ];
+    return candidates.filter((p) => existsSync(p));
+}
+/**
+ * 서버 재시작 워처를 띄운다. 각 루트에 대해 recursive watcher 를 하나씩
+ * 걸고, 필터로 재시작 파일만 통과시킨다. 파일 하나(gaon.config.ts)를 감시할
+ * 때도 watchDir 은 부모 디렉터리를 잡고 filter 로 걸러낸다.
+ */
+export function startRestartWatcher(opts) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const debounceMs = opts.debounceMs ?? 200;
+    const onError = opts.onError ?? (() => { });
+    const roots = resolveWatchRoots(cwd);
+    const handles = [];
+    // 디렉터리 vs 단일 파일 구분 — 파일이면 부모 디렉터리를 감시하고
+    // filter 에서 정확 매칭한다.
+    for (const rootPath of roots) {
+        const isFile = rootPath.endsWith('.ts') || rootPath.endsWith('.js');
+        const watchTarget = isFile ? resolve(rootPath, '..') : rootPath;
+        const fileBaseName = isFile ? rootPath.slice(watchTarget.length + 1) : undefined;
+        handles.push(watchDir(watchTarget, {
+            debounceMs,
+            filter: (rel) => {
+                if (fileBaseName)
+                    return rel === fileBaseName;
+                return isRestartChange(rel);
+            },
+            onChange: async (changed) => {
+                await opts.onRestart(changed);
+            },
+            onError,
+        }));
+    }
+    return {
+        roots,
+        close() {
+            for (const h of handles)
+                h.close();
+        },
+    };
+}

package/dist/dev.d.ts

@@ -1,4 +1,4 @@
-import { type WatchHandle, type WatchOptions } from '@gaonjs/data';
+import type { WatchHandle, WatchOptions } from '@gaonjs/data';
 export interface DevApp {
     readonly name: string;
     readonly appDir: string;
@@ -42,18 +42,3 @@ export interface DevHandle {
 export declare function startDev(deps: DevDeps): Promise<DevHandle>;
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export declare function resolveDevLayout(cwd: string): DevLayout;
-export interface DevCommandOptions {
-    readonly cwd?: string;
-    readonly json?: boolean;
-    /** 프로세스 시그널 등록·해제(테스트에서 주입 가능). 기본 process. */
-    readonly signals?: {
-        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
-        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
-    };
-}
-/**
- * `gaon dev` 진입점. cwd 관례로 레이아웃을 엮고 워치 루프를 띄운 뒤
- * SIGINT/SIGTERM 에 graceful stop. 프로세스는 워처가 살아 있는 동안
- * 유지된다(활성 핸들). 반환 프라미스는 종료 시 resolve.
- */
-export declare function runDevCommand(opts?: DevCommandOptions): Promise<void>;

package/dist/dev.js

@@ -1,19 +1,18 @@
 /**
- * @gaonjs/cli · `gaon dev` — .gaon 갱신 파이프라인 (M3)
+ * @gaonjs/cli · dev — .gaon 갱신 파이프라인 (M3 · v0.15 §6.3)
  *
  * 파일 워처(@gaonjs/data watchDir) → 재생성(tables.d.ts·routes.d.ts) →
- * 디스크 mtime 갱신 → 편집기 tsserver 자동 반영(§6.3, 열린 질문 3).
+ * 디스크 mtime 갱신 → 편집기 tsserver 자동 반영. 오케스트레이션은
+ * 주입(deps)으로 순수하게 유지하고(테스트 용이 · dbCli 패턴 동일),
+ * 상위(gaon dev 오케스트레이터 · commands/dev.ts)가 이 startDev 를 재사용한다.
  *
- * 오케스트레이션은 주입(deps)으로 순수하게 유지하고(테스트 용이·dbCli
- * 패턴과 동일), CLI 진입점이 cwd 관례로 실제 경로·재생성기를 엮는다.
- * 실제 웹 서버·Vite·Docker 인프라 기동은 후속 마일스톤이다 — M3 는
- * 타입 브리지 갱신 루프만 담당한다.
+ * M9-C 이전에는 이 파일이 gaon dev 진입점(runDevCommand)도 겸했으나,
+ * M9-C 에서 인프라·서버·타입 검사기를 통합하는 새 진입점이 commands/dev.ts
+ * 로 이동했다. 이 파일은 .gaon 재생성 코어(startDev · resolveDevLayout) 만
+ * 유지한다.
  */
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { generateTablesDts, watchDir } from '@gaonjs/data';
-import { generateRoutesDts } from '@gaonjs/web';
-import { registerTsResolve } from './tsResolve.js';
 const isSchemaChange = (f) => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts') && !f.includes('.gaon');
 const isRoutesChange = (f) => !f.includes('.gaon') &&
     f.endsWith('.ts') &&
@@ -94,60 +93,5 @@ export function resolveDevLayout(cwd) {
         apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
     };
 }
-/** 사람이 읽는 이벤트 텍스트. */
-function humanEvent(e) {
-    switch (e.kind) {
-        case 'ready': {
-            const parts = [];
-            if (e.schema)
-                parts.push('schema→tables.d.ts');
-            for (const a of e.apps)
-                parts.push(`${a}→routes.d.ts`);
-            const what = parts.length ? parts.join(', ') : '(감시 대상 없음 — domain/schema·apps/* 확인)';
-            return `  gaon dev · 워치 시작 — ${what}\n  파일을 저장하면 .gaon 이 재생성되고 편집기가 자동 반영합니다. (Ctrl+C 종료)`;
-        }
-        case 'regen':
-            return e.target === 'tables'
-                ? '  ↻ tables.d.ts 재생성'
-                : `  ↻ ${e.app}/.gaon/routes.d.ts 재생성`;
-        case 'stopped':
-            return '  gaon dev · 종료';
-    }
-}
-/**
- * `gaon dev` 진입점. cwd 관례로 레이아웃을 엮고 워치 루프를 띄운 뒤
- * SIGINT/SIGTERM 에 graceful stop. 프로세스는 워처가 살아 있는 동안
- * 유지된다(활성 핸들). 반환 프라미스는 종료 시 resolve.
- */
-export async function runDevCommand(opts = {}) {
-    const cwd = opts.cwd ?? process.cwd();
-    const json = opts.json ?? false;
-    const signals = opts.signals ?? process;
-    registerTsResolve(); // 사용자 .ts 의 `.js` 상대 import 를 런타임에 해석
-    const layout = resolveDevLayout(cwd);
-    const emit = (e) => {
-        if (json)
-            process.stdout.write(JSON.stringify(e) + '\n');
-        else
-            process.stdout.write(humanEvent(e) + '\n');
-    };
-    const deps = {
-        layout,
-        regenerateTables: generateTablesDts,
-        regenerateRoutes: generateRoutesDts,
-        watch: watchDir,
-        log: emit,
-        onError: (err) => process.stderr.write(`  ✗ ${err.message}\n`),
-    };
-    const handle = await startDev(deps);
-    await new Promise((resolvePromise) => {
-        const stop = () => {
-            signals.off('SIGINT', stop);
-            signals.off('SIGTERM', stop);
-            handle.close();
-            resolvePromise();
-        };
-        signals.on('SIGINT', stop);
-        signals.on('SIGTERM', stop);
-    });
-}
+// runDevCommand · DevCommandOptions 는 M9-C 에서 commands/dev.ts 로 이동.
+// 이 파일은 .gaon 재생성 코어(startDev · resolveDevLayout)만 유지한다.

package/dist/doctor/no-auto-import.d.ts

@@ -0,0 +1,10 @@
+import type { DoctorCheck, RuleReport } from './types.js';
+/**
+ * config 파일 하나의 소스에서 자동 import 플러그인 import 를 잡는다
+ * (단위 테스트 진입점).
+ */
+export declare function inspectConfigForAutoImport(file: string, source: string, cwd: string): DoctorCheck[];
+/** package.json 안의 deps 4종을 훑어 자동 import 플러그인 유무를 낸다. */
+export declare function inspectPackageJson(file: string, source: string, cwd: string): DoctorCheck[];
+/** 프로젝트 루트를 훑어 자동 import 설정·의존을 잡는다. */
+export declare function checkNoAutoImport(cwd: string): Promise<RuleReport>;

package/dist/doctor/no-auto-import.js

@@ -0,0 +1,158 @@
+// @gaonjs/cli · doctor · 자동 import 감지 (M9-E 확장 · errata E-5 §2.4)
+//
+// Nuxt 식 자동 import(컴포넌트·컴포저블을 import 문 없이 사용)는 넣지
+// 않는다. 출처가 코드에 보이지 않는 마법은 AI 가 "이 심볼이 어디서
+// 왔는지"를 추측하게 만들어 v0.15 §1.2 (관례로 추측을 없앤다) 와 정면
+// 충돌한다. 모든 컴포넌트·컴포저블은 명시적으로 import 한다.
+//
+// 검사 대상 (E-5 §2.4 · v0.15 §1.2):
+//  1) 프로젝트 루트의 대표 config 파일 안의 import 선언에서
+//     'unplugin-auto-import' · 'unplugin-vue-components' · 'unimport'
+//     발견 시 error.
+//  2) package.json 의 dependencies · devDependencies · peerDependencies
+//     · optionalDependencies 에 위 3종이 있으면 error.
+//
+// 방법: config 는 TS AST 로 import 선언만 훑고 · package.json 은 JSON
+// 파싱 + 라인 검색(에러 메시지에 라인을 붙이기 위해 원문에서 재검색).
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+/** 금지 플러그인 목록 — 자동 import 를 도입하는 대표 3종. */
+const FORBIDDEN_PLUGINS = [
+    'unplugin-auto-import',
+    'unplugin-vue-components',
+    'unimport',
+];
+/**
+ * 검사할 config 파일. Vite/Nuxt/Vue-CLI 관례 파일명을 모두 훑는다.
+ * 존재하지 않는 파일은 스킵.
+ */
+const CONFIG_FILES = [
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'nuxt.config.ts',
+    'nuxt.config.js',
+    'vue.config.js',
+    'vue.config.ts',
+];
+/**
+ * config 파일 하나의 소스에서 자동 import 플러그인 import 를 잡는다
+ * (단위 테스트 진입점).
+ */
+export function inspectConfigForAutoImport(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const spec = node.moduleSpecifier.text;
+            const plugin = matchForbidden(spec);
+            if (plugin) {
+                const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                issues.push({
+                    rule: 'no-auto-import',
+                    level: 'error',
+                    file: rel,
+                    line: line + 1,
+                    message: `${rel} (line ${line + 1})\n` +
+                        `  '${plugin}' 발견 · v0.15 §1.2 (관례로 추측 없앤다) 정합 X\n` +
+                        `→ 자동 import 플러그인 제거 · 명시 import 사용`,
+                    detail: { plugin, source: 'config-import', module: spec },
+                });
+            }
+        }
+        // require('unplugin-...') 형태(CJS config)도 잡는다.
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'require') {
+            const arg = node.arguments[0];
+            if (arg && ts.isStringLiteral(arg)) {
+                const plugin = matchForbidden(arg.text);
+                if (plugin) {
+                    const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                    issues.push({
+                        rule: 'no-auto-import',
+                        level: 'error',
+                        file: rel,
+                        line: line + 1,
+                        message: `${rel} (line ${line + 1})\n` +
+                            `  '${plugin}' 발견 · v0.15 §1.2 (관례로 추측 없앤다) 정합 X\n` +
+                            `→ 자동 import 플러그인 제거 · 명시 import 사용`,
+                        detail: { plugin, source: 'config-require', module: arg.text },
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return issues;
+}
+/** 지정한 모듈 이름이 금지 목록에 걸리면 해당 플러그인 이름을 낸다. */
+function matchForbidden(spec) {
+    return FORBIDDEN_PLUGINS.find((p) => spec === p || spec.startsWith(p + '/'));
+}
+/** package.json 안의 deps 4종을 훑어 자동 import 플러그인 유무를 낸다. */
+export function inspectPackageJson(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    let pkg;
+    try {
+        pkg = JSON.parse(source);
+    }
+    catch {
+        // JSON 파싱 실패 시 이 규칙은 아무 것도 하지 않는다 — 다른 규칙 도구가
+        // 잡을 문제(예: gaon check 의 tsconfig 파싱)이지 자동 import 검사의 몫이 아님.
+        return [];
+    }
+    const allDeps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+        ...(pkg.peerDependencies ?? {}),
+        ...(pkg.optionalDependencies ?? {}),
+    };
+    for (const plugin of FORBIDDEN_PLUGINS) {
+        if (!(plugin in allDeps))
+            continue;
+        const line = findLineForKey(source, plugin);
+        const loc = line ? ` (line ${line})` : '';
+        issues.push({
+            rule: 'no-auto-import',
+            level: 'error',
+            file: rel,
+            line: line,
+            message: `${rel}${loc}\n` +
+                `  package.json 에 '${plugin}' 발견 · v0.15 §1.2 (관례로 추측 없앤다) 정합 X\n` +
+                `→ 자동 import 플러그인 제거 · 명시 import 사용 · 'pnpm remove ${plugin}' 후 vite/nuxt config 도 정리`,
+            detail: { plugin, source: 'package-json' },
+        });
+    }
+    return issues;
+}
+/** package.json 원문에서 `"<key>"` 가 처음 나오는 1-기반 라인 번호. */
+function findLineForKey(source, key) {
+    const lines = source.split(/\r?\n/);
+    const needle = `"${key}"`;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(needle))
+            return i + 1;
+    }
+    return undefined;
+}
+/** 프로젝트 루트를 훑어 자동 import 설정·의존을 잡는다. */
+export async function checkNoAutoImport(cwd) {
+    const issues = [];
+    for (const cfg of CONFIG_FILES) {
+        const full = join(cwd, cfg);
+        if (!existsSync(full))
+            continue;
+        const src = await readFile(full, 'utf8');
+        issues.push(...inspectConfigForAutoImport(full, src, cwd));
+    }
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        const src = await readFile(pkgPath, 'utf8');
+        issues.push(...inspectPackageJson(pkgPath, src, cwd));
+    }
+    return { rule: 'no-auto-import', issues };
+}

package/dist/doctor/reporter.d.ts

@@ -1,5 +1,5 @@
 import type { DoctorResult } from './types.js';
-/** JSON 출력 문자열(끝 개행 없음). */
+/** JSON 출력 문자열(끝 개행 없음). fatal 이 있으면 그대로 포함된다. */
 export declare function renderJson(result: DoctorResult): string;
 /** 사람이 읽는 요약(끝 개행 없음). */
 export declare function renderHuman(result: DoctorResult): string;

package/dist/doctor/reporter.js

@@ -1,13 +1,26 @@
-// @gaonjs/cli · doctor · 출력 포맷 (human / JSON) — M9-E
+// @gaonjs/cli · doctor · 출력 포맷 (human / JSON) — M9-E · M9-E-Fix
 //
 // human: 사람이 읽는 요약 + 규칙별 이슈 목록.
-// JSON: 자동화(CI)용 · {passed, warnings, errors} 그대로 직렬화 · 파싱 안정.
-/** JSON 출력 문자열(끝 개행 없음). */
+// JSON: 자동화(CI)용 · {passed, warnings, errors, fatal?} 그대로 직렬화
+// · 파싱 안정.
+//
+// fatal 이 있으면 규칙 실행 자체가 불가능한 상황 — 크래시 대신 우아한
+// 안내(§7.5.3 · 에러 = 수리 안내서)를 출력한다.
+/** JSON 출력 문자열(끝 개행 없음). fatal 이 있으면 그대로 포함된다. */
 export function renderJson(result) {
     return JSON.stringify(result);
 }
 /** 사람이 읽는 요약(끝 개행 없음). */
 export function renderHuman(result) {
+    if (result.fatal) {
+        const lines = [];
+        lines.push(`  ✗ gaon doctor · 시작 불가 (${result.fatal.code})`);
+        for (const ln of result.fatal.message.split('\n')) {
+            lines.push(`    ${ln}`);
+        }
+        lines.push(`    ${result.fatal.hint}`);
+        return lines.join('\n');
+    }
     const lines = [];
     const passN = result.passed.length;
     const warnN = result.warnings.length;

package/dist/doctor/setup.d.ts

@@ -0,0 +1,26 @@
+import type { DoctorFatal } from './types.js';
+export type { DoctorFatal, DoctorFatalCode } from './types.js';
+/**
+ * 프로젝트 마커 4종: gaon.config.ts · domain/ · apps/ · shared/.
+ * 하나라도 있으면 gaon 프로젝트로 인정한다. 모두 없으면 검사할 대상이
+ * 없으므로 우아한 안내 후 종료한다.
+ */
+export declare function detectProject(cwd: string): boolean;
+/**
+ * typescript 모듈이 doctor 가 필요로 하는 compiler API 를 노출하는지
+ * 검사한다. 예: 사용자 프로젝트가 typescript@7 을 받아 오면 default
+ * export 가 `{ version, versionMajorMinor }` 스텁만 담아
+ * `ts.ScriptTarget` 이 undefined → `ts.createSourceFile` 호출 시 크래시.
+ *
+ * 인자 tsMod 는 테스트에서 스텁을 주입하기 위해 기본값을 실 ts 로 둔다.
+ */
+export declare function checkTypeScriptApi(tsMod?: {
+    readonly ScriptTarget?: {
+        readonly ES2022?: number;
+    };
+    readonly createSourceFile?: unknown;
+}): boolean;
+/** 프로젝트 마커 없음 · 우아한 안내. */
+export declare function fatalNoProject(cwd: string): DoctorFatal;
+/** typescript compiler API 미노출 · 우아한 안내. */
+export declare function fatalTsApiMissing(installedVersion: string | undefined): DoctorFatal;