@gaonjs/cli 0.4.0 → 0.10.0

package/dist/commands/check.d.ts

@@ -0,0 +1,50 @@
+export type CheckStep = 'typecheck' | 'vue-tsc' | 'build' | 'doctor';
+export interface CheckCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    /** 지정 시 그 검사 하나만 실행. 나머지는 스킵. */
+    readonly only?: CheckStep;
+    /** true 면 doctor 도 포함. 기본 false. */
+    readonly includeDoctor?: boolean;
+}
+export type CheckStepStatus = 'passed' | 'failed' | 'skipped';
+export interface CheckStepResult {
+    readonly step: CheckStep;
+    readonly status: CheckStepStatus;
+    /** 실행에 쓴 커맨드(디버깅용) — skipped 는 undefined. */
+    readonly command?: string;
+    /** 원본 exit code. skipped/doctor 는 undefined. */
+    readonly exitCode?: number;
+    /** stdout+stderr 합본(사람 UI 에 그대로 출력). skipped 는 짧은 사유. */
+    readonly output?: string;
+}
+export type RegenStatus = 'done' | 'skipped' | 'failed';
+/**
+ * 검사 직전 .gaon 재생성 결과. 규칙 3(§13.4-5) — check 는 최신 타입 브리지
+ * 위에서 검증해야 한다. done = 재생성함 · skipped = 재생성할 대상 없음
+ * (domain/schema · apps/* 없음) · failed = 스키마/라우트 구문 오류로 재생성
+ * 실패(이 경우 검사를 진행하지 않고 실패로 종료).
+ */
+export interface CheckRegen {
+    readonly status: RegenStatus;
+    /** tables.d.ts 를 재생성했는가. */
+    readonly tables: boolean;
+    /** routes.d.ts 를 재생성한 앱 이름. */
+    readonly apps: readonly string[];
+    /** 실패 시 에러 + 수리 안내. done/skipped 는 undefined. */
+    readonly output?: string;
+}
+export interface CheckReport {
+    readonly ok: boolean;
+    /** 검사 직전 .gaon 재생성 단계(규칙 3). */
+    readonly regen: CheckRegen;
+    readonly steps: readonly CheckStepResult[];
+}
+/**
+ * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
+ * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만
+ * 실행. --include-doctor 시 doctor 추가.
+ *
+ * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
+ */
+export declare function runCheckCommand(opts?: CheckCommandOptions): Promise<number>;

package/dist/commands/check.js

@@ -0,0 +1,286 @@
+/**
+ * @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`).
+ *
+ * The One Way — 하나의 명령이 3(선택 4) 검사를 순서대로 돌린다:
+ *   1) typecheck (pnpm typecheck 또는 tsc --noEmit)
+ *   2) vue-tsc   (pnpm vue-tsc 또는 vue-tsc --noEmit)
+ *   3) build     (pnpm build)
+ *   (4) doctor   (--include-doctor 시 · 코어 재사용)
+ *
+ * 옵션 최소:
+ *   --json                     자동화 · 각 검사의 passed/failed/skipped
+ *   --only <name>              단일 검사만
+ *   --include-doctor           check 안에서 doctor 도 · 기본 off
+ *
+ * exit code: 검사가 하나라도 실패하면 1, 그 외 0. 미리 검사할 대상이
+ * 하나도 없으면(예: 스크립트도 없고 바이너리도 없음) 스킵으로 리포트 —
+ * 우회가 아니라 사용자에게 "설정이 부족하다" 를 명확히 노출.
+ *
+ * §9 실 인프라 — 서브 프로세스 실행은 실 `child_process.spawn` 을 쓴다.
+ * 목업 X.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { generateTablesDts } from '@gaonjs/data';
+import { generateRoutesDts } from '@gaonjs/web';
+import { runDoctorCommand } from '../doctor.js';
+import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
+import { registerTsResolve } from '../tsResolve.js';
+/**
+ * 프로젝트 스크립트 존재 여부. pnpm/npm 어느 쪽이든 `scripts.<name>` 을
+ * 정의해 두면 우선 사용한다.
+ */
+function hasScript(cwd, name) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function binExists(cwd, name) {
+    return existsSync(join(cwd, 'node_modules', '.bin', name));
+}
+/**
+ * 단일 서브 프로세스를 spawn 해서 stdout+stderr 를 모으고 exit 코드를
+ * 돌려준다. 실행 실패(파일 없음)는 exit 127 로 매핑.
+ */
+function runSubprocess(cwd, cmd, args) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(cmd, args, { cwd, env: process.env });
+        let output = '';
+        child.stdout.on('data', (b) => (output += b.toString('utf8')));
+        child.stderr.on('data', (b) => (output += b.toString('utf8')));
+        child.on('error', (err) => {
+            resolvePromise({ exitCode: 127, output: output + String(err) });
+        });
+        child.on('close', (code) => {
+            resolvePromise({ exitCode: code ?? 1, output });
+        });
+    });
+}
+/** typecheck · vue-tsc 는 노말 검사 · build 는 산출물 생성. */
+async function runStep(step, cwd) {
+    // 1) 사용자 스크립트가 정의돼 있으면 그걸 쓴다(한 곳에서 관리).
+    const scriptName = step;
+    if (hasScript(cwd, scriptName)) {
+        const cmd = 'pnpm';
+        const args = ['run', scriptName];
+        const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        return {
+            step,
+            status: exitCode === 0 ? 'passed' : 'failed',
+            command: `${cmd} ${args.join(' ')}`,
+            exitCode,
+            output,
+        };
+    }
+    // 2) 폴백 — 로컬 바이너리를 직접 부른다.
+    if (step === 'typecheck') {
+        // tsc 는 로컬 node_modules 또는 workspace 루트에 있다.
+        const tsconfigPath = join(cwd, 'tsconfig.json');
+        if (!existsSync(tsconfigPath)) {
+            return {
+                step,
+                status: 'skipped',
+                output: `tsconfig.json 이 없어 typecheck 를 건너뜁니다: ${tsconfigPath}\n→ 프로젝트 루트에 tsconfig.json 을 만들거나 package.json 에 "typecheck" 스크립트를 정의하세요.`,
+            };
+        }
+        const tsBin = join(cwd, 'node_modules', 'typescript', 'bin', 'tsc');
+        if (!existsSync(tsBin)) {
+            return {
+                step,
+                status: 'skipped',
+                output: `typescript 가 설치돼 있지 않아 typecheck 를 건너뜁니다.\n→ pnpm add -D typescript 후 다시 실행하세요.`,
+            };
+        }
+        const cmd = process.execPath;
+        const args = [tsBin, '--noEmit', '-p', tsconfigPath];
+        const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        return {
+            step,
+            status: exitCode === 0 ? 'passed' : 'failed',
+            command: `node tsc --noEmit -p ${tsconfigPath}`,
+            exitCode,
+            output,
+        };
+    }
+    if (step === 'vue-tsc') {
+        // vue-tsc 는 .vue 가 하나라도 있는 프로젝트에서만 의미가 있다 —
+        // 없으면 스킵(설치 안 됐어도 정상).
+        if (!binExists(cwd, 'vue-tsc')) {
+            return {
+                step,
+                status: 'skipped',
+                output: 'vue-tsc 가 설치돼 있지 않아 스킵합니다(.vue 파일이 없으면 정상).',
+            };
+        }
+        const tsconfigPath = join(cwd, 'tsconfig.json');
+        if (!existsSync(tsconfigPath)) {
+            return {
+                step,
+                status: 'skipped',
+                output: 'tsconfig.json 이 없어 vue-tsc 를 건너뜁니다.',
+            };
+        }
+        const cmd = join(cwd, 'node_modules', '.bin', 'vue-tsc');
+        const args = ['--noEmit', '-p', tsconfigPath];
+        const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+        return {
+            step,
+            status: exitCode === 0 ? 'passed' : 'failed',
+            command: `vue-tsc --noEmit -p ${tsconfigPath}`,
+            exitCode,
+            output,
+        };
+    }
+    // build — 사용자 스크립트가 없으면 pnpm -r build 를 최선의 폴백으로 시도.
+    const cmd = 'pnpm';
+    const args = ['-r', 'run', 'build'];
+    const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+    return {
+        step,
+        status: exitCode === 0 ? 'passed' : 'failed',
+        command: `${cmd} ${args.join(' ')}`,
+        exitCode,
+        output,
+    };
+}
+/** doctor 는 이미 있는 명령을 재사용 — cwd 만 넘긴다. json 은 상위에서. */
+async function runDoctorStep(cwd) {
+    try {
+        // runDoctorCommand 는 stdout 에 리포트를 그대로 찍는다. 결과 객체로
+        // 성공/실패를 판단한다.
+        const result = await runDoctorCommand({ cwd, json: false });
+        const failed = !!result.fatal || result.errors.length > 0;
+        return {
+            step: 'doctor',
+            status: failed ? 'failed' : 'passed',
+            command: 'gaon doctor',
+            exitCode: failed ? 1 : 0,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            step: 'doctor',
+            status: 'failed',
+            command: 'gaon doctor',
+            exitCode: 1,
+            output: msg,
+        };
+    }
+}
+/**
+ * 검사 직전 .gaon 타입 브리지를 1회 재생성한다(규칙 3 · §13.4-5). 개발
+ * 서버 없이 부르는 check 가 stale/누락된 .gaon 으로 검증해 잘못된 통과·
+ * 실패를 내지 않게 한다. --only 여부와 무관하게 항상 먼저 돈다 —
+ * typecheck·vue-tsc·build 가 모두 .gaon 을 소비하기 때문.
+ */
+async function regenerateGaon(cwd) {
+    const layout = resolveDevLayout(cwd);
+    if (!layout.schemaDir && layout.apps.length === 0) {
+        return { status: 'skipped', tables: false, apps: [] };
+    }
+    // 생성기는 사용자 스키마·컨트롤러 .ts 를 동적 import 한다. TS-for-ESM
+    // 관례상 상대 import 가 `.js` 라 Node 가 못 찾으므로 `.js`→`.ts` 해석
+    // 훅을 등록한다(gaon dev·serve 와 동일 · tsResolve).
+    registerTsResolve();
+    try {
+        const result = await regenerateGaonOnce(layout, {
+            regenerateTables: generateTablesDts,
+            regenerateRoutes: generateRoutesDts,
+        });
+        return { status: 'done', tables: result.tables, apps: result.apps };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            status: 'failed',
+            tables: false,
+            apps: [],
+            output: `.gaon 타입 브리지 재생성에 실패해 검사를 중단합니다: ${msg}\n` +
+                `→ domain/schema/*.ts 와 apps/*/routes.ts·controllers/*.ts 의 구문 오류를 고친 뒤 다시 실행하세요.`,
+        };
+    }
+}
+/**
+ * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
+ * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만
+ * 실행. --include-doctor 시 doctor 추가.
+ *
+ * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
+ */
+export async function runCheckCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const only = opts.only;
+    const includeDoctor = opts.includeDoctor ?? false;
+    // 규칙 3 — 검사는 최신 타입 브리지 위에서만 신뢰할 수 있다. 재생성이
+    // 실패하면 stale .gaon 으로 검사하지 않고 즉시 중단한다.
+    const regen = await regenerateGaon(cwd);
+    const steps = regen.status === 'failed'
+        ? []
+        : only
+            ? [only]
+            : ['typecheck', 'vue-tsc', 'build', ...(includeDoctor ? ['doctor'] : [])];
+    const results = [];
+    for (const step of steps) {
+        if (step === 'doctor') {
+            results.push(await runDoctorStep(cwd));
+        }
+        else {
+            results.push(await runStep(step, cwd));
+        }
+    }
+    const ok = regen.status !== 'failed' && results.every((r) => r.status !== 'failed');
+    const report = { ok, regen, steps: results };
+    if (json) {
+        process.stdout.write(JSON.stringify(report) + '\n');
+    }
+    else {
+        writeRegenLine(regen);
+        for (const r of results) {
+            const mark = r.status === 'passed' ? '✓' : r.status === 'failed' ? '✗' : '·';
+            process.stdout.write(`  ${mark} ${r.step} — ${r.status}${r.command ? ` (${r.command})` : ''}\n`);
+            if (r.status === 'failed' && r.output) {
+                process.stdout.write(r.output.endsWith('\n') ? r.output : r.output + '\n');
+            }
+            if (r.status === 'skipped' && r.output) {
+                process.stdout.write(`    ${r.output.split('\n').join('\n    ')}\n`);
+            }
+        }
+        process.stdout.write(ok ? '  ▶ gaon check · 통과\n' : '  ✗ gaon check · 실패\n');
+    }
+    return ok ? 0 : 1;
+}
+/** 사람 UI 에 재생성 단계를 한 줄로 보고한다. */
+function writeRegenLine(regen) {
+    if (regen.status === 'failed') {
+        process.stdout.write('  ✗ .gaon 재생성 — failed\n');
+        if (regen.output)
+            process.stdout.write(`    ${regen.output.split('\n').join('\n    ')}\n`);
+        return;
+    }
+    if (regen.status === 'skipped') {
+        process.stdout.write('  · .gaon 재생성 — skipped (domain/schema · apps/* 없음)\n');
+        return;
+    }
+    const parts = [];
+    if (regen.tables)
+        parts.push('tables.d.ts');
+    for (const app of regen.apps)
+        parts.push(`${app}/routes.d.ts`);
+    process.stdout.write(`  ✓ .gaon 재생성 — ${parts.join(', ')}\n`);
+}

package/dist/commands/console.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @gaonjs/cli · `gaon console` — REPL 진입점 (M9-G · v0.15 §13.5)
+ *
+ * Rails console 스타일 — 프로젝트 컨텍스트(gaon.config.ts + apps/*)를
+ * 로드해 배터리(DB · 모델 · 서비스)가 살아있는 상태로 Node REPL 을 띄운다.
+ * 종료는 REPL 관례대로 `.exit` 또는 Ctrl+C(2회).
+ *
+ * The One Way — 단일 진입점 · 옵션 최소:
+ *   · (기본)         gaon.config.ts 로드 → wireGaon → REPL
+ *   · --no-config    순수 REPL (config 없이 · 프로젝트 밖 실험용)
+ *   · --json         부팅 이벤트만 JSON 라인(자동화 · CI 스모크). REPL 자체는
+ *                    stdin TTY 를 그대로 물려 준다.
+ *
+ * loadDomain 은 domain/models · services 를 REPL 컨텍스트에 노출한다.
+ * `.later()` 로 잡을 스케줄해 볼 수 있게 하기 위해 도메인 잡도 함께 로드한다.
+ *
+ * fail-closed(§7.5.3): config 로드 실패는 stderr 에 수리 안내를 던지고
+ * exit code 1 로 나간다 — 우회 없이 정확한 원인을 노출.
+ */
+import { type REPLServer } from 'node:repl';
+export interface ConsoleCommandOptions {
+    readonly cwd?: string;
+    /** 프로젝트 컨텍스트 로드 없이 순수 REPL. 기본 false. */
+    readonly noConfig?: boolean;
+    /** 부팅 이벤트를 JSON 라인으로 출력. REPL 세션 자체는 사람 UI. */
+    readonly json?: boolean;
+    /**
+     * REPL 서버 팩토리 — 테스트가 stdin/stdout 을 갈아 끼울 수 있게 주입점을
+     * 남긴다. 미주입 시 process.stdin/stdout 을 쓰는 기본 REPL.
+     */
+    readonly replFactory?: () => REPLServer;
+    /** 종료 감지용 signals — 테스트에서 SIGINT 를 주입한다. 기본 process. */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * `gaon console` 진입점.
+ *
+ * --no-config: env 만 로드하고 순수 REPL 을 띄운다.
+ * 기본:        loadDotEnv → loadGaonConfig → wireGaon → loadDomain →
+ *              REPL 컨텍스트에 gaon(wired) · config · apps · models · services
+ *              · domain 을 심고, .exit 대기.
+ */
+export declare function runConsoleCommand(opts?: ConsoleCommandOptions): Promise<void>;

package/dist/commands/console.js

@@ -0,0 +1,129 @@
+/**
+ * @gaonjs/cli · `gaon console` — REPL 진입점 (M9-G · v0.15 §13.5)
+ *
+ * Rails console 스타일 — 프로젝트 컨텍스트(gaon.config.ts + apps/*)를
+ * 로드해 배터리(DB · 모델 · 서비스)가 살아있는 상태로 Node REPL 을 띄운다.
+ * 종료는 REPL 관례대로 `.exit` 또는 Ctrl+C(2회).
+ *
+ * The One Way — 단일 진입점 · 옵션 최소:
+ *   · (기본)         gaon.config.ts 로드 → wireGaon → REPL
+ *   · --no-config    순수 REPL (config 없이 · 프로젝트 밖 실험용)
+ *   · --json         부팅 이벤트만 JSON 라인(자동화 · CI 스모크). REPL 자체는
+ *                    stdin TTY 를 그대로 물려 준다.
+ *
+ * loadDomain 은 domain/models · services 를 REPL 컨텍스트에 노출한다.
+ * `.later()` 로 잡을 스케줄해 볼 수 있게 하기 위해 도메인 잡도 함께 로드한다.
+ *
+ * fail-closed(§7.5.3): config 로드 실패는 stderr 에 수리 안내를 던지고
+ * exit code 1 로 나간다 — 우회 없이 정확한 원인을 노출.
+ */
+import { start as startRepl } from 'node:repl';
+import { loadDotEnv } from '@gaonjs/core';
+import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
+import { registerTsResolve } from '../tsResolve.js';
+import { loadDomain } from '../domain.js';
+function humanEvent(e) {
+    switch (e.kind) {
+        case 'starting':
+            return `  gaon console · 시작 — cwd=${e.cwd}${e.noConfig ? ' · --no-config' : ''}`;
+        case 'loaded': {
+            const cfg = e.configPath ? `config=${e.configPath}` : 'config=(없음 · 기본값)';
+            const apps = e.apps.length ? `apps=[${e.apps.join(', ')}]` : 'apps=(없음)';
+            const d = `domain(jobs=${e.domain.jobs} · listeners=${e.domain.listeners} · mails=${e.domain.mails})`;
+            return `  ▶ 로드됨 — ${cfg} · ${apps} · ${d}`;
+        }
+        case 'ready':
+            return e.noConfig
+                ? '  ▶ REPL 준비 (--no-config · 프로젝트 컨텍스트 없음). .exit 로 종료.'
+                : '  ▶ REPL 준비. 컨텍스트: gaon, config, apps, models, services, domain. .exit 로 종료.';
+        case 'exited':
+            return '  gaon console · 종료';
+    }
+}
+/**
+ * `gaon console` 진입점.
+ *
+ * --no-config: env 만 로드하고 순수 REPL 을 띄운다.
+ * 기본:        loadDotEnv → loadGaonConfig → wireGaon → loadDomain →
+ *              REPL 컨텍스트에 gaon(wired) · config · apps · models · services
+ *              · domain 을 심고, .exit 대기.
+ */
+export async function runConsoleCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const noConfig = opts.noConfig ?? false;
+    const signals = opts.signals ?? process;
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    // .ts 상대 import 해석기 — 사용자 gaon.config.ts · domain/* 로드에 필요.
+    registerTsResolve();
+    loadDotEnv(cwd);
+    emit({ kind: 'starting', cwd, noConfig });
+    let wired;
+    let domain;
+    let configPath;
+    const context = {};
+    if (!noConfig) {
+        configPath = findConfigPath(cwd);
+        const config = await loadGaonConfig(cwd);
+        wired = await wireGaon(config, cwd);
+        domain = await loadDomain(cwd);
+        context.gaon = wired;
+        context.config = config;
+        context.apps = wired.apps;
+        context.domain = domain;
+        // 모델·서비스 자동 노출은 사용자 코드 스캔이 필요해 v1 은 domain 요약만
+        // 노출한다(§13.5 M9-G 최소 스코프). 사용자는 컨텍스트에서 필요 파일을
+        // `await import(...)` 로 가져올 수 있다(REPL 은 top-level await 허용).
+        context.models = {};
+        context.services = {};
+        emit({
+            kind: 'loaded',
+            configPath,
+            apps: wired.apps.map((a) => a.name),
+            domain: {
+                jobs: domain.jobs,
+                listeners: domain.listeners,
+                mails: domain.mails,
+            },
+        });
+    }
+    emit({ kind: 'ready', noConfig });
+    // REPL 시작 — 테스트는 replFactory 로 stdin/stdout 을 갈아 끼운다.
+    const repl = opts.replFactory
+        ? opts.replFactory()
+        : startRepl({
+            prompt: noConfig ? 'gaon(no-config)> ' : 'gaon> ',
+            useColors: true,
+            // top-level await 허용 — 배터리 검증용 fetch/DB 조회에 편리.
+            // (Node ≥ 22 에서 안정 지원.)
+            useGlobal: false,
+        });
+    // 컨텍스트를 REPL 에 주입.
+    Object.assign(repl.context, context);
+    // Ctrl+C 로 nudge, 종료는 SIGINT 로 배선 close.
+    await new Promise((resolveExit) => {
+        const done = async () => {
+            signals.off('SIGINT', done);
+            signals.off('SIGTERM', done);
+            if (wired) {
+                try {
+                    await wired.close();
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`  ✗ 종료 중 오류: ${msg}\n`);
+                }
+            }
+            emit({ kind: 'exited' });
+            resolveExit();
+        };
+        repl.on('exit', () => void done());
+        signals.on('SIGINT', () => void done());
+        signals.on('SIGTERM', () => void done());
+    });
+}

package/dist/commands/db.d.ts

@@ -1,4 +1,4 @@
-export type DbSubcommand = 'diff' | 'migrate' | 'reset' | 'seed';
+export type DbSubcommand = 'diff' | 'migrate' | 'reset' | 'seed' | 'status';
 export interface DbCommandOptions {
     /** 프로젝트 루트 — gaon.config.ts·domain/schema 위치. 기본 process.cwd(). */
     readonly cwd?: string;
@@ -12,6 +12,8 @@ export interface DbCommandOptions {
     readonly yes?: boolean;
     /** migrate/reset dry-run — 실행 없이 SQL 만 출력. */
     readonly dryRun?: boolean;
+    /** `gaon db migrate down` — 가장 최근 이력 한 건 롤백(§4.8). */
+    readonly down?: boolean;
 }
 /**
  * `gaon db <sub>` 진입점. 사람/JSON 출력을 자체 처리하고 exitCode 를

package/dist/commands/db.js

@@ -10,6 +10,7 @@
 import { runDbDiff } from '../db/diff.js';
 import { runDbMigrate } from '../db/migrate.js';
 import { runDbReset } from '../db/reset.js';
+import { runDbStatus } from '../db/status.js';
 import { runDbSeedCommand } from '../db.js';
 /**
  * `gaon db <sub>` 진입점. 사람/JSON 출력을 자체 처리하고 exitCode 를
@@ -34,7 +35,12 @@ export async function runDbCommand(subcommand, opts = {}) {
             return r.exitCode;
         }
         if (subcommand === 'migrate') {
-            const r = await runDbMigrate({ cwd, dbKey, json, dryRun, configPath });
+            const r = await runDbMigrate({ cwd, dbKey, json, dryRun, down: opts.down ?? false, configPath });
+            emit(r.text, r.json);
+            return r.exitCode;
+        }
+        if (subcommand === 'status') {
+            const r = await runDbStatus({ cwd, dbKey, json, configPath });
             emit(r.text, r.json);
             return r.exitCode;
         }
@@ -58,7 +64,7 @@ export async function runDbCommand(subcommand, opts = {}) {
         }
         // 방어 — dispatcher 라 도달할 수 없지만 컴파일러 만족용.
         process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${String(subcommand)}\n` +
-            `  → 지원: diff | migrate | reset | seed\n`);
+            `  → 지원: diff | migrate | reset | seed | status\n`);
         return 1;
     }
     catch (err) {

package/dist/commands/g.d.ts

@@ -1,5 +1,5 @@
 import { type ScaffoldFile, type WriteResult } from '../scaffold/index.js';
-export type GenerateType = 'controller' | 'model' | 'page' | 'job';
+export type GenerateType = 'controller' | 'model' | 'page' | 'job' | 'app';
 export interface GenerateOptions {
     readonly cwd?: string;
     readonly app?: string;

package/dist/commands/g.js

@@ -11,10 +11,12 @@
 //
 // 파일 위치는 프로젝트 관습(CLAUDE.md §2)을 따른다:
 //   controller → apps/<app>/controllers/<plural>.ts
-//   model      → domain/schema/<camel>.ts + domain/models/<camel>.ts
+//   model      → domain/schema/<posts>.ts + domain/models/<Post>.ts (§3.4: 스키마=테이블명 · 모델=Pascal)
 //   page       → apps/<app>/pages/<path>.vue
 //   job        → domain/jobs/<camel>.ts
-import { controllerScaffold, inflectModel, jobScaffold, modelScaffoldFiles, pageScaffold, writeScaffold, } from '../scaffold/index.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { appScaffoldFiles, controllerScaffold, inflectModel, jobScaffold, jobTestScaffold, modelScaffoldFiles, pageScaffold, writeScaffold, } from '../scaffold/index.js';
 /** argv 에서 옵션을 뽑는다(간단 파서 · runCli 관례와 일치). */
 export function parseGenerateArgs(argv) {
     const type = argv[0];
@@ -60,6 +62,10 @@ export function planScaffold(type, name, app) {
     if (type === 'page') {
         return [pageScaffold(name, app)];
     }
+    // app 은 이름 자체가 앱 폴더명이 되므로 '/' 는 허용하지 않는다(app.ts 재검증).
+    if (type === 'app') {
+        return appScaffoldFiles(name);
+    }
     if (name.includes('/')) {
         throw new Error(`${type} 이름에 '/' 는 사용할 수 없습니다: ${name}`);
     }
@@ -68,8 +74,9 @@ export function planScaffold(type, name, app) {
         return [controllerScaffold(names, app)];
     if (type === 'model')
         return modelScaffoldFiles(names);
+    // 잡은 통합 테스트 골격을 짝으로 생성한다 (결정 42 · expectJobProcessed).
     if (type === 'job')
-        return [jobScaffold(names.pascal)];
+        return [jobScaffold(names.pascal), jobTestScaffold(names.pascal)];
     throw new Error(`알 수 없는 제너레이터: ${type}`);
 }
 /** `gaon g <type> <name>` 실행. exitCode 를 반환한다(0=성공, 1=실패). */
@@ -90,6 +97,23 @@ export function runGenerateCommand(type, name, opts = {}) {
         }
         return 1;
     }
+    // gaon g app <name>: 앱 폴더가 이미 있으면 사고를 막기 위해 즉시 실패한다
+    // (--overwrite 로도 되돌리지 않는다 — 앱 재생성은 파괴적이라 사용자 판단
+    // 필요). 다른 스캐폴드는 파일 단위 skip 관례(Rails)를 그대로 유지.
+    if (type === 'app') {
+        const appDir = join(cwd, 'apps', name);
+        if (existsSync(appDir)) {
+            const msg = `앱 폴더가 이미 존재합니다: apps/${name}\n` +
+                `  → 다른 이름을 쓰거나 apps/${name} 을 수동으로 정리한 뒤 다시 실행하세요.`;
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+            }
+            else {
+                process.stderr.write(`  ✗ gaon g app: ${msg}\n`);
+            }
+            return 1;
+        }
+    }
     const write = writeScaffold(cwd, files, { overwrite: opts.overwrite });
     // overwrite 없이 기존 파일이 있으면 실패(사고 방지 · Rails 관례).
     const failed = write.skipped.length > 0;

package/dist/commands/mcp.d.ts

@@ -0,0 +1,15 @@
+export interface McpCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    /**
+     * 트랜스포트. v1 은 'stdio' 만. 미래 확장(http)을 위한 자리.
+     * 지금 'http' 를 주면 명확히 미지원 에러(§7.5.3 수리 안내).
+     */
+    readonly transport?: 'stdio' | 'http';
+    /** 서버 버전 문자열(파사드 gaonjs 가 주입). 미주입 시 'dev'. */
+    readonly version?: string;
+}
+/**
+ * `gaon mcp` 진입점. stdio transport 는 stdin close 까지 살아 있는다.
+ */
+export declare function runMcpCommand(opts?: McpCommandOptions): Promise<number>;