@gaonjs/cli 0.2.0 → 0.3.0

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;

package/dist/scaffold/page.js

@@ -0,0 +1,46 @@
+// @gaonjs/cli · scaffold · page (M9-B)
+//
+// `gaon g page <Path>/<Name>` — Vue 페이지(Inertia SPA · §6).
+// pageProps<K>() 로 컨트롤러 render 결과 타입을 그대로 이어받는다 —
+// 스키마→모델→컨트롤러→(생성된 라우트 지도)→페이지 체인의 마지막 고리(§6.2).
+//
+// 입력 예: `gaon g page Posts/Index` → apps/<app>/pages/Posts/Index.vue.
+// 라우트 키는 소문자·리소스 관례로 `posts#index` 를 기본값으로 넣는다 —
+// 사용자가 라우트를 다르게 걸었으면 수동 수정하면 된다(주석에 안내).
+import { toCamel } from './inflect.js';
+/**
+ * 페이지 경로에서 스캐폴드를 만든다.
+ * @param pagePath 예: 'Posts/Index' · 'Dashboard' · 'admin/Users/Show'.
+ * @param app 대상 앱.
+ */
+export function pageScaffold(pagePath, app) {
+    const trimmed = pagePath.trim().replace(/^\/+|\/+$/g, '');
+    if (!trimmed) {
+        throw new Error(`[gaon g page] 페이지 경로가 비어 있습니다.\n` +
+            `  → 예: gaon g page Posts/Index (apps/${app}/pages/Posts/Index.vue 생성)`);
+    }
+    const segments = trimmed.split('/').filter(Boolean);
+    const last = segments[segments.length - 1];
+    const parent = segments[segments.length - 2] ?? last;
+    // 라우트 키 기본값 — 폴더는 리소스명(복수·소문자), 파일은 액션명(소문자).
+    const routeKey = `${toCamel(parent).toLowerCase()}#${toCamel(last).toLowerCase()}`;
+    const filePath = `apps/${app}/pages/${trimmed}.vue`;
+    const lines = [
+        `<script setup lang="ts">`,
+        `import { pageProps } from 'gaonjs/vue'`,
+        ``,
+        `// 컨트롤러 ${routeKey} 의 render props 타입이 그대로 흐른다(§6.2).`,
+        `// 라우트 키가 다르면 이 리터럴을 바꾼다 — .gaon/routes.d.ts 가 유효한 키를 알려준다.`,
+        `const props = pageProps<'${routeKey}'>()`,
+        `</script>`,
+        ``,
+        `<template>`,
+        `  <div>`,
+        `    <h1>${last}</h1>`,
+        `    <pre>{{ props }}</pre>`,
+        `  </div>`,
+        `</template>`,
+        ``,
+    ];
+    return { path: filePath, contents: lines.join('\n') };
+}

package/dist/serve.d.ts

@@ -0,0 +1,18 @@
+export interface ServeCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    /** 리슨 포트. 우선순위: 옵션 > config.web.port > env PORT > 3000. */
+    readonly port?: number;
+    /** 리슨 호스트. 우선순위: 옵션 > config.web.host > '0.0.0.0'. */
+    readonly host?: string;
+    /** 프로세스 시그널(테스트 주입). 기본 process. */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * `gaon serve` 진입점. loadDotEnv → loadGaonConfig → wireGaon → listen →
+ * SIGINT 대기 → graceful close. 예외는 stderr + exit 1.
+ */
+export declare function runServeCommand(opts?: ServeCommandOptions): Promise<void>;

package/dist/serve.js

@@ -0,0 +1,79 @@
+/**
+ * @gaonjs/cli · `gaon serve` — 웹 서버 부팅 (§7 · M9-A)
+ *
+ * 운영 프로세스 3종 중 하나(serve · work · hub). cwd 관례로 gaon.config.ts
+ * 를 로드하고, apps/* 를 스캔해 자동 배선한 뒤 Fastify 를 listen 한다.
+ * SIGINT/SIGTERM 에 graceful 종료(Fastify → NATS → Redis → DB 순).
+ *
+ * env 를 먼저 로드한다 — .env 의 값이 gaon.config.ts 안의 env('KEY') 에
+ * 들어갈 수 있어야 하기 때문.
+ *
+ * 워커 수(--workers, WEB_CONCURRENCY)는 v0.8 정본이지만 컨테이너 안 기본
+ * 1워커라 M9-A 는 단일 프로세스만 다룬다. node:cluster 통합은 후속(M9-C).
+ */
+import { loadDotEnv } from '@gaonjs/core';
+import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
+import { registerTsResolve } from './tsResolve.js';
+function humanEvent(e) {
+    switch (e.kind) {
+        case 'starting': {
+            const cfg = e.configPath ? `config=${e.configPath}` : 'config=(없음 · 기본값)';
+            const apps = e.apps.length > 0 ? `apps=[${e.apps.join(', ')}]` : 'apps=(없음)';
+            return `  gaon serve · 시작 — ${cfg} · ${apps}`;
+        }
+        case 'listening':
+            return `  ▶ 리슨 중 — ${e.url}  (Ctrl+C 로 종료)`;
+        case 'stopping':
+            return '  gaon serve · 종료 중 (graceful) ...';
+        case 'stopped':
+            return '  gaon serve · 종료';
+    }
+}
+/**
+ * `gaon serve` 진입점. loadDotEnv → loadGaonConfig → wireGaon → listen →
+ * SIGINT 대기 → graceful close. 예외는 stderr + exit 1.
+ */
+export async function runServeCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const signals = opts.signals ?? process;
+    // .ts 상대 import 해석기 등록 (사용자 gaon.config.ts, apps/* 로드에 필요).
+    registerTsResolve();
+    loadDotEnv(cwd);
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    const configPath = findConfigPath(cwd);
+    const config = await loadGaonConfig(cwd);
+    const wired = await wireGaon(config, cwd);
+    emit({ kind: 'starting', configPath, apps: wired.apps.map((a) => a.name) });
+    const host = opts.host ?? config.web?.host ?? '0.0.0.0';
+    const port = opts.port ??
+        config.web?.port ??
+        (process.env.PORT ? Number(process.env.PORT) : 3000);
+    await wired.app.listen({ host, port });
+    const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+    emit({ kind: 'listening', host, port, url: `http://${displayHost}:${port}` });
+    await new Promise((resolvePromise) => {
+        const stop = () => {
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            emit({ kind: 'stopping' });
+            void wired
+                .close()
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`  ✗ 종료 중 오류: ${msg}\n`);
+            })
+                .finally(() => {
+                emit({ kind: 'stopped' });
+                resolvePromise();
+            });
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}

package/dist/templates/auth/auth.wiring.ts.tpl

@@ -4,7 +4,7 @@ import { User } from '../../domain/models/user.js'
 
 // 세션에 심긴 userId 로 사용자를 로드한다(§7). web 은 도메인을 loadUser 로 받는다.
 export const loadUser: AuthOptions['loadUser'] = async (id) =>
-  await User.query().where('id', '=', BigInt(String(id))).first()
+  await User.where('id', '=', BigInt(String(id))).first()
 
 // this.currentUser 에 User 필드 타입을 얹는다(GaonRouteMap 과 동일 관례).
 declare module 'gaonjs/web' {

package/dist/templates/auth/session.controller.ts.tpl

@@ -10,7 +10,7 @@ export default controller({
   // POST /session — 로그인
   async create() {
     const { email, password } = this.params({ _row: {} as { email: string; password: string } })
-    const user = await User.query().where('email', '=', email).first()
+    const user = await User.where('email', '=', email).first()
     // passwordDigest 는 hidden 이지만 서버 코드에서는 투명하게 읽힌다(§4.2).
     if (user && (await verifyPassword(password, user.passwordDigest))) {
       this.auth.login(user)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -25,11 +25,12 @@
   ],
   "dependencies": {
     "typescript": "*",
+    "@gaonjs/config": "0.1.0",
     "@gaonjs/async": "0.2.2",
     "@gaonjs/core": "0.1.4",
-    "@gaonjs/data": "0.2.3",
-    "@gaonjs/mail": "0.1.0",
-    "@gaonjs/web": "0.3.0"
+    "@gaonjs/data": "0.3.0",
+    "@gaonjs/web": "0.3.0",
+    "@gaonjs/mail": "0.1.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""