@gaonjs/cli 0.1.7 → 0.2.0

package/dist/db.d.ts

@@ -0,0 +1,20 @@
+import { type SeedDef } from '@gaonjs/data';
+export interface DbSeedOptions {
+    readonly json?: boolean;
+    /** 도메인 루트(domain/ 의 부모). 기본 cwd. */
+    readonly root?: string;
+    /** DB URL 오버라이드. 생략 시 env GAON_DATABASE_URL. */
+    readonly databaseUrl?: string;
+}
+/** domain/seed.ts 의 default export 를 읽어 SeedDef 를 돌려준다(없으면 안내 에러). */
+export declare function loadSeed(root: string): Promise<SeedDef>;
+export interface DbSeedResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: unknown;
+}
+/**
+ * `gaon db seed` — main 커넥션을 연결하고 domain/seed.ts 를 실행한다.
+ * 커넥션 정리(destroyAllConnections)는 항상 수행한다.
+ */
+export declare function runDbSeedCommand(opts?: DbSeedOptions): Promise<DbSeedResult>;

package/dist/db.js

@@ -0,0 +1,62 @@
+// @gaonjs/cli · `gaon db seed` (§7 M8 — domain/seed.ts 실행)
+//
+// 관례: `domain/seed.ts` 의 default export(seed 정의)를 실행한다. 커넥션은
+// `gaon work` 와 **같은 관례**로 연결한다 — `GAON_DATABASE_URL` 로 main
+// 커넥션을 세운다(§4.5 멀티 커넥션의 gaon.config.ts 전체 로더는 M9 CLI 완성).
+// 모든 명령은 --json 을 함께 낸다(CLAUDE.md §4).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { env, EnvError } from '@gaonjs/core';
+import { createDb, registerConnection, destroyAllConnections, isSeedDef, } from '@gaonjs/data';
+import { registerTsResolve } from './tsResolve.js';
+/** DB URL 에서 어댑터를 추정한다(gaon work 와 동일 규칙). */
+function dbConfigFromUrl(url) {
+    if (url.startsWith('mysql://') || url.startsWith('mariadb://')) {
+        return { adapter: 'mysql', url, poolMax: 4 };
+    }
+    return { adapter: 'postgres', url, poolMax: 4 };
+}
+/** domain/seed.ts 의 default export 를 읽어 SeedDef 를 돌려준다(없으면 안내 에러). */
+export async function loadSeed(root) {
+    const file = join(root, 'domain', 'seed.ts');
+    if (!existsSync(file)) {
+        throw new Error(`시드 파일이 없습니다: domain/seed.ts\n` +
+            `  → domain/seed.ts 를 만들고 default export 로 시드를 선언하세요:\n` +
+            `      import { seed } from 'gaonjs/data'\n` +
+            `      export default seed(async () => { /* await Model.create(...) */ })`);
+    }
+    registerTsResolve();
+    const mod = (await import(pathToFileURL(file).href));
+    if (!isSeedDef(mod.default)) {
+        throw new Error(`domain/seed.ts 의 default export 가 시드 정의가 아닙니다.\n` +
+            `  → seed(...) 로 감싸 default export 하세요: export default seed(async () => {...})`);
+    }
+    return mod.default;
+}
+/**
+ * `gaon db seed` — main 커넥션을 연결하고 domain/seed.ts 를 실행한다.
+ * 커넥션 정리(destroyAllConnections)는 항상 수행한다.
+ */
+export async function runDbSeedCommand(opts = {}) {
+    const root = opts.root ?? process.cwd();
+    const dbUrl = opts.databaseUrl ?? env.optional('GAON_DATABASE_URL');
+    if (!dbUrl) {
+        throw new EnvError(`환경변수 GAON_DATABASE_URL 가 설정되지 않았습니다(시드에 DB 연결 필요).\n` +
+            `  → .env 에 다음 줄을 추가하고 다시 실행하세요:\n` +
+            `      GAON_DATABASE_URL=postgres://user:pass@localhost:5432/mydb`);
+    }
+    registerConnection('main', createDb(dbConfigFromUrl(dbUrl)), dbConfigFromUrl(dbUrl).adapter);
+    try {
+        const def = await loadSeed(root);
+        await def.run();
+        return {
+            exitCode: 0,
+            text: `  gaon db seed · 완료 — domain/seed.ts 실행됨`,
+            json: { command: 'seed', ok: true },
+        };
+    }
+    finally {
+        await destroyAllConnections();
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,36 @@
+export type ResponseKind = 'render' | 'redirect' | 'json' | 'plain';
+export interface ActionUsage {
+    readonly file: string;
+    readonly action: string;
+    readonly line: number;
+    readonly kinds: readonly ResponseKind[];
+}
+export interface DoctorIssue {
+    readonly file: string;
+    readonly line: number;
+    readonly action: string;
+    readonly kinds: readonly ResponseKind[];
+    readonly message: string;
+}
+export interface DoctorResult {
+    readonly ok: boolean;
+    readonly checked: number;
+    readonly issues: readonly DoctorIssue[];
+}
+/** 컨트롤러 파일 하나를 검사한다. */
+export declare function inspectControllerSource(file: string, source: string): ActionUsage[];
+/**
+ * apps/<app>/controllers/ 를 훑어 응답 혼용 액션을 찾는다. 액션 하나의 kinds
+ * 배열이 2종 이상이면 위반(단, 'plain' 하나만 있는 것과 render 만 있는 것은 통과).
+ *
+ * 명시적 예외: 반환 없는 return(=undefined→204)만 있는 경우는 통과 — void 액션은
+ * 흔히 혼용 없이 정상적으로 쓰인다.
+ */
+export declare function runDoctor(appsDir: string): Promise<DoctorResult>;
+export declare function fileExists(file: string): Promise<boolean>;
+export interface DoctorCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+}
+/** `gaon doctor` 진입점. */
+export declare function runDoctorCommand(opts?: DoctorCommandOptions): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,218 @@
+/**
+ * @gaonjs/cli · `gaon doctor` — 정적 검사 (M3 · errata E-3)
+ *
+ * v1 첫 검사 항목: **응답 혼용 금지**. 한 컨트롤러 액션은 render/JSON/
+ * redirect 중 한 가지 응답 형태만 낼 수 있다(§C · The One Way). 조건 분기로
+ * 섞으면 "이 라우트가 무엇을 돌려주는지"가 코드를 읽어야 알게 돼 AI 첫 시도
+ * 성공률이 떨어진다.
+ *
+ * 검사 방법(정적 분석):
+ *  · apps/<app>/controllers/*.ts 를 TS AST 로 파싱.
+ *  · export default controller({ ... }) 의 액션 함수마다 return 노드에서
+ *    최종 응답 형태를 분류(render | redirect | json | plain).
+ *  · 서로 다른 형태가 두 종류 이상이면 위반.
+ *  · this.render/this.redirect/this.json/평범한 객체 반환의 4종을 구별한다.
+ *
+ * 위반 시: 파일·라인·액션 이름 + 감지된 형태 목록 + "→ 한 액션은 한 응답
+ * 형태만 유지하세요(errata E-3 §C)" 안내를 낸다.
+ *
+ * 나머지 doctor 검사(의존 방향 §1-5, 커넥션 §4.5 등)는 후속 마일스톤에서
+ * 이 모듈에 규칙을 얹는다.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+/** 컨트롤러 파일 하나를 검사한다. */
+export function inspectControllerSource(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const usages = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isControllerCall(node)) {
+            const arg = node.arguments[0];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    const action = actionName(prop);
+                    if (!action)
+                        continue;
+                    const body = actionBody(prop);
+                    if (!body)
+                        continue;
+                    const kinds = classifyReturns(body);
+                    const { line } = sf.getLineAndCharacterOfPosition(prop.getStart(sf));
+                    usages.push({ file, action, line: line + 1, kinds });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return usages;
+}
+function isControllerCall(node) {
+    const e = node.expression;
+    if (ts.isIdentifier(e) && e.text === 'controller')
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'controller')
+        return true;
+    return false;
+}
+function actionName(prop) {
+    if (ts.isMethodDeclaration(prop) && ts.isIdentifier(prop.name))
+        return prop.name.text;
+    if (ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        (ts.isArrowFunction(prop.initializer) || ts.isFunctionExpression(prop.initializer))) {
+        return prop.name.text;
+    }
+    return undefined;
+}
+function actionBody(prop) {
+    if (ts.isMethodDeclaration(prop))
+        return prop.body;
+    if (ts.isPropertyAssignment(prop)) {
+        if (ts.isArrowFunction(prop.initializer))
+            return prop.initializer.body;
+        if (ts.isFunctionExpression(prop.initializer))
+            return prop.initializer.body;
+    }
+    return undefined;
+}
+/** 액션 본문의 모든 return 표현식을 응답 형태로 분류하고 중복을 제거해 반환한다. */
+function classifyReturns(body) {
+    const kinds = new Set();
+    const classify = (expr) => {
+        // await x → x 로 되짚어 본다.
+        if (ts.isAwaitExpression(expr))
+            return classify(expr.expression);
+        // this.render / this.redirect / this.json
+        if (ts.isCallExpression(expr)) {
+            const c = expr.expression;
+            if (ts.isPropertyAccessExpression(c) && c.expression.kind === ts.SyntaxKind.ThisKeyword) {
+                if (c.name.text === 'render')
+                    return 'render';
+                if (c.name.text === 'redirect')
+                    return 'redirect';
+                if (c.name.text === 'json')
+                    return 'json';
+            }
+            // 삼항·논리 연산 결과라도 호출식이 나오면 함수 반환값에 의존 — 보수적으로 plain.
+            return 'plain';
+        }
+        // 삼항 연산자 — 양쪽 각각 분류
+        if (ts.isConditionalExpression(expr)) {
+            kinds.add(classify(expr.whenTrue));
+            kinds.add(classify(expr.whenFalse));
+            return classify(expr.whenTrue); // 반환값(대표) — Set 에 이미 다 넣음
+        }
+        // 그 외(객체·배열·literal·식별자 등) → plain(JSON 액션)
+        return 'plain';
+    };
+    const visit = (node) => {
+        if (ts.isReturnStatement(node)) {
+            if (node.expression)
+                kinds.add(classify(node.expression));
+            else
+                kinds.add('plain'); // 빈 return 은 undefined → 204 (plain 으로 취급, 혼용 검사에서만 의미)
+            return; // return 안의 하위 함수는 다른 스코프 — 이 return 만 잡는다
+        }
+        // 중첩 함수/화살표는 다른 스코프 — 파고들지 않는다.
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
+            return;
+        ts.forEachChild(node, visit);
+    };
+    // 표현식 본문 화살표(=> render(...))는 body 가 표현식.
+    if (ts.isBlock(body))
+        visit(body);
+    else
+        kinds.add(classify(body));
+    return [...kinds];
+}
+/**
+ * apps/<app>/controllers/ 를 훑어 응답 혼용 액션을 찾는다. 액션 하나의 kinds
+ * 배열이 2종 이상이면 위반(단, 'plain' 하나만 있는 것과 render 만 있는 것은 통과).
+ *
+ * 명시적 예외: 반환 없는 return(=undefined→204)만 있는 경우는 통과 — void 액션은
+ * 흔히 혼용 없이 정상적으로 쓰인다.
+ */
+export async function runDoctor(appsDir) {
+    const issues = [];
+    let checked = 0;
+    const apps = await safeListDirs(appsDir);
+    for (const app of apps) {
+        const ctrlDir = join(appsDir, app, 'controllers');
+        for (const file of await safeListFiles(ctrlDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const full = join(ctrlDir, file);
+            const source = await readFile(full, 'utf8');
+            const usages = inspectControllerSource(full, source);
+            checked += usages.length;
+            for (const u of usages) {
+                if (u.kinds.length < 2)
+                    continue;
+                // 'plain' 이 유일한 다른 형태이면서 실제 return 문에 undefined 만 있는 경우는 걸러야
+                // 하지만, 액션이 render|json 를 하다가 조건에 따라 undefined 반환하면 혼용이다. 유지.
+                const rel = relative(process.cwd(), full);
+                issues.push({
+                    file: rel,
+                    line: u.line,
+                    action: u.action,
+                    kinds: u.kinds,
+                    message: `[doctor] 응답 혼용 감지: ${rel}:${u.line} · 액션 '${u.action}' 이 서로 다른 응답 형태를 섞습니다 (${u.kinds.join(', ')}).\n` +
+                        `→ 한 액션은 한 응답 형태만 유지하세요 (render | JSON | redirect · errata E-3 §C).\n` +
+                        `→ 조건 분기가 필요하면 액션을 둘로 나누거나, JSON 반환에는 예외를 던져 상태 코드를 표현하세요.`,
+                });
+            }
+        }
+    }
+    return { ok: issues.length === 0, checked, issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+// stat 은 API 표면 유지용 — 파일 존재 확인이 필요할 때 씀.
+export async function fileExists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `gaon doctor` 진입점. */
+export async function runDoctorCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const appsDir = resolve(cwd, 'apps');
+    const result = await runDoctor(appsDir);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(result) + '\n');
+    }
+    else {
+        process.stdout.write(`  검사한 액션: ${result.checked}개\n`);
+        if (result.ok) {
+            process.stdout.write(`  ✓ 응답 혼용 없음\n`);
+        }
+        else {
+            process.stdout.write(`  ✗ 응답 혼용 ${result.issues.length}건\n`);
+            for (const i of result.issues)
+                process.stdout.write(i.message + '\n');
+        }
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/domain.d.ts

@@ -2,6 +2,7 @@ import { type ScheduleDef } from '@gaonjs/async';
 export interface LoadedDomain {
     readonly jobs: number;
     readonly listeners: number;
+    readonly mails: number;
     readonly schedule?: ScheduleDef;
 }
 /**

package/dist/domain.js

@@ -15,6 +15,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isJobDef, isListener, reidentifyListener } from '@gaonjs/async';
+import { isMailDef } from '@gaonjs/mail';
 import { registerTsResolve } from './tsResolve.js';
 function tsFilesIn(dir) {
     if (!existsSync(dir))
@@ -36,9 +37,21 @@ export async function loadDomain(root) {
     const domainDir = join(root, 'domain');
     let jobs = 0;
     let listeners = 0;
+    let mails = 0;
     // 이벤트 정의를 먼저 import 해 리스너가 참조할 수 있게 한다(부수효과 없음).
     for (const file of tsFilesIn(join(domainDir, 'events')))
         await importFile(file);
+    // 메일 — domain/mails/ 의 파일이 곧 등록(§7). 파일명을 이름으로 심는다.
+    for (const file of tsFilesIn(join(domainDir, 'mails'))) {
+        const mod = await importFile(file);
+        const nm = basename(file, '.ts');
+        for (const value of Object.values(mod)) {
+            if (isMailDef(value)) {
+                value.assignName(nm);
+                mails++;
+            }
+        }
+    }
     for (const file of tsFilesIn(join(domainDir, 'jobs'))) {
         const mod = await importFile(file);
         const base = basename(file, '.ts');
@@ -68,5 +81,5 @@ export async function loadDomain(root) {
             schedule = def;
         }
     }
-    return { jobs, listeners, schedule };
+    return { jobs, listeners, mails, schedule };
 }

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthComma
 export { runHubCommand, type HubCommandOptions } from "./hub.js";
 export { runWorkCommand, type WorkCommandOptions } from "./work.js";
 export { runJobsCommand, type JobsCommandOptions } from "./jobs.js";
+export { runDbSeedCommand, loadSeed, type DbSeedOptions, type DbSeedResult } from "./db.js";
+export { runDoctorCommand, runDoctor, inspectControllerSource, type DoctorResult, type DoctorIssue, type ActionUsage, type ResponseKind, type DoctorCommandOptions, } from "./doctor.js";
 export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {
     readonly name: "gaon";

package/dist/index.js

@@ -16,12 +16,16 @@ import { runGenerateAuthCommand } from "./generate.js";
 import { runHubCommand } from "./hub.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
+import { runDbSeedCommand } from "./db.js";
+import { runDoctorCommand } from "./doctor.js";
 export { runDevCommand, startDev, resolveDevLayout, } from "./dev.js";
 export { runCheck, runCheckCommand, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
 export { runHubCommand } from "./hub.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 { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
 export function roadmapReport(version = VERSION) {
@@ -69,6 +73,7 @@ function renderHelp(version = VERSION) {
         "    gaon dev           .gaon 타입 브리지를 감시·재생성 (스키마·라우트)",
         "    gaon dev --json    재생성 이벤트를 JSON 으로 출력",
         "    gaon check         .gaon 재생성 후 타입 검사 (CI·AI 정합)",
+        "    gaon doctor        정적 검사 (응답 혼용·의존 방향 등)",
         "    gaon g auth        인증 스캐폴드 생성 (회원가입·로그인·세션·보호 라우트)",
         "    gaon hub           실시간 허브 프로세스 (프레즌스 권위·중계 · 리더 선출 HA)",
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
@@ -108,6 +113,19 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon doctor` — 정적 검사(응답 혼용 등 · errata E-3 §C). --fix 는 후속.
+    if (argv[0] === "doctor") {
+        void runDoctorCommand({ json: argv.includes("--json") })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon doctor 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon hub` — 실시간 허브 프로세스(§7 M6). 운영 프로세스 3종 중 하나.
     // NATS·리더 선출 대기로 프로세스를 살려 두고, SIGINT/SIGTERM 에 그레이스풀 종료.
     if (argv[0] === "hub") {
@@ -141,6 +159,21 @@ 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;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon db seed 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     // `gaon g auth` — 인증 스캐폴드 제너레이터(§7 M5). 다른 제너레이터는 후속.
     if (argv[0] === "g" || argv[0] === "generate") {
         if (argv[1] === "auth") {

package/dist/work.js

@@ -72,6 +72,15 @@ export async function runWorkCommand(opts = {}) {
     if (dbUrl)
         db = createDb(dbConfigFromUrl(dbUrl));
     const domain = await loadDomain(root);
+    // 로드된 도메인 자산 요약(파일=등록 관측용). 잡·리스너·메일 수를 노출한다.
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            kind: 'domain',
+            jobs: domain.jobs,
+            listeners: domain.listeners,
+            mails: domain.mails,
+        }) + '\n');
+    }
     let work;
     try {
         work = await runWork({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@gaonjs/async": "0.2.1",
-    "@gaonjs/core": "0.1.3",
-    "@gaonjs/data": "0.2.2",
-    "@gaonjs/web": "0.2.2"
+    "typescript": "*",
+    "@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"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""