@gaonjs/cli 0.3.0 → 0.5.0

package/dist/commands/dev.js

@@ -0,0 +1,287 @@
+/**
+ * @gaonjs/cli · `gaon dev` — 개발 오케스트레이션 (M9-C · v0.15 §13.5)
+ *
+ * 하나의 명령이 개발 스택 전체를 띄운다:
+ *   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 모드 지원
+ *
+ * The One Way: `gaon dev` 하나로 전부 · 옵션은 개별 debug 용만 노출.
+ * fail-closed: Docker 없으면 명확 안내(§7.5.3), 목업 대체 절대 X (§9).
+ * ctrl-C: graceful — serve → tsc → 워처 순 정리 · Docker 는 유지(재사용)
+ *   또는 --stop-docker 시 down.
+ *
+ * HMR: v1 Vue 어댑터는 아직 Vite 통합이 없어(§6.4) 서버 재시작 방식만
+ * 지원한다. 진짜 Vue HMR 은 어댑터 통합 이후 확장 예정.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadDotEnv, VERSION } from '@gaonjs/core';
+import { registerTsResolve } from '../tsResolve.js';
+import { startDev, resolveDevLayout } from '../dev.js';
+import { generateTablesDts, watchDir } from '@gaonjs/data';
+import { generateRoutesDts } from '@gaonjs/web';
+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';
+/**
+ * gaon 셀프 경로를 찾는다. 부모가 gaon 으로 실행됐다면 argv[1] 이
+ * gaonjs/dist/cli.js (또는 개발 시 packages/gaonjs/src/cli.ts). 자식
+ * serve 도 같은 진입점을 재사용한다 — 사용자 환경에서 강제 폴백 없이
+ * 동일 CLI 를 다시 부른다.
+ */
+function resolveSelfCliEntry() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error('gaon dev · CLI 자기참조 실패: process.argv[1] 이 비어 있습니다.\n' +
+            '→ gaon 을 npm 스크립트나 bin 을 통해 실행했는지 확인하세요.');
+    }
+    // .ts 진입점(모노레포 dev)은 --experimental-strip-types 필요.
+    const isTs = scriptPath.endsWith('.ts');
+    const flags = isTs ? ['--experimental-strip-types', '--no-warnings'] : [];
+    return { node: process.execPath, args: [...flags, scriptPath] };
+}
+/**
+ * serve 자식을 하나 띄운다. stdout/stderr 을 통합 콘솔로 파이프하고,
+ * exit 콜백에서 종료 코드를 알려준다(비정상 종료 감시용).
+ */
+function spawnServe(args) {
+    const { node, args: nodeArgs } = resolveSelfCliEntry();
+    const serveArgs = ['serve'];
+    if (args.json)
+        serveArgs.push('--json');
+    if (args.port != null)
+        serveArgs.push('--port', String(args.port));
+    if (args.host != null)
+        serveArgs.push('--host', args.host);
+    const child = spawn(node, [...nodeArgs, ...serveArgs], {
+        cwd: args.cwd,
+        // detached=false + own signal handling: 부모가 명시적으로 kill 한다.
+        // 셸에서 Ctrl+C 를 누르면 자식도 같이 SIGINT 를 받는데(같은 프로세스
+        // 그룹), serve 는 자체 handler 로 graceful 종료하므로 안전.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env },
+    });
+    child.stdout?.on('data', (b) => args.console.pipe('serve', b, 'info'));
+    child.stderr?.on('data', (b) => args.console.pipe('serve', b, 'error'));
+    child.on('exit', (code, signal) => args.onExit(code, signal));
+    return child;
+}
+/**
+ * .gaon 재생성 파이프라인(M3)을 띄운다. 로그는 통합 콘솔로 흘리고,
+ * 이 모듈은 층분리를 위해 startDev 를 그대로 재사용한다.
+ */
+async function startGaonRegen(args) {
+    const layout = resolveDevLayout(args.cwd);
+    return await startDev({
+        layout,
+        regenerateTables: generateTablesDts,
+        regenerateRoutes: generateRoutesDts,
+        watch: watchDir,
+        log: (e) => {
+            if (e.kind === 'ready') {
+                const parts = [];
+                if (e.schema)
+                    parts.push('schema→tables.d.ts');
+                for (const a of e.apps)
+                    parts.push(`${a}→routes.d.ts`);
+                args.console.log('watcher', parts.length
+                    ? `.gaon 재생성 준비 완료 — ${parts.join(', ')}`
+                    : `.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 재생성`);
+            }
+            else {
+                args.console.log('watcher', '.gaon 워처 종료');
+            }
+        },
+        onError: (err) => args.console.log('watcher', err.message, 'error'),
+    });
+}
+/**
+ * `gaon dev` 진입점. 자식들을 순서대로 띄우고, SIGINT/SIGTERM 로 정리한다.
+ * 반환 프라미스는 완전 종료 시 resolve — 프로세스는 자식 워처가 살아 있는
+ * 동안 유지된다.
+ */
+export async function runDevCommand(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const json = opts.json ?? false;
+    const stopDocker = opts.stopDocker ?? false;
+    const signals = opts.signals ?? process;
+    registerTsResolve();
+    loadDotEnv(cwd);
+    const consoleOut = createDevConsole({ json, timestamp: opts.timestamp });
+    const startedAt = Date.now();
+    consoleOut.log('dev', `gaon dev · 시작 (v${VERSION}) — ${cwd}`);
+    // ── 1) Docker Compose 자동 기동 ─────────────────────────────────
+    let composeFile;
+    if (opts.noDocker !== true) {
+        try {
+            const infra = await ensureInfra({
+                cwd,
+                onLine: (line, level) => consoleOut.log('docker', line, level),
+            });
+            if (infra) {
+                composeFile = infra.composeFile;
+                consoleOut.log('docker', infra.startedNow
+                    ? `▶ compose up 완료 — ${infra.status.runningCount}/${infra.status.definedCount} 서비스 · ${infra.composeFile}`
+                    : `▶ 이미 실행 중(재사용) — ${infra.status.runningCount}/${infra.status.definedCount} 서비스 · ${infra.composeFile}`);
+            }
+            else {
+                consoleOut.log('docker', 'compose 파일이 없어 인프라 자동 기동을 건너뜁니다.');
+            }
+        }
+        catch (err) {
+            consoleOut.log('docker', err.message, 'error');
+            throw err;
+        }
+    }
+    else {
+        consoleOut.log('docker', '--no-docker · 인프라 자동 기동 비활성화');
+    }
+    // ── 2) .gaon 재생성 워처 ─────────────────────────────────────────
+    const regen = await startGaonRegen({ cwd, console: consoleOut });
+    // ── 3) tsc / vue-tsc 워치 ────────────────────────────────────────
+    const tsc = opts.noTsc && opts.noVueTsc
+        ? undefined
+        : startTscWatchers({
+            cwd,
+            enableTsc: opts.noTsc !== true,
+            enableVueTsc: opts.noVueTsc !== true,
+            onLine: (source, line, level) => consoleOut.log(source, line, level),
+            onExit: (source, code) => {
+                // 비정상 종료(code≠0) 는 알린다 · 정상(SIGTERM=null) 은 조용히.
+                if (code != null && code !== 0) {
+                    consoleOut.log(source, `[${source}] 비정상 종료 (code=${code})`, 'warn');
+                }
+            },
+        });
+    // ── 4) serve 자식 · 재시작 스케줄러 ─────────────────────────────
+    let serveChild;
+    let shuttingDown = false;
+    let restartInFlight;
+    const startServe = () => {
+        consoleOut.log('serve', '▶ serve 자식 프로세스 spawn');
+        return spawnServe({
+            cwd,
+            json,
+            port: opts.port,
+            host: opts.host,
+            console: consoleOut,
+            onExit: (code, signal) => {
+                if (shuttingDown)
+                    return;
+                // 사용자 편집으로 인한 재시작 중이면 무시 — restart 흐름이 다시 띄운다.
+                if (restartInFlight)
+                    return;
+                if (code === 0 || signal === 'SIGTERM' || signal === 'SIGINT')
+                    return;
+                consoleOut.log('serve', `serve 자식이 비정상 종료 (code=${code}, signal=${signal}) — 파일을 저장해 재시도하거나 로그를 확인하세요.`, 'error');
+            },
+        });
+    };
+    serveChild = startServe();
+    const restartServe = async (changed) => {
+        if (shuttingDown)
+            return;
+        // 이미 재시작 중이면 그 프라미스에 대기(중첩 방지).
+        if (restartInFlight)
+            return restartInFlight;
+        const summary = changed.slice(0, 3).join(', ') + (changed.length > 3 ? ` ... (+${changed.length - 3})` : '');
+        consoleOut.log('watcher', `↻ 재시작 — ${summary}`);
+        restartInFlight = (async () => {
+            try {
+                if (serveChild && serveChild.exitCode === null && serveChild.signalCode === null) {
+                    await killChild(serveChild, 3000);
+                }
+                if (shuttingDown)
+                    return;
+                serveChild = startServe();
+            }
+            finally {
+                restartInFlight = undefined;
+            }
+        })();
+        return restartInFlight;
+    };
+    // ── 5) 파일 워처(서버 재시작 트리거) ───────────────────────────
+    let restartWatcher;
+    if (opts.noWatch !== true) {
+        restartWatcher = startRestartWatcher({
+            cwd,
+            onRestart: (changed) => restartServe(changed),
+            onError: (err) => consoleOut.log('watcher', err.message, 'error'),
+        });
+        consoleOut.log('watcher', restartWatcher.roots.length > 0
+            ? `▶ 재시작 워치 — ${restartWatcher.roots.map((r) => shortenPath(r, cwd)).join(', ')}`
+            : `▶ 재시작 워치 — 감시 대상 없음(apps/ · domain/ 등 확인)`);
+    }
+    consoleOut.log('dev', `준비 완료 — 부팅 ${Date.now() - startedAt}ms (Ctrl+C 로 종료)`);
+    // ── 6) SIGINT/SIGTERM → graceful ────────────────────────────────
+    await new Promise((resolvePromise) => {
+        const stop = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            consoleOut.log('dev', '종료 신호 수신 — 정리 중...');
+            void (async () => {
+                try {
+                    // 순서: 재시작 워처 → serve → tsc → .gaon 워처 → Docker(옵션)
+                    restartWatcher?.close();
+                    if (serveChild) {
+                        await killChild(serveChild, 5000);
+                    }
+                    if (tsc) {
+                        await tsc.stop();
+                    }
+                    regen.close();
+                    if (stopDocker && composeFile) {
+                        consoleOut.log('docker', '--stop-docker · compose down 실행');
+                        try {
+                            await composeDown(composeFile, {
+                                onLine: (line, level) => consoleOut.log('docker', line, level),
+                            });
+                        }
+                        catch (err) {
+                            consoleOut.log('docker', err.message, 'error');
+                        }
+                    }
+                    else if (composeFile) {
+                        consoleOut.log('docker', 'compose 는 유지 · 다음 gaon dev 에서 재사용');
+                    }
+                }
+                finally {
+                    consoleOut.log('dev', 'gaon dev · 종료');
+                    resolvePromise();
+                }
+            })();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}
+/** cwd 기준 상대경로로 짧게(로그 가독성). */
+function shortenPath(p, cwd) {
+    const normP = resolve(p);
+    const normCwd = resolve(cwd);
+    if (normP === normCwd)
+        return '.';
+    if (normP.startsWith(normCwd + '/'))
+        return normP.slice(normCwd.length + 1);
+    return normP;
+}
+// (test·doc 목적으로 노출) — 파일이 실제 존재하는지 여부는 호출자 판단.
+export const _internals = {
+    resolveSelfCliEntry,
+    fileURLToPathSafe: (u) => (u.startsWith('file:') ? fileURLToPath(u) : u),
+    existsSync,
+};

package/dist/commands/new.d.ts

@@ -0,0 +1,45 @@
+/** `gaon new` 옵션. 모두 선택적 — 기본값이 The One Way. */
+export interface NewCommandOptions {
+    /** 프로젝트 생성 위치의 부모 폴더. 기본 process.cwd(). */
+    readonly cwd?: string;
+    /** 자동화용 구조화 출력. */
+    readonly json?: boolean;
+    /** 의존성 설치 스킵(테스트·오프라인). */
+    readonly skipInstall?: boolean;
+    /** git init · 첫 커밋 스킵(테스트·기존 git 저장소에 삽입). */
+    readonly skipGit?: boolean;
+    /** 패키지 매니저. 기본 pnpm(모노레포 관례 정합). */
+    readonly packageManager?: 'pnpm' | 'npm' | 'yarn';
+    /**
+     * (테스트 훅) 템플릿의 gaonjs 의존성 버전. 미지정 시 파사드(gaonjs)
+     * 패키지의 실 버전을 자동 조회한다(package.json).
+     */
+    readonly gaonjsVersion?: string;
+}
+/** JSON 리포트(--json). 사람 모드는 콘솔에 사람이 읽는 요약을 출력한다. */
+export interface NewCommandResult {
+    readonly ok: boolean;
+    readonly project: string;
+    readonly path: string;
+    readonly filesCreated: number;
+    readonly install: {
+        readonly ran: boolean;
+        readonly skipped: boolean;
+        readonly packageManager: string;
+        readonly durationMs: number;
+        readonly exitCode: number | null;
+    };
+    readonly git: {
+        readonly ran: boolean;
+        readonly skipped: boolean;
+        readonly initialized: boolean;
+        readonly firstCommit: boolean;
+    };
+    readonly totalMs: number;
+    readonly error?: string;
+}
+/**
+ * `gaon new <name>` 실행. 파일 생성 → pnpm install → git init 순서.
+ * 각 단계는 옵션으로 스킵 가능. 반환값은 프로세스 종료 코드(0=성공).
+ */
+export declare function runNewCommand(name: string, opts?: NewCommandOptions): Promise<number>;

package/dist/commands/new.js

@@ -0,0 +1,274 @@
+// @gaonjs/cli · `gaon new <name>` — 프로젝트 스캐폴드 (M9-F).
+//
+// v0.15 §13.5 M9 완료 기준 "설치 후 첫 화면까지 60초" 를 만족시키기 위한
+// One Way. `gaon new demo` → cd demo → `gaon serve` → http://localhost:3000
+// 응답 이 전체 흐름의 목표. 60초 안에 이 왕복이 끝나야 한다.
+//
+// 관례(§2 · errata E-1 · E-3 · E-4 · E-5):
+//   · 폴더 배치: apps/<앱>/ + domain/ + shared/ (앱 밖에 domain)
+//   · 프론트: Vue + Inertia SPA (`gaonjs/vue`)
+//   · 인프라: docker-compose.yaml 5종(pg · redis · nats · mailpit · minio)
+//   · 컴포저블·레이아웃: E-5(apps/<앱>/composables + shared/composables, 대칭
+//     구조 · layouts/Default.vue 존재 시 자동 적용)
+//   · 자동 import 금지 — 모든 import 는 명시적으로(E-5 §2.4).
+//
+// 옵션은 최소로: --skip-install · --skip-git · --json · --package-manager.
+// The One Way — pnpm workspace monorepo · Vue · Inertia SPA · 5종 인프라.
+//
+// 이 파일은 파일 생성·설치·git init 만 담당하고, argv 파싱과 배선은
+// index.ts 가 통합한다(M9-F 는 편집 X — M1 이 통합 커밋).
+import { existsSync, mkdirSync, readdirSync, writeFileSync, } from 'node:fs';
+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';
+/** 이름 유효성 — npm 패키지명 규칙(단순 부분)만 검사. */
+function validateProjectName(name) {
+    if (!name)
+        throw new Error('프로젝트 이름이 비어 있습니다.');
+    if (name.includes('/') || name.includes('\\')) {
+        throw new Error(`프로젝트 이름에 '/' 또는 '\\\\' 는 사용할 수 없습니다: ${name}`);
+    }
+    if (name.includes('..')) {
+        throw new Error(`프로젝트 이름에 '..' 는 사용할 수 없습니다: ${name}`);
+    }
+    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(name)) {
+        throw new Error(`프로젝트 이름은 영문/숫자/-/_ 로 시작해 같은 문자만 씁니다: ${name}\n` +
+            `  → 예: gaon new my-app · gaon new demo`);
+    }
+}
+/** 파사드(gaonjs) 패키지의 실 버전을 찾는다 — package.json 을 위로 훑는다. */
+function detectGaonjsVersion() {
+    // 가장 안전한 방법: 이 파일 위치를 기준으로 packages/gaonjs/package.json 을
+    // 상향 탐색. 개발 트리(src)와 배포 트리(dist) 모두에서 동작한다.
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(dir, '..', 'gaonjs', 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const raw = readFileSync(candidate, 'utf8');
+                const pkg = JSON.parse(raw);
+                if (typeof pkg.version === 'string')
+                    return `^${pkg.version}`;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // 발견 못 하면 최근 스텁 배포 라인의 안전 하한.
+    return '^0.5.0';
+}
+/** 대상 폴더가 비어 있는지(생성 대상으로 안전한지) 확인. */
+function isEmptyOrMissing(dir) {
+    if (!existsSync(dir))
+        return true;
+    try {
+        const entries = readdirSync(dir);
+        return entries.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** 파일 전체를 디스크에 쓴다. 이미 있으면 예외. */
+function writeAll(root, files) {
+    let count = 0;
+    for (const f of files) {
+        const abs = join(root, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.contents, 'utf8');
+        count += 1;
+    }
+    return count;
+}
+/** 패키지 매니저 install 명령을 동기 실행. 반환값에 종료 코드·시간 포함.
+ *  json 모드에서는 stdout 을 완전 격리해 JSON 라인이 pnpm progress 로
+ *  오염되지 않도록 한다 — 파이프라인 파서 안전 정합. */
+function runInstall(root, pm, json) {
+    const args = ['install'];
+    const t0 = Date.now();
+    // stdio: json 모드에서는 stdout 을 ignore(우리 JSON 을 오염시키지 않게),
+    //        stderr 는 사용자에게 원인 진단이 필요할 수 있어 inherit.
+    //        human 모드에서는 모든 스트림을 inherit(사용자가 progress 를 본다).
+    const res = spawnSync(pm, args, {
+        cwd: root,
+        stdio: json ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+        env: process.env,
+    });
+    const ms = Date.now() - t0;
+    if (res.error) {
+        process.stderr.write(`  ✗ ${pm} 을 찾지 못했습니다. → ${pm} 을 설치하거나 --skip-install 로 건너뛰세요.\n`);
+        return { code: -1, ms };
+    }
+    return { code: res.status, ms };
+}
+/** git init + 첫 커밋. git 이 없으면 조용히 스킵(로컬에 git 없이도 스캐폴드는 성공). */
+function runGitInit(root) {
+    const opts = { cwd: root, stdio: 'ignore', env: process.env };
+    const init = spawnSync('git', ['init', '--initial-branch=main'], opts);
+    if (init.error || init.status !== 0)
+        return { initialized: false, firstCommit: false };
+    spawnSync('git', ['add', '-A'], opts);
+    // 첫 커밋 — 사용자 git config 가 없어도 실패하지 않도록 -c 로 임시 identity 주입.
+    const commit = spawnSync('git', [
+        '-c',
+        'user.email=gaon@gaonjs.dev',
+        '-c',
+        'user.name=Gaon',
+        'commit',
+        '-m',
+        'chore: gaon new — initial scaffold',
+        '--no-gpg-sign',
+    ], opts);
+    return { initialized: true, firstCommit: commit.status === 0 };
+}
+/**
+ * `gaon new <name>` 실행. 파일 생성 → pnpm install → git init 순서.
+ * 각 단계는 옵션으로 스킵 가능. 반환값은 프로세스 종료 코드(0=성공).
+ */
+export async function runNewCommand(name, opts = {}) {
+    const t0 = Date.now();
+    const cwd = opts.cwd ?? process.cwd();
+    const pm = opts.packageManager ?? 'pnpm';
+    const json = opts.json ?? false;
+    const emitError = (msg, totalMs) => {
+        if (json) {
+            const result = {
+                ok: false,
+                project: name,
+                path: resolve(cwd, name),
+                filesCreated: 0,
+                install: { ran: false, skipped: true, packageManager: pm, durationMs: 0, exitCode: null },
+                git: { ran: false, skipped: true, initialized: false, firstCommit: false },
+                totalMs,
+                error: msg,
+            };
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        else {
+            process.stderr.write(`  ✗ gaon new: ${msg}\n`);
+        }
+        return 1;
+    };
+    try {
+        validateProjectName(name);
+    }
+    catch (err) {
+        return emitError(err instanceof Error ? err.message : String(err), Date.now() - t0);
+    }
+    const root = resolve(cwd, name);
+    if (!isEmptyOrMissing(root)) {
+        return emitError(`대상 폴더가 비어 있지 않습니다: ${root}\n` +
+            `  → 다른 이름을 쓰거나 폴더를 비운 뒤 다시 실행하세요.`, Date.now() - t0);
+    }
+    // 파일 생성 — 실패 시 부분 생성물이 남지 않도록 폴더를 정리하지는 않는다
+    // (사용자가 원인 파악 후 rm -rf 로 지우도록). 정상 흐름에서는 문제 없음.
+    const gaonjsVersion = opts.gaonjsVersion ?? detectGaonjsVersion();
+    const files = renderProjectFiles({ projectName: name, gaonjsVersion });
+    let filesCreated = 0;
+    try {
+        mkdirSync(root, { recursive: true });
+        filesCreated = writeAll(root, files);
+    }
+    catch (err) {
+        return emitError(`파일 생성 실패: ${err instanceof Error ? err.message : String(err)}`, Date.now() - t0);
+    }
+    // pnpm install (또는 npm/yarn) — 스킵 시 안내만.
+    const installReport = {
+        ran: false,
+        skipped: opts.skipInstall === true,
+        packageManager: pm,
+        durationMs: 0,
+        exitCode: null,
+    };
+    if (!opts.skipInstall) {
+        if (!json)
+            process.stdout.write(`\n  · 의존성 설치 (${pm} install) ...\n`);
+        const { code, ms } = runInstall(root, pm, json);
+        installReport.ran = true;
+        installReport.durationMs = ms;
+        installReport.exitCode = code;
+        if (code !== 0) {
+            // install 실패는 스캐폴드 자체 실패로 취급하지 않는다 — 파일은 이미
+            // 만들어졌으므로 사용자가 원인(레지스트리·네트워크) 확인 후 재시도 가능.
+            // 종료 코드는 실패로 반환(자동화 파이프라인 정합).
+            const total = Date.now() - t0;
+            if (json) {
+                const result = {
+                    ok: false,
+                    project: name,
+                    path: root,
+                    filesCreated,
+                    install: installReport,
+                    git: { ran: false, skipped: true, initialized: false, firstCommit: false },
+                    totalMs: total,
+                    error: `${pm} install 실패 (exit ${code})`,
+                };
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`  ✗ ${pm} install 이 실패했습니다 (exit ${code}).\n` +
+                    `  → 네트워크·레지스트리 상태를 확인한 뒤 ${root} 에서 다시 ${pm} install 을 실행하세요.\n`);
+            }
+            return 1;
+        }
+    }
+    // git init + 첫 커밋 — 스킵 시 그대로 넘어감.
+    const gitReport = { ran: false, skipped: opts.skipGit === true, initialized: false, firstCommit: false };
+    if (!opts.skipGit) {
+        if (!json)
+            process.stdout.write(`  · git 저장소 초기화 (git init + 첫 커밋) ...\n`);
+        const g = runGitInit(root);
+        gitReport.ran = true;
+        gitReport.initialized = g.initialized;
+        gitReport.firstCommit = g.firstCommit;
+    }
+    const totalMs = Date.now() - t0;
+    if (json) {
+        const result = {
+            ok: true,
+            project: name,
+            path: root,
+            filesCreated,
+            install: installReport,
+            git: gitReport,
+            totalMs,
+        };
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return 0;
+    }
+    // 사람 모드 요약 — 다음 단계를 § 방향과 함께 안내(§7.5.3 원칙 정합).
+    const lines = [''];
+    lines.push(`  gaon new ${name} — 스캐폴드 완료 (${filesCreated}개 파일 · ${totalMs}ms)`);
+    lines.push('');
+    lines.push(`   폴더: ${root}`);
+    if (installReport.ran) {
+        lines.push(`   ${pm} install: ${installReport.exitCode === 0 ? '성공' : '실패'} (${installReport.durationMs}ms)`);
+    }
+    else {
+        lines.push(`   ${pm} install: 스킵 (--skip-install)`);
+    }
+    if (gitReport.ran) {
+        lines.push(`   git init: ${gitReport.initialized ? '완료' : '실패'} · 첫 커밋: ${gitReport.firstCommit ? '완료' : '실패(수동)'}`);
+    }
+    else {
+        lines.push(`   git init: 스킵 (--skip-git)`);
+    }
+    lines.push('');
+    lines.push('  다음 단계:');
+    lines.push(`   1) cd ${name}`);
+    lines.push('   2) cp .env.example .env       # 환경 변수 편집');
+    lines.push('   3) gaon dev                    # Docker + 타입 브리지 + serve 통합');
+    lines.push('   4) http://localhost:3000       # 홈 페이지 확인 (60초 실측 · v0.15 §13.5 M9)');
+    lines.push('');
+    lines.push('  문서: https://gaonjs.dev');
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+    return 0;
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,11 @@
+export type TestScope = 'unit' | 'integration' | 'all';
+export interface TestCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    readonly scope?: TestScope;
+}
+/**
+ * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
+ * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ */
+export declare function runTestCommand(args?: readonly string[], opts?: TestCommandOptions): Promise<number>;