@gaonjs/cli 0.3.0 → 0.4.0

package/dist/dev/docker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @gaonjs/cli · dev/docker — Docker Compose 자동 오케스트레이션 (M9-C)
+ *
+ * `gaon dev` 는 개발 인프라(pg · redis · nats · mailpit · minio)를 실 컨테이너
+ * 로 띄운다 — CLAUDE.md §9(실 인프라 필수 · 목업 금지) 정합. 이미 떠 있으면
+ * 재사용하고, 죽었으면 up -d 한다. Ctrl+C 로 종료해도 컨테이너는 유지되어
+ * 다음 실행을 빨리 시작할 수 있다(--stop-docker 옵션 시만 down).
+ *
+ * fail-closed: Docker 가 없거나 compose.yaml 을 못 찾으면 명확한 수리
+ * 안내(§7.5.3 — 에러 = 다음 명령서)를 던진다.
+ */
+export interface DockerLocateOptions {
+    /** 프로젝트 루트(기본 process.cwd). */
+    readonly cwd?: string;
+}
+/** Docker Compose 파일을 찾는 관례 — 프로젝트 루트 → packages/data 순. */
+export declare function findComposeFile(opts?: DockerLocateOptions): string | undefined;
+/** `docker` 바이너리가 PATH 에 있는지. */
+export declare function isDockerAvailable(): Promise<boolean>;
+/** compose 서비스 상태 요약(존재 · 실행 개수). */
+export interface ComposeStatus {
+    /** 정의된 서비스 개수(compose config --services). */
+    readonly definedCount: number;
+    /** 이미 running 상태인 서비스 개수. */
+    readonly runningCount: number;
+    /** 이미 필요한 만큼 다 떠 있어 up 이 불필요한가. */
+    readonly allRunning: boolean;
+}
+/**
+ * `docker compose ps --status running --format json` 로 실행 중 서비스를
+ * 세고, `docker compose config --services` 로 정의된 서비스와 비교한다.
+ */
+export declare function inspectCompose(composeFile: string): Promise<ComposeStatus>;
+export interface ComposeUpOptions {
+    /** 진행 로그 훅(자식 stdout/stderr 를 그대로 스트림). */
+    readonly onLine?: (line: string, level: 'info' | 'error') => void;
+}
+/** `docker compose up -d` — 이미 running 이면 no-op 에 가깝다. */
+export declare function composeUp(composeFile: string, opts?: ComposeUpOptions): Promise<void>;
+/** `docker compose down` — --stop-docker 옵션 시만 부른다. */
+export declare function composeDown(composeFile: string, opts?: ComposeUpOptions): Promise<void>;
+/**
+ * `gaon dev` 진입점에서 부를 상위 오케스트레이터: compose 파일 감지 →
+ * Docker 가용 확인 → 상태 조회 → 필요 시 up. 반환값으로 후속 종료
+ * 로직(down 여부)에 필요한 정보를 넘긴다.
+ */
+export interface EnsureInfraResult {
+    readonly composeFile: string;
+    readonly startedNow: boolean;
+    readonly status: ComposeStatus;
+}
+export declare function ensureInfra(opts?: DockerLocateOptions & ComposeUpOptions): Promise<EnsureInfraResult | undefined>;

package/dist/dev/docker.js

@@ -0,0 +1,163 @@
+/**
+ * @gaonjs/cli · dev/docker — Docker Compose 자동 오케스트레이션 (M9-C)
+ *
+ * `gaon dev` 는 개발 인프라(pg · redis · nats · mailpit · minio)를 실 컨테이너
+ * 로 띄운다 — CLAUDE.md §9(실 인프라 필수 · 목업 금지) 정합. 이미 떠 있으면
+ * 재사용하고, 죽었으면 up -d 한다. Ctrl+C 로 종료해도 컨테이너는 유지되어
+ * 다음 실행을 빨리 시작할 수 있다(--stop-docker 옵션 시만 down).
+ *
+ * fail-closed: Docker 가 없거나 compose.yaml 을 못 찾으면 명확한 수리
+ * 안내(§7.5.3 — 에러 = 다음 명령서)를 던진다.
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+/** Docker Compose 파일을 찾는 관례 — 프로젝트 루트 → packages/data 순. */
+export function findComposeFile(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const candidates = [
+        join(cwd, 'compose.yaml'),
+        join(cwd, 'compose.yml'),
+        join(cwd, 'docker-compose.yaml'),
+        join(cwd, 'docker-compose.yml'),
+        // 모노레포 관례(현 저장소) — 사용자 프로젝트에는 없을 수 있으니
+        // 있으면만 채택한다.
+        join(cwd, 'packages', 'data', 'compose.yaml'),
+    ];
+    for (const p of candidates)
+        if (existsSync(p))
+            return p;
+    return undefined;
+}
+/** `docker` 바이너리가 PATH 에 있는지. */
+export async function isDockerAvailable() {
+    return runOnce('docker', ['--version']).then((r) => r.exitCode === 0, () => false);
+}
+/**
+ * `docker compose ps --status running --format json` 로 실행 중 서비스를
+ * 세고, `docker compose config --services` 로 정의된 서비스와 비교한다.
+ */
+export async function inspectCompose(composeFile) {
+    const defined = await runOnce('docker', ['compose', '-f', composeFile, 'config', '--services']);
+    if (defined.exitCode !== 0) {
+        throw new Error(`Docker Compose 정의를 읽지 못했습니다 (${composeFile}).\n` +
+            `→ 이 파일이 유효한 compose 형식인지 확인하세요.\n` +
+            `→ 수동 확인: docker compose -f ${composeFile} config --services\n` +
+            (defined.stderr ? `stderr: ${defined.stderr.trim()}` : ''));
+    }
+    const definedList = defined.stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    // ps --format json 은 라인 당 JSON — 서비스가 없으면 빈 출력.
+    const ps = await runOnce('docker', [
+        'compose',
+        '-f',
+        composeFile,
+        'ps',
+        '--status',
+        'running',
+        '--format',
+        'json',
+    ]);
+    const runningNames = new Set();
+    if (ps.exitCode === 0) {
+        for (const line of ps.stdout.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                const rec = JSON.parse(t);
+                if (rec.Service)
+                    runningNames.add(rec.Service);
+            }
+            catch {
+                // ps 가 배열 형태로 오는 이전 버전 호환.
+                try {
+                    const arr = JSON.parse(t);
+                    for (const r of arr)
+                        if (r.Service)
+                            runningNames.add(r.Service);
+                }
+                catch {
+                    // 파싱 실패한 줄은 무시(포맷 편차 방어).
+                }
+            }
+        }
+    }
+    const running = definedList.filter((n) => runningNames.has(n)).length;
+    return {
+        definedCount: definedList.length,
+        runningCount: running,
+        allRunning: definedList.length > 0 && running === definedList.length,
+    };
+}
+/** `docker compose up -d` — 이미 running 이면 no-op 에 가깝다. */
+export async function composeUp(composeFile, opts = {}) {
+    const res = await runStreamed('docker', ['compose', '-f', composeFile, 'up', '-d'], opts.onLine);
+    if (res.exitCode !== 0) {
+        throw new Error(`Docker Compose up 이 실패했습니다 (${composeFile}, exit ${res.exitCode}).\n` +
+            `→ 로그를 확인하세요: docker compose -f ${composeFile} logs\n` +
+            `→ 포트 충돌이면 compose.yaml 의 포트를 조정하거나 기존 컨테이너를 정리하세요.`);
+    }
+}
+/** `docker compose down` — --stop-docker 옵션 시만 부른다. */
+export async function composeDown(composeFile, opts = {}) {
+    const res = await runStreamed('docker', ['compose', '-f', composeFile, 'down'], opts.onLine);
+    if (res.exitCode !== 0) {
+        throw new Error(`Docker Compose down 이 실패했습니다 (${composeFile}, exit ${res.exitCode}).\n` +
+            `→ 수동 정리: docker compose -f ${composeFile} down`);
+    }
+}
+export async function ensureInfra(opts = {}) {
+    const composeFile = findComposeFile({ cwd: opts.cwd });
+    if (!composeFile) {
+        // compose 파일이 없는 프로젝트는 인프라 오케스트레이션 스킵.
+        // (사용자 프로젝트가 아직 인프라를 정의하지 않은 초기 상태 가능.)
+        return undefined;
+    }
+    const hasDocker = await isDockerAvailable();
+    if (!hasDocker) {
+        throw new Error(`Docker 를 찾을 수 없습니다.\n` +
+            `compose 파일이 있지만 (${composeFile}) docker 바이너리가 PATH 에 없습니다.\n` +
+            `→ Docker Desktop 을 설치하고 실행하세요: https://www.docker.com/products/docker-desktop/\n` +
+            `→ 이미 설치되어 있다면 실행 중인지 확인하세요 (docker ps).\n` +
+            `→ 인프라 없이 진행하려면 compose.yaml 을 이동/제거하세요 — gaon dev 는 감지 시 자동 기동합니다.`);
+    }
+    const status = await inspectCompose(composeFile);
+    if (status.allRunning) {
+        return { composeFile, startedNow: false, status };
+    }
+    await composeUp(composeFile, { onLine: opts.onLine });
+    return { composeFile, startedNow: true, status: await inspectCompose(composeFile) };
+}
+/** 한 번 실행하고 결과를 모아 반환(단순 조회용). */
+function runOnce(cmd, args) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (b) => out.push(b.toString('utf8')));
+        child.stderr.on('data', (b) => err.push(b.toString('utf8')));
+        child.on('error', rejectPromise);
+        child.on('close', (code) => resolvePromise({ exitCode: code ?? -1, stdout: out.join(''), stderr: err.join('') }));
+    });
+}
+/** 실행하며 라인 단위로 스트림(진행 로그를 콘솔로 흘리기 위함). */
+function runStreamed(cmd, args, onLine) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const emit = (chunk, level) => {
+            if (!onLine)
+                return;
+            for (const line of chunk.toString('utf8').split('\n')) {
+                if (line.trim().length > 0)
+                    onLine(line, level);
+            }
+        };
+        child.stdout.on('data', (b) => emit(b, 'info'));
+        child.stderr.on('data', (b) => emit(b, 'error'));
+        child.on('error', rejectPromise);
+        child.on('close', (code) => resolvePromise({ exitCode: code ?? -1 }));
+    });
+}

package/dist/dev/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @gaonjs/cli · dev — `gaon dev` 서브모듈 public export (M9-C)
+ *
+ * 상위 index.ts 는 이 모듈만 재수출한다 — 오케스트레이터 진입점은
+ * commands/dev.ts 의 runDevCommand.
+ */
+export { createDevConsole } from './console.js';
+export type { DevConsole, DevConsoleOptions, DevSource, DevLevel } from './console.js';
+export { findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, } from './docker.js';
+export type { ComposeStatus, ComposeUpOptions, EnsureInfraResult, DockerLocateOptions } from './docker.js';
+export { startTscWatchers, killChild } from './tsc.js';
+export type { TscWatcherOptions, TscWatcherHandle } from './tsc.js';
+export { startRestartWatcher, isRestartChange, resolveWatchRoots } from './watcher.js';
+export type { RestartWatcherOptions, RestartWatcherHandle } from './watcher.js';

package/dist/dev/index.js

@@ -0,0 +1,10 @@
+/**
+ * @gaonjs/cli · dev — `gaon dev` 서브모듈 public export (M9-C)
+ *
+ * 상위 index.ts 는 이 모듈만 재수출한다 — 오케스트레이터 진입점은
+ * commands/dev.ts 의 runDevCommand.
+ */
+export { createDevConsole } from './console.js';
+export { findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, } from './docker.js';
+export { startTscWatchers, killChild } from './tsc.js';
+export { startRestartWatcher, isRestartChange, resolveWatchRoots } from './watcher.js';

package/dist/dev/tsc.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 { type ChildProcess } from 'node:child_process';
+export interface TscWatcherOptions {
+    /** 프로젝트 루트(tsconfig.json 위치). */
+    readonly cwd?: string;
+    /** tsconfig 경로(옵션). 생략 시 cwd/tsconfig.json. */
+    readonly project?: string;
+    /** stdout · stderr 라인 훅(통합 콘솔로 파이프). */
+    readonly onLine?: (source: 'tsc' | 'vue-tsc', line: string, level: 'info' | 'error') => void;
+    /** 자식 죽었을 때(비정상 종료 감시). */
+    readonly onExit?: (source: 'tsc' | 'vue-tsc', code: number | null) => void;
+}
+export interface TscWatcherHandle {
+    /** SIGTERM 후 잠깐 대기 · 안 죽으면 SIGKILL. */
+    stop(): Promise<void>;
+    /** 진단용 — 살아 있는 자식만 세운다. */
+    readonly children: readonly ChildProcess[];
+}
+/**
+ * tsc + vue-tsc 워처 두 개를 띄운다. project 파일이 없으면 스킵.
+ * 개별 워처를 끄는 옵션(no-tsc · no-vue-tsc)은 호출자가 결정한다.
+ */
+export declare function startTscWatchers(opts: TscWatcherOptions & {
+    readonly enableTsc?: boolean;
+    readonly enableVueTsc?: boolean;
+}): TscWatcherHandle;
+/** SIGTERM 후 timeoutMs 안에 안 죽으면 SIGKILL. */
+export declare function killChild(child: ChildProcess, timeoutMs: number): Promise<void>;

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>;