@gaonjs/cli 0.1.6 → 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

@@ -0,0 +1,12 @@
+import { type ScheduleDef } from '@gaonjs/async';
+export interface LoadedDomain {
+    readonly jobs: number;
+    readonly listeners: number;
+    readonly mails: number;
+    readonly schedule?: ScheduleDef;
+}
+/**
+ * domain/ 을 스캔·import 해 잡·리스너·스케줄을 등록한다. 반환값은 등록 요약.
+ * .ts 상대 import 해석을 위해 tsResolve 훅을 먼저 켠다.
+ */
+export declare function loadDomain(root: string): Promise<LoadedDomain>;

package/dist/domain.js

@@ -0,0 +1,85 @@
+/**
+ * @gaonjs/cli · 도메인 로더 (§7 M7 — 파일=등록)
+ *
+ * `gaon work`(그리고 향후 serve)가 부팅 시 도메인의 비동기 자산을 불러
+ * 레지스트리를 채운다. 관례대로 **디렉터리에 파일을 놓는 것이 곧 등록**이고,
+ * 잡·리스너의 이름/식별자는 파일명에서 채운다(잡은 그래야 `.later()` 가
+ * 어느 프로세스에서든 동작한다 — assignName 이 원본 객체를 mutate).
+ *
+ *  domain/jobs/*.ts        → 잡(이름 = 파일명)
+ *  domain/events/*.ts      → 이벤트 정의(리스너가 참조 · import 만)
+ *  domain/listeners/*.ts   → 리스너(durable id = 파일명)
+ *  domain/schedule.ts      → 스케줄 정의(default export)
+ */
+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))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.test.ts'))
+        .map((e) => join(dir, e.name))
+        .sort();
+}
+async function importFile(file) {
+    return (await import(pathToFileURL(file).href));
+}
+/**
+ * domain/ 을 스캔·import 해 잡·리스너·스케줄을 등록한다. 반환값은 등록 요약.
+ * .ts 상대 import 해석을 위해 tsResolve 훅을 먼저 켠다.
+ */
+export async function loadDomain(root) {
+    registerTsResolve();
+    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');
+        for (const value of Object.values(mod)) {
+            if (isJobDef(value)) {
+                value.assignName(base);
+                jobs++;
+            }
+        }
+    }
+    for (const file of tsFilesIn(join(domainDir, 'listeners'))) {
+        const mod = await importFile(file);
+        const base = basename(file, '.ts');
+        for (const value of Object.values(mod)) {
+            if (isListener(value)) {
+                reidentifyListener(value, base);
+                listeners++;
+            }
+        }
+    }
+    let schedule;
+    const scheduleFile = join(domainDir, 'schedule.ts');
+    if (existsSync(scheduleFile)) {
+        const mod = await importFile(scheduleFile);
+        const def = mod.default;
+        if (def && typeof def === 'object' && Array.isArray(def.entries)) {
+            schedule = def;
+        }
+    }
+    return { jobs, listeners, mails, schedule };
+}

package/dist/hub.d.ts

@@ -4,9 +4,11 @@ export interface HubCommandOptions {
     readonly natsUrl?: string;
     /** 리스 TTL(ms). 생략 시 env GAON_HUB_TTL_MS, 그다음 허브 기본(5000). */
     readonly ttlMs?: number;
-    /** 멤버 만료 임계(ms). 생략 시 env GAON_HUB_MEMBER_TIMEOUT_MS. */
-    readonly memberTimeoutMs?: number;
-    /** 만료 스윕 주기(ms). 생략 시 env GAON_HUB_SWEEP_MS. */
+    /** TCP 리슨 포트(errata E-2). 생략 시 env GAON_HUB_PORT, 그다음 4001. */
+    readonly port?: number;
+    /** 소켓 무활동 임계(ms). 생략 시 env GAON_HUB_PING_TIMEOUT_MS. */
+    readonly pingTimeoutMs?: number;
+    /** 무활동·회수 스윕 주기(ms). 생략 시 env GAON_HUB_SWEEP_MS. */
     readonly sweepMs?: number;
     /** 시그널 등록·해제(테스트 주입). 기본 process. */
     readonly signals?: {

package/dist/hub.js

@@ -54,10 +54,14 @@ export async function runHubCommand(opts = {}) {
             nats,
             id,
             // 운영 튜닝: 옵션 > 환경변수 > 허브 기본. 컨테이너 배치에서 헬스체크
-            // 주기에 맞춰 리스 TTL·만료 임계를 조정한다.
+            // 주기에 맞춰 리스 TTL·TCP 포트·소켓 임계를 조정한다.
             ttlMs: opts.ttlMs ?? envInt('GAON_HUB_TTL_MS'),
-            memberTimeoutMs: opts.memberTimeoutMs ?? envInt('GAON_HUB_MEMBER_TIMEOUT_MS'),
+            port: opts.port ?? envInt('GAON_HUB_PORT'),
+            host: process.env.GAON_HUB_HOST,
+            advertiseAddr: process.env.GAON_HUB_ADVERTISE,
+            pingTimeoutMs: opts.pingTimeoutMs ?? envInt('GAON_HUB_PING_TIMEOUT_MS'),
             sweepMs: opts.sweepMs ?? envInt('GAON_HUB_SWEEP_MS'),
+            reclaimGraceMs: envInt('GAON_HUB_RECLAIM_GRACE_MS'),
             onState: (s) => emit({ kind: 'leader', leader: s.leader, id }),
         });
     }

package/dist/index.d.ts

@@ -2,6 +2,11 @@ export { runDevCommand, startDev, resolveDevLayout, type DevDeps, type DevLayout
 export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, type AuthScaffoldOptions, type ScaffoldFile, type ScaffoldResult, type GenerateAuthOptions, } from "./generate.js";
 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";
     readonly version: string;

package/dist/index.js

@@ -14,10 +14,19 @@ import { runDevCommand } from "./dev.js";
 import { runCheckCommand } from "./check.js";
 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) {
     return {
@@ -64,8 +73,12 @@ 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)",
+        "    gaon jobs list --failed   DLQ(실패 잡) 목록",
+        "    gaon jobs retry <id>      DLQ 잡 재적재",
         "    gaon --json        같은 정보를 JSON 으로 출력",
         "    gaon --version     버전 출력",
         "    gaon --help        이 도움말",
@@ -100,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") {
@@ -110,6 +136,44 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // `gaon work` — 워커 프로세스(§7 M7). 잡·리스너·스케줄·아웃박스 조립.
+    // 시그널에 graceful drain 후 종료.
+    if (argv[0] === "work") {
+        void runWorkCommand({ json: argv.includes("--json") }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon work 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
+    // `gaon jobs` — DLQ 조회·재적재(§7 M7). list --failed | retry <id>.
+    if (argv[0] === "jobs") {
+        void runJobsCommand(argv.slice(1), { json: argv.includes("--json") })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon jobs 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        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/jobs.d.ts

@@ -0,0 +1,7 @@
+export interface JobsCommandOptions {
+    readonly json?: boolean;
+    /** NATS 접속지. 생략 시 GAON_NATS_URL, 그다음 기본(4222). */
+    readonly natsUrl?: string;
+}
+/** `gaon jobs ...` 진입점. 종료 코드를 돌려준다(0 성공 · 1 실패). */
+export declare function runJobsCommand(argv: readonly string[], opts?: JobsCommandOptions): Promise<number>;

package/dist/jobs.js

@@ -0,0 +1,76 @@
+/**
+ * @gaonjs/cli · `gaon jobs` — DLQ 조회·재적재 (§7 · M7 · line 886~887)
+ *
+ * 최대 재시도를 소진해 DLQ 로 간 잡을 운영자가 확인하고 재실행한다:
+ *   gaon jobs list --failed      실패 잡 목록(최신순)
+ *   gaon jobs retry <id>         DLQ 잡을 잡 큐로 재적재
+ * 모든 명령과 같이 `--json` 을 제공한다.
+ */
+import { connectNats, listDlq, retryDlq } from '@gaonjs/async';
+function fmtTime(ms) {
+    return new Date(ms).toISOString();
+}
+function renderList(entries) {
+    if (entries.length === 0)
+        return '  DLQ 가 비어 있습니다 — 실패한 잡이 없습니다.';
+    const lines = [`  실패 잡 ${entries.length}건 (최신순):`, ''];
+    for (const e of entries) {
+        lines.push(`  ${e.id}  ${e.name}  (시도 ${e.attempts}회 · ${fmtTime(e.failedAt)})`);
+        lines.push(`     ↳ ${e.error}`);
+    }
+    lines.push('');
+    lines.push('  재적재: gaon jobs retry <id>');
+    return lines.join('\n');
+}
+/** `gaon jobs ...` 진입점. 종료 코드를 돌려준다(0 성공 · 1 실패). */
+export async function runJobsCommand(argv, opts = {}) {
+    const json = opts.json ?? argv.includes('--json');
+    const sub = argv[0];
+    if (sub === 'list') {
+        const failedOnly = argv.includes('--failed');
+        if (!failedOnly) {
+            process.stderr.write(`  ✗ gaon jobs list 는 현재 --failed(DLQ) 만 지원합니다.\n` +
+                `  → gaon jobs list --failed\n`);
+            return 1;
+        }
+        const nats = await connectNats({ servers: opts.natsUrl, name: 'jobs-cli' });
+        try {
+            const entries = await listDlq(nats);
+            if (json)
+                process.stdout.write(JSON.stringify({ failed: entries }, null, 2) + '\n');
+            else
+                process.stdout.write(renderList(entries) + '\n');
+            return 0;
+        }
+        finally {
+            await nats.close();
+        }
+    }
+    if (sub === 'retry') {
+        const id = argv[1];
+        if (!id || id.startsWith('--')) {
+            process.stderr.write(`  ✗ 재적재할 잡 id 가 필요합니다.\n  → gaon jobs retry <id>\n`);
+            return 1;
+        }
+        const nats = await connectNats({ servers: opts.natsUrl, name: 'jobs-cli' });
+        try {
+            const entry = await retryDlq(nats, id);
+            if (json)
+                process.stdout.write(JSON.stringify({ retried: entry }, null, 2) + '\n');
+            else
+                process.stdout.write(`  ↺ 재적재 완료 — ${entry.name} (id ${entry.id})\n`);
+            return 0;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ ${msg}\n`);
+            return 1;
+        }
+        finally {
+            await nats.close();
+        }
+    }
+    process.stderr.write(`  ✗ 알 수 없는 jobs 명령: ${sub ?? '(없음)'}\n` +
+        `  → gaon jobs list --failed | gaon jobs retry <id>\n`);
+    return 1;
+}

package/dist/work.d.ts

@@ -0,0 +1,24 @@
+export interface WorkCommandOptions {
+    readonly json?: boolean;
+    /** NATS 접속지. 생략 시 GAON_NATS_URL, 그다음 기본(4222). */
+    readonly natsUrl?: string;
+    /** 도메인 루트(domain/ 의 부모). 기본 cwd. */
+    readonly root?: string;
+    /** 아웃박스 릴레이용 DB URL. 생략 시 GAON_DATABASE_URL, 없으면 릴레이 미기동. */
+    readonly databaseUrl?: string;
+    /** 큐 기본 동시성. */
+    readonly concurrency?: number;
+    /** ack 대기(ms). 생략 시 GAON_WORKER_ACK_WAIT_MS. */
+    readonly ackWaitMs?: number;
+    /** graceful drain 상한(ms). 생략 시 GAON_WORKER_DRAIN_MS. */
+    readonly drainTimeoutMs?: number;
+    /** 시그널 등록·해제(테스트 주입). 기본 process. */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * 워커를 띄우고 시그널까지 살려 둔다. 반환 프라미스는 graceful 종료 시 resolve.
+ */
+export declare function runWorkCommand(opts?: WorkCommandOptions): Promise<void>;

package/dist/work.js

@@ -0,0 +1,122 @@
+/**
+ * @gaonjs/cli · `gaon work` — 워커 프로세스 (§7 · M7)
+ *
+ * 운영 프로세스 3종(serve · work · hub) 중 하나. 도메인의 잡·리스너·스케줄·
+ * 아웃박스를 한 프로세스에 조립해 돌린다(@gaonjs/async runWork). 개발
+ * 모드는 `gaon dev` 가 워커를 내장 실행하므로 이 명령은 운영 배치용이다.
+ *
+ * 종료 시그널(SIGTERM·SIGINT)에 graceful drain — 스케줄러 리더 반납 →
+ * 릴레이·리스너·워커 순으로 내리고, 진행 중 잡은 상한까지 기다린다. 모든
+ * 명령과 같이 `--json` 을 제공한다.
+ */
+import { hostname } from 'node:os';
+import { connectNats, runWork } from '@gaonjs/async';
+import { createDb } from '@gaonjs/data';
+import { loadDomain } from './domain.js';
+/** DB URL 에서 어댑터를 추정한다(postgres·mysql). */
+function dbConfigFromUrl(url) {
+    if (url.startsWith('mysql://') || url.startsWith('mariadb://')) {
+        return { adapter: 'mysql', url, poolMax: 4 };
+    }
+    return { adapter: 'postgres', url, poolMax: 4 };
+}
+/** 환경변수를 정수로 파싱(미설정·비정상 시 undefined). */
+function envInt(name) {
+    const raw = process.env[name];
+    if (raw == null || raw === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : undefined;
+}
+function emitHuman(e) {
+    switch (e.kind) {
+        case 'ready':
+            return `  gaon work · 준비 — 잡 ${e.jobs} · 리스너 ${e.listeners} · 스케줄 ${e.scheduled}`;
+        case 'scheduler':
+            if (e.event.kind === 'leader')
+                return e.event.leader ? '  ▶ 스케줄러 리더 — 틱 발행 시작' : '  · 스케줄러 대기(standby)';
+            if (e.event.kind === 'fired')
+                return `  ⏰ 스케줄 발행 — ${e.event.label}`;
+            return undefined;
+        case 'worker':
+            if (e.event.kind === 'dead')
+                return `  ✗ 잡 DLQ — ${e.event.job} (${e.event.error})`;
+            return undefined;
+        case 'relay':
+            return `  ↪ 아웃박스 릴레이 — ${e.count}건 발행`;
+        default:
+            return undefined;
+    }
+}
+/**
+ * 워커를 띄우고 시그널까지 살려 둔다. 반환 프라미스는 graceful 종료 시 resolve.
+ */
+export async function runWorkCommand(opts = {}) {
+    const json = opts.json ?? false;
+    const signals = opts.signals ?? process;
+    const root = opts.root ?? process.cwd();
+    const id = `${hostname()}#${process.pid}`;
+    const emit = (e) => {
+        if (json) {
+            process.stdout.write(JSON.stringify(e) + '\n');
+        }
+        else {
+            const line = emitHuman(e);
+            if (line)
+                process.stdout.write(line + '\n');
+        }
+    };
+    const nats = await connectNats({ servers: opts.natsUrl, name: `work@${id}` });
+    let db;
+    const dbUrl = opts.databaseUrl ?? process.env.GAON_DATABASE_URL;
+    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({
+            nats,
+            id,
+            db,
+            schedule: domain.schedule,
+            concurrency: opts.concurrency,
+            ackWaitMs: opts.ackWaitMs ?? envInt('GAON_WORKER_ACK_WAIT_MS'),
+            drainTimeoutMs: opts.drainTimeoutMs ?? envInt('GAON_WORKER_DRAIN_MS'),
+            onEvent: emit,
+        });
+    }
+    catch (err) {
+        if (db)
+            await db.destroy().catch(() => { });
+        await nats.close();
+        throw err;
+    }
+    await new Promise((resolve) => {
+        const stop = () => {
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            void (async () => {
+                await work.stop();
+                if (db)
+                    await db.destroy().catch(() => { });
+                await nats.close();
+                if (json)
+                    process.stdout.write(JSON.stringify({ kind: 'stopped' }) + '\n');
+                else
+                    process.stdout.write('  gaon work · 종료\n');
+                resolve();
+            })();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@gaonjs/async": "0.2.0",
-    "@gaonjs/core": "0.1.3",
-    "@gaonjs/web": "0.2.1",
-    "@gaonjs/data": "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})\""