@gaonjs/cli 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,31 +1,40 @@
 /**
  * @gaonjs/cli — Gaon CLI 구현.
  *
- * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M3 부터
- * `gaon dev` 가 실제로 동작한다 — .gaon 타입 브리지(tables·routes)를
- * 감시·재생성한다(dev.ts). 모든 명령은 `--json` 출력을 함께 제공한다
- * (CLAUDE.md §4). 스캐폴딩·나머지 제너레이터는 이후 마일스톤이다.
+ * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M9-C 부터
+ * `gaon dev` 가 통합 개발 오케스트레이션을 담당한다 — Docker Compose
+ * 자동 기동 + .gaon 타입 브리지 재생성 + serve 자식 프로세스 + tsc/vue-tsc
+ * --watch + 소스 변경 시 서버 재시작(commands/dev.ts). 모든 명령은 `--json`
+ * 출력을 함께 제공한다 (CLAUDE.md §4).
  *
  * 표시 버전은 호출자(파사드)가 주입한다 — 사용자가 설치한 패키지
  * (`gaonjs`) 버전을 그대로 보여주기 위함. 미주입 시 core 버전을 쓴다.
  */
 import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
-import { runDevCommand } from "./dev.js";
+import { runDevCommand } from "./commands/dev.js";
 import { runCheckCommand } from "./check.js";
 import { runGenerateAuthCommand } from "./generate.js";
+import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
+import { runServeCommand } from "./serve.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
-import { runDbSeedCommand } from "./db.js";
+import { runDbCommand } from "./commands/db.js";
 import { runDoctorCommand } from "./doctor.js";
-export { runDevCommand, startDev, resolveDevLayout, } from "./dev.js";
+export { startDev, resolveDevLayout, } from "./dev.js";
+export { runDevCommand } from "./commands/dev.js";
+export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, } from "./dev/index.js";
 export { runCheck, runCheckCommand, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
+export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
+export { runServeCommand } from "./serve.js";
 export { runWorkCommand } from "./work.js";
 export { runJobsCommand } from "./jobs.js";
 export { runDbSeedCommand, loadSeed } from "./db.js";
-export { runDoctorCommand, runDoctor, inspectControllerSource, } from "./doctor.js";
+export { runDbCommand, } from "./commands/db.js";
+export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, } from "./db/index.js";
+export { runDoctorCommand, runDoctor, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
 export { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
 export function roadmapReport(version = VERSION) {
@@ -70,15 +79,32 @@ function renderHelp(version = VERSION) {
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
-        "    gaon dev           .gaon 타입 브리지를 감시·재생성 (스키마·라우트)",
-        "    gaon dev --json    재생성 이벤트를 JSON 으로 출력",
+        "    gaon dev           개발 스택 통합 (Docker · .gaon · serve · tsc/vue-tsc · 재시작 워처)",
+        "    gaon dev --stop-docker  Ctrl+C 시 Docker Compose 도 down",
+        "    gaon dev --no-watch|--no-tsc|--no-vue-tsc|--no-docker  개별 debug 옵션",
+        "    gaon dev --port <n> --host <h>  serve 리슨 지정",
+        "    gaon dev --json    통합 콘솔을 JSON 라인으로 출력(자동화)",
+        "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
+        "    gaon serve --port <n> --host <h>   리슨 포트·호스트 (config 값을 덮음)",
         "    gaon check         .gaon 재생성 후 타입 검사 (CI·AI 정합)",
-        "    gaon doctor        정적 검사 (응답 혼용·의존 방향 등)",
+        "    gaon doctor        정적 검사 (5 검사 · 응답 혼용·N+1·의존 방향·커넥션·마이그)",
+        "    gaon doctor --json                        자동화용 JSON 출력",
+        "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
+        "    gaon g controller <name>   컨트롤러 스캐폴드 (Rails 관례 · 페이지+JSON 액션)",
+        "    gaon g model <Name>        모델 스캐폴드 (스키마+모델 · E-4 컬럼 예시)",
+        "    gaon g page <Path/Name>    Vue 페이지 (Inertia SPA · pageProps 브리지)",
+        "    gaon g job <Name>          비동기 잡 (domain/jobs · later/in/at)",
+        "    gaon g <type> --overwrite  기존 파일 덮어쓰기 · --app <이름> · --json",
         "    gaon hub           실시간 허브 프로세스 (프레즌스 권위·중계 · 리더 선출 HA)",
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
         "    gaon jobs list --failed   DLQ(실패 잡) 목록",
         "    gaon jobs retry <id>      DLQ 잡 재적재",
+        "    gaon db diff              스키마 ↔ DB 차이 계산 (적용 X · --json · --db <키>)",
+        "    gaon db migrate           스키마 변경을 실제 적용 + _gaon_migrations 이력",
+        "    gaon db migrate --dry-run 적용 없이 up SQL 만 출력",
+        "    gaon db reset --yes       DROP ALL → 재마이그 → seed (--yes 필수 · production 거부)",
+        "    gaon db seed              domain/seed.ts 실행 (M8)",
         "    gaon --json        같은 정보를 JSON 으로 출력",
         "    gaon --version     버전 출력",
         "    gaon --help        이 도움말",
@@ -87,19 +113,72 @@ function renderHelp(version = VERSION) {
         "",
     ].join("\n");
 }
+/**
+ * `gaon doctor --check=<이름>[,<이름>...]` 파싱(M9-E).
+ * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
+ */
+export function parseDoctorChecks(argv) {
+    const known = [
+        "response-mixing",
+        "n-plus-one",
+        "dependency-direction",
+        "connections",
+        "migration-diff",
+    ];
+    const isKnown = (s) => known.includes(s);
+    const out = [];
+    for (const a of argv) {
+        if (a.startsWith("--check=")) {
+            for (const nm of a.slice("--check=".length).split(",")) {
+                if (isKnown(nm) && !out.includes(nm))
+                    out.push(nm);
+            }
+        }
+    }
+    return out.length ? out : undefined;
+}
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
-    // `gaon dev` — .gaon 갱신 파이프라인(장기 실행). 워처가 활성 핸들로
-    // 프로세스를 살려 두고, SIGINT 로 종료된다. 에러는 stderr + exit 1.
+    // `gaon dev` — 통합 개발 오케스트레이션(M9-C · v0.15 §13.5). Docker Compose
+    // 자동 기동 + .gaon 재생성 + serve 자식 + tsc/vue-tsc watch + 서버 재시작 워처.
+    // SIGINT/SIGTERM 시 순서대로 정리(serve → tsc → 워처 → Docker[--stop-docker 시]).
+    // 개별 debug 옵션은 --no-watch / --no-tsc / --no-vue-tsc / --no-docker 뿐.
     if (argv[0] === "dev") {
-        void runDevCommand({ json: argv.includes("--json") }).catch((err) => {
+        const portIdx = argv.indexOf("--port");
+        const hostIdx = argv.indexOf("--host");
+        const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
+        const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+        void runDevCommand({
+            json: argv.includes("--json"),
+            stopDocker: argv.includes("--stop-docker"),
+            noWatch: argv.includes("--no-watch"),
+            noTsc: argv.includes("--no-tsc"),
+            noVueTsc: argv.includes("--no-vue-tsc"),
+            noDocker: argv.includes("--no-docker"),
+            timestamp: argv.includes("--timestamp"),
+            port,
+            host,
+        }).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon dev 실패: ${msg}\n`);
             process.exitCode = 1;
         });
         return;
     }
+    // `gaon serve` — 웹 서버 부팅(§7 · M9-A). gaon.config.ts 자동 배선 후 listen.
+    if (argv[0] === "serve") {
+        const portIdx = argv.indexOf("--port");
+        const hostIdx = argv.indexOf("--host");
+        const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
+        const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+        void runServeCommand({ json: argv.includes("--json"), port, host }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon check` — .gaon 재생성 후 타입 검사(§13.4-5). 종료 코드로 결과 전달.
     if (argv[0] === "check") {
         void runCheckCommand({ json: argv.includes("--json") })
@@ -113,11 +192,18 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(응답 혼용 등 · errata E-3 §C). --fix 는 후속.
+    // `gaon doctor` — 정적 검사(M9-E · 5 검사). --check=<이름>[,<이름>...] 로
+    // 선택 실행, --json 은 자동화 파싱용.
+    // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
-        void runDoctorCommand({ json: argv.includes("--json") })
-            .then((code) => {
-            process.exitCode = code;
+        const checks = parseDoctorChecks(argv);
+        void runDoctorCommand({ json: argv.includes("--json"), checks })
+            .then((result) => {
+            if (result.fatal) {
+                process.exitCode = 2;
+                return;
+            }
+            process.exitCode = result.errors.length > 0 ? 1 : 0;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -159,22 +245,40 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon db seed` — domain/seed.ts 실행(§7 M8). diff·migrate 는 M9 CLI 완성.
-    if (argv[0] === "db" && argv[1] === "seed") {
-        const json = argv.includes("--json");
-        void runDbSeedCommand({ json })
-            .then((res) => {
-            process.stdout.write((json ? JSON.stringify(res.json) : res.text) + "\n");
-            process.exitCode = res.exitCode;
+    // `gaon db <sub>` — diff · migrate · reset · seed (§7 M8/M9-D).
+    if (argv[0] === "db") {
+        const sub = argv[1];
+        const known = ["diff", "migrate", "reset", "seed"];
+        if (!sub || !known.includes(sub)) {
+            process.stderr.write(`  ✗ 알 수 없는 db 서브커맨드: ${sub ?? "(없음)"}\n` +
+                `  → 지원: gaon db diff | migrate | reset | seed\n` +
+                `  → 옵션: --json · --db <키> · --config <path> · --yes · --dry-run\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const dbIdx = argv.indexOf("--db");
+        const cfgIdx = argv.indexOf("--config");
+        const dbOpts = {
+            json: argv.includes("--json"),
+            db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
+            config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
+            yes: argv.includes("--yes"),
+            dryRun: argv.includes("--dry-run"),
+        };
+        void runDbCommand(sub, dbOpts)
+            .then((code) => {
+            process.exitCode = code;
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`  ✗ gaon db seed 실패: ${msg}\n`);
+            process.stderr.write(`  ✗ gaon db ${sub} 실패: ${msg}\n`);
             process.exitCode = 1;
         });
         return;
     }
-    // `gaon g auth` — 인증 스캐폴드 제너레이터(§7 M5). 다른 제너레이터는 후속.
+    // `gaon g <type> <name>` — 스캐폴드(§7 M5·M9-B).
+    //  · auth 는 인증 스캐폴드(별도 진입점)
+    //  · controller/model/page/job 은 M9-B 통합 라우터
     if (argv[0] === "g" || argv[0] === "generate") {
         if (argv[1] === "auth") {
             const appIdx = argv.indexOf("--app");
@@ -183,8 +287,47 @@ export function runCli(argv, opts = {}) {
             process.exitCode = code;
             return;
         }
+        const known = ["controller", "model", "page", "job"];
+        const type = argv[1];
+        if (type && known.includes(type)) {
+            const rest = argv.slice(2);
+            // name = 첫 위치 인자(--플래그 제외 · --app <v> 스킵)
+            let name;
+            let app;
+            let overwrite = false;
+            let json = false;
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "--json") {
+                    json = true;
+                    continue;
+                }
+                if (a === "--overwrite") {
+                    overwrite = true;
+                    continue;
+                }
+                if (a === "--app") {
+                    app = rest[++i];
+                    continue;
+                }
+                if (a?.startsWith("--"))
+                    continue;
+                if (name === undefined)
+                    name = a;
+            }
+            if (!name) {
+                process.stderr.write(`  ✗ gaon g ${type}: 이름이 없습니다.\n` +
+                    `  → 예: gaon g ${type} ${type === "page" ? "Posts/Index" : "Post"}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const code = runGenerateCommand(type, name, { app, overwrite, json });
+            process.exitCode = code;
+            return;
+        }
         process.stderr.write(`  ✗ 알 수 없는 제너레이터: ${argv[1] ?? "(없음)"}\n` +
-            `  → 현재 지원: gaon g auth [--app <이름>]\n`);
+            `  → 현재 지원: gaon g auth | controller | model | page | job\n` +
+            `  → 옵션: --app <이름> · --overwrite · --json\n`);
         process.exitCode = 1;
         return;
     }

package/dist/scaffold/controller.d.ts

@@ -0,0 +1,12 @@
+import type { ModelNames } from './inflect.js';
+/** 스캐폴드가 만들 파일 하나 — path 는 프로젝트 루트 기준 상대 경로. */
+export interface ScaffoldFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/**
+ * 컨트롤러 스캐폴드 파일을 만든다.
+ * @param names 이름 변형(카멜/파스칼/복수) — inflect() 결과.
+ * @param app 대상 앱 폴더(apps/<app>/).
+ */
+export declare function controllerScaffold(names: ModelNames, app: string): ScaffoldFile;

package/dist/scaffold/controller.js

@@ -0,0 +1,50 @@
+// @gaonjs/cli · scaffold · controller (M9-B)
+//
+// `gaon g controller <name>` — Rails 관례의 컨트롤러 스캐폴드.
+// 페이지 액션(this.render)과 JSON 액션(반환값=응답 · errata E-3) 두 예시를
+// 함께 담는다 — 실 프로젝트에서 가장 자주 쓰는 두 패턴이라 첫 코드에서
+// 노출하는 편이 AI/사람 첫 시도 성공률에 유리하다.
+//
+// 응답 혼용 주의: 한 컨트롤러 안에서 페이지 액션과 JSON 액션을 섞는 것은
+// doctor 가 경고한다(errata E-3 §C). 스캐폴드는 이유를 주석으로 남기고,
+// 규모가 커지면 분리하도록 안내한다.
+//
+// 모델 참조: apps/<app>/controllers/*.ts → domain/models/*.ts. 프로젝트 관습
+// (CLAUDE.md §2): 모델·잡은 domain/ 아래 두어 앱 간 재사용을 허용한다
+// (apps→apps 금지 · rule 5).
+/**
+ * 컨트롤러 스캐폴드 파일을 만든다.
+ * @param names 이름 변형(카멜/파스칼/복수) — inflect() 결과.
+ * @param app 대상 앱 폴더(apps/<app>/).
+ */
+export function controllerScaffold(names, app) {
+    const { pascal, camel, plural } = names;
+    const lines = [
+        `// ${plural} 컨트롤러 — gaon g controller (M9-B).`,
+        `// 페이지 액션(this.render)과 JSON 액션(반환값=응답 · errata E-3) 예시를 담는다.`,
+        `// 응답 종류를 한 컨트롤러에서 섞으면 doctor 가 경고한다(§C) — 규모가 커지면 분리.`,
+        `import { controller } from 'gaonjs/web'`,
+        `import { ${pascal} } from '../../../domain/models/${camel}.js'`,
+        ``,
+        `export default controller({`,
+        `  // GET /${plural} — 목록 페이지 (Inertia render).`,
+        `  // E-4 체이닝 예시: orderBy · limit · all.`,
+        `  async index() {`,
+        `    const items = await ${pascal}.orderBy('createdAt', 'desc').limit(20).all()`,
+        `    return this.render('${pascal}/Index', { items })`,
+        `  },`,
+        ``,
+        `  // GET /${plural}/count.json — JSON 액션 (errata E-3).`,
+        `  // 반환값 = 응답. api('${plural}#count') 클라이언트가 Serialized<> 로 받는다.`,
+        `  // this.params() 안전 규칙: 라우트 > body > query (errata E-3 §5.1).`,
+        `  async count() {`,
+        `    return { total: await ${pascal}.count() }`,
+        `  },`,
+        `})`,
+        ``,
+    ];
+    return {
+        path: `apps/${app}/controllers/${plural}.ts`,
+        contents: lines.join('\n'),
+    };
+}

package/dist/scaffold/index.d.ts

@@ -0,0 +1,20 @@
+export type { ScaffoldFile } from './controller.js';
+export { controllerScaffold } from './controller.js';
+export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
+export { pageScaffold } from './page.js';
+export { jobScaffold } from './job.js';
+export { inflectModel, toCamel, toPascal, singularize, pluralize, type ModelNames, } from './inflect.js';
+import type { ScaffoldFile } from './controller.js';
+export interface WriteResult {
+    readonly created: string[];
+    readonly overwritten: string[];
+    /** overwrite=false 로 스킵된 기존 파일. */
+    readonly skipped: string[];
+}
+/**
+ * 파일 계획을 실제로 쓴다. 기본은 기존 파일 skip(멱등 · 사고 방지).
+ * overwrite=true 이면 덮어쓴다(기존 파일 목록을 overwritten 에 반환).
+ */
+export declare function writeScaffold(cwd: string, files: readonly ScaffoldFile[], opts?: {
+    overwrite?: boolean;
+}): WriteResult;

package/dist/scaffold/index.js

@@ -0,0 +1,41 @@
+// @gaonjs/cli · scaffold · public export (M9-B)
+//
+// `gaon g <type> <name>` 스캐폴드 진입점 모음. runCli 가 여기서 팩토리를
+// 골라 파일을 쓴다. 각 팩토리는 순수 함수 — 디스크 접근 없이 파일 계획을
+// 반환한다. 실제 쓰기는 writeScaffold 가 담당(멱등·overwrite 옵션 처리).
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export { controllerScaffold } from './controller.js';
+export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
+export { pageScaffold } from './page.js';
+export { jobScaffold } from './job.js';
+export { inflectModel, toCamel, toPascal, singularize, pluralize, } from './inflect.js';
+/**
+ * 파일 계획을 실제로 쓴다. 기본은 기존 파일 skip(멱등 · 사고 방지).
+ * overwrite=true 이면 덮어쓴다(기존 파일 목록을 overwritten 에 반환).
+ */
+export function writeScaffold(cwd, files, opts = {}) {
+    const root = resolve(cwd);
+    const created = [];
+    const overwritten = [];
+    const skipped = [];
+    for (const file of files) {
+        const abs = join(root, file.path);
+        const exists = existsSync(abs);
+        if (exists && !opts.overwrite) {
+            skipped.push(file.path);
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, file.contents, 'utf8');
+        if (exists)
+            overwritten.push(file.path);
+        else
+            created.push(file.path);
+    }
+    return {
+        created: created.sort(),
+        overwritten: overwritten.sort(),
+        skipped: skipped.sort(),
+    };
+}

package/dist/scaffold/inflect.d.ts

@@ -0,0 +1,19 @@
+/** 파스칼케이스 → 카멜케이스 (`Post` → `post`, `SendEmail` → `sendEmail`). */
+export declare function toCamel(s: string): string;
+/** 카멜/스네이크/케밥 → 파스칼케이스 (`post` → `Post`, `send_email` → `SendEmail`). */
+export declare function toPascal(s: string): string;
+/** 단순 단수화 — 끝의 s 하나만 벗긴다 ('users' → 'user' · 'ss' 는 유지). */
+export declare function singularize(s: string): string;
+/** 단순 복수화 — 끝에 s 를 붙인다 ('user' → 'users' · 이미 s 로 끝나면 유지). */
+export declare function pluralize(s: string): string;
+/** 모델 이름 · 표준 변형 묶음. 스캐폴드가 파일명·클래스명·테이블명에 쓴다. */
+export interface ModelNames {
+    /** 파스칼 단수 — 클래스/const 명 (`Post`). */
+    readonly pascal: string;
+    /** 카멜 단수 — 파일 stem·변수명 (`post`). */
+    readonly camel: string;
+    /** 카멜 복수 — 테이블명·경로 (`posts`). */
+    readonly plural: string;
+}
+/** 사용자 입력(어느 형태든)에서 세 가지 변형을 파생한다. */
+export declare function inflectModel(input: string): ModelNames;

package/dist/scaffold/inflect.js

@@ -0,0 +1,50 @@
+// @gaonjs/cli · scaffold · 이름 변환 헬퍼 (M9-B)
+//
+// Rails 관례: 사용자가 아무 형태(Post·post·Posts·posts)로 넣어도 스캐폴드가
+// 필요한 변형(파일명·클래스명·테이블명)을 일관되게 뽑는다. 완벽한 영어
+// 복수형 규칙(children/geese …)은 v1 범위 밖 — 기본 규칙(s 추가/삭제)만
+// 다룬다. 예외가 필요하면 사용자가 --table/--singular 로 덮어쓸 수 있다
+// (v1.1 계획 · 현재는 기본 규칙만).
+/** 파스칼케이스 → 카멜케이스 (`Post` → `post`, `SendEmail` → `sendEmail`). */
+export function toCamel(s) {
+    if (!s)
+        return s;
+    return s.charAt(0).toLowerCase() + s.slice(1);
+}
+/** 카멜/스네이크/케밥 → 파스칼케이스 (`post` → `Post`, `send_email` → `SendEmail`). */
+export function toPascal(s) {
+    if (!s)
+        return s;
+    return s
+        .split(/[_\-\s]+/)
+        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
+        .join('');
+}
+/** 단순 단수화 — 끝의 s 하나만 벗긴다 ('users' → 'user' · 'ss' 는 유지). */
+export function singularize(s) {
+    if (s.endsWith('ies') && s.length > 3)
+        return s.slice(0, -3) + 'y';
+    if (s.endsWith('ss'))
+        return s;
+    if (s.endsWith('s') && s.length > 1)
+        return s.slice(0, -1);
+    return s;
+}
+/** 단순 복수화 — 끝에 s 를 붙인다 ('user' → 'users' · 이미 s 로 끝나면 유지). */
+export function pluralize(s) {
+    if (s.endsWith('s'))
+        return s;
+    if (s.endsWith('y') && s.length > 1 && !'aeiou'.includes(s[s.length - 2])) {
+        return s.slice(0, -1) + 'ies';
+    }
+    return s + 's';
+}
+/** 사용자 입력(어느 형태든)에서 세 가지 변형을 파생한다. */
+export function inflectModel(input) {
+    const trimmed = input.trim();
+    const singular = singularize(toCamel(toPascal(trimmed)));
+    const pascal = toPascal(singular);
+    const camel = toCamel(pascal);
+    const plural = pluralize(camel);
+    return { pascal, camel, plural };
+}

package/dist/scaffold/job.d.ts

@@ -0,0 +1,3 @@
+import type { ScaffoldFile } from './controller.js';
+/** 잡 이름(파스칼) → 파일·잡명 파생. */
+export declare function jobScaffold(pascalName: string): ScaffoldFile;

package/dist/scaffold/job.js

@@ -0,0 +1,46 @@
+// @gaonjs/cli · scaffold · job (M9-B)
+//
+// `gaon g job <Name>` — 비동기 잡 스캐폴드(§7 M7). domain/jobs/<name>.ts 에
+// 두면 워커가 자동 로드·등록한다(파일 로더가 assignName 으로 이름 채움).
+//
+// 파일 위치 (CLAUDE.md §2 · rule 5): 잡은 domain/jobs/ 아래 둔다 —
+// 여러 앱이 같은 잡을 예약/실행할 수 있어야 하고, 앱→앱 import 는 금지다.
+//
+// 사용 예:
+//   import send${Pascal} from '../../domain/jobs/${camel}.js'
+//   await send${Pascal}.later({ id: 'abc' })     // 즉시 큐 적재
+//   await send${Pascal}.in('5m', { id: 'abc' })  // 5분 지연 후 실행
+//   await send${Pascal}.at(new Date(...), args)  // 특정 시각 실행
+/** 잡 이름(파스칼) → 파일·잡명 파생. */
+export function jobScaffold(pascalName) {
+    const trimmed = pascalName.trim();
+    if (!trimmed) {
+        throw new Error(`[gaon g job] 잡 이름이 비어 있습니다. 예: gaon g job SendEmail`);
+    }
+    // 파스칼 정규화(사용자가 send_email/sendEmail 로 넣어도 동작)
+    const pascal = trimmed
+        .split(/[_\-\s]+/)
+        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
+        .join('');
+    const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    const lines = [
+        `// ${pascal} 잡 — gaon g job (M9-B).`,
+        `// 반환값을 export 하면 워커가 자동 등록한다(§7). 이름은 { name } 옵션이 우선,`,
+        `// 없으면 파일명에서 채워진다(파일 로더 assignName).`,
+        `//`,
+        `// 실행:`,
+        `//   import ${camel} from '../../domain/jobs/${camel}.js'`,
+        `//   await ${camel}.later({ id: 'abc' })       // 즉시 큐 적재`,
+        `//   await ${camel}.in('5m', { id: 'abc' })    // 5분 지연 후 실행`,
+        `//   await ${camel}.at(new Date(...), payload) // 특정 시각 실행`,
+        `import { job } from 'gaonjs/async'`,
+        ``,
+        `export default job(async (payload: { id: string }) => {`,
+        `  // 실 로직을 여기에.`,
+        `  // 예: const record = await SomeModel.where('id', '=', payload.id).first()`,
+        `  console.log('[${pascal}] 실행:', payload.id)`,
+        `}, { name: '${camel}' })`,
+        ``,
+    ];
+    return { path: `domain/jobs/${camel}.ts`, contents: lines.join('\n') };
+}

package/dist/scaffold/model.d.ts

@@ -0,0 +1,8 @@
+import type { ScaffoldFile } from './controller.js';
+import type { ModelNames } from './inflect.js';
+/** 스키마 스캐폴드 — E-4 컬럼 타입 예시를 함께 담는다. */
+export declare function schemaScaffold(names: ModelNames): ScaffoldFile;
+/** 모델 스캐폴드 — scopes 예시를 담는다(체이닝 진입점 도우미). */
+export declare function modelScaffold(names: ModelNames): ScaffoldFile;
+/** 모델 스캐폴드 = 스키마 + 모델 두 파일. */
+export declare function modelScaffoldFiles(names: ModelNames): ScaffoldFile[];

package/dist/scaffold/model.js

@@ -0,0 +1,66 @@
+// @gaonjs/cli · scaffold · model (M9-B)
+//
+// `gaon g model <Name>` — 스키마 + 모델 두 파일을 함께 만든다.
+// 스키마는 errata E-4 신규 컬럼 타입(decimal · enum · uuid)과 수식어(unique ·
+// nullable · default) 예시를 담아 새 개발자가 바로 참고할 수 있게 한다.
+//
+// 파일 위치 (CLAUDE.md §2 · rule 5):
+//  · 스키마 → domain/schema/<name>.ts (테이블 정의 · tables.d.ts 원천)
+//  · 모델   → domain/models/<name>.ts (Active Record · scopes/methods)
+// 앱→도메인 import 만 허용되므로 이 위치가 유일한 정답이다.
+/** 스키마 스캐폴드 — E-4 컬럼 타입 예시를 함께 담는다. */
+export function schemaScaffold(names) {
+    const { pascal, camel, plural } = names;
+    const lines = [
+        `// ${pascal} 스키마 — gaon g model (M9-B).`,
+        `// errata E-4 예시: unique · default · enum · nullable. 컬럼은 자유롭게 추가/삭제한다.`,
+        `// .gaon/tables.d.ts 가 자동 재생성돼 모델·컨트롤러·페이지 전 체인이 즉시 반영된다(§6.3).`,
+        `import { table, t, type RowOf } from 'gaonjs/data'`,
+        ``,
+        `export const ${plural} = table('${plural}', {`,
+        `  id: t.id(),`,
+        `  title: t.string().max(200).unique(),`,
+        `  status: t.enum(['draft', 'published']).default('draft'),`,
+        `  ...t.timestamps(),`,
+        `})`,
+        ``,
+        `// tables.d.ts 자동 재생성 전(dev 서버 미기동)이라도 이 augmentation 이 있으면`,
+        `// 모델·컨트롤러에서 즉시 참조 가능하다. 재생성 후에는 이 블록이 중복돼도 무해하다.`,
+        `declare module 'gaonjs/data' {`,
+        `  interface GaonTables {`,
+        `    ${plural}: RowOf<typeof ${plural}>`,
+        `  }`,
+        `}`,
+        ``,
+    ];
+    return {
+        path: `domain/schema/${camel}.ts`,
+        contents: lines.join('\n'),
+    };
+}
+/** 모델 스캐폴드 — scopes 예시를 담는다(체이닝 진입점 도우미). */
+export function modelScaffold(names) {
+    const { pascal, camel, plural } = names;
+    const lines = [
+        `// ${pascal} 모델 — gaon g model (M9-B).`,
+        `// scopes 는 체인 어느 지점에서든 호출 가능하다(§4.4). E-4 체이닝 예시:`,
+        `//   ${pascal}.published().orderBy('createdAt', 'desc').limit(20).all()`,
+        `import { model } from 'gaonjs/data'`,
+        `import { ${plural} } from '../schema/${camel}.js'`,
+        ``,
+        `export const ${pascal} = model(${plural}, {`,
+        `  scopes: {`,
+        `    published: (q) => q.where('status', '=', 'published'),`,
+        `  },`,
+        `})`,
+        ``,
+    ];
+    return {
+        path: `domain/models/${camel}.ts`,
+        contents: lines.join('\n'),
+    };
+}
+/** 모델 스캐폴드 = 스키마 + 모델 두 파일. */
+export function modelScaffoldFiles(names) {
+    return [schemaScaffold(names), modelScaffold(names)];
+}

package/dist/scaffold/page.d.ts

@@ -0,0 +1,7 @@
+import type { ScaffoldFile } from './controller.js';
+/**
+ * 페이지 경로에서 스캐폴드를 만든다.
+ * @param pagePath 예: 'Posts/Index' · 'Dashboard' · 'admin/Users/Show'.
+ * @param app 대상 앱.
+ */
+export declare function pageScaffold(pagePath: string, app: string): ScaffoldFile;