@gaonjs/cli 0.1.2 → 0.1.3

package/dist/check.d.ts

@@ -0,0 +1,29 @@
+import { type DevLayout } from './dev.js';
+export interface TypecheckResult {
+    readonly ok: boolean;
+    readonly output: string;
+    /** 실행한 체커 이름(vue-tsc | tsc | none). */
+    readonly checker: string;
+}
+export interface CheckDeps {
+    readonly layout: DevLayout;
+    regenerateTables(schemaDir: string, out: string): Promise<unknown>;
+    regenerateRoutes(appDir: string, out: string): Promise<unknown>;
+    typecheck(): Promise<TypecheckResult>;
+}
+export interface CheckResult {
+    readonly ok: boolean;
+    readonly regenerated: {
+        readonly tables: boolean;
+        readonly routes: string[];
+    };
+    readonly typecheck: TypecheckResult;
+}
+/** .gaon 재생성 → 타입 체크. 재생성이 검사보다 먼저다(§13.4-5). */
+export declare function runCheck(deps: CheckDeps): Promise<CheckResult>;
+export interface CheckCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+}
+/** `gaon check` 진입점. */
+export declare function runCheckCommand(opts?: CheckCommandOptions): Promise<number>;

package/dist/check.js

@@ -0,0 +1,92 @@
+/**
+ * @gaonjs/cli · `gaon check` — 검사 전 .gaon 재생성 (M3, §13.4-5)
+ *
+ * 개발 서버(gaon dev)가 떠 있지 않은 CI·AI 에이전트 환경에서도 타입
+ * 체인이 항상 최신으로 검증되게, 타입 검사 **전에** .gaon(tables·routes)
+ * 을 먼저 재생성한 뒤 tsc/vue-tsc 를 돌린다.
+ *
+ * 오케스트레이션(runCheck)은 주입으로 순수하게 유지하고, 진입점이 cwd
+ * 관례로 실제 재생성기·타입 체커를 엮는다(dev.ts 와 동일 패턴).
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { generateTablesDts } from '@gaonjs/data';
+import { generateRoutesDts } from '@gaonjs/web';
+import { resolveDevLayout } from './dev.js';
+import { registerTsResolve } from './tsResolve.js';
+/** .gaon 재생성 → 타입 체크. 재생성이 검사보다 먼저다(§13.4-5). */
+export async function runCheck(deps) {
+    const { layout } = deps;
+    const routes = [];
+    if (layout.schemaDir)
+        await deps.regenerateTables(layout.schemaDir, layout.tablesOut);
+    for (const app of layout.apps) {
+        await deps.regenerateRoutes(app.appDir, app.routesOut);
+        routes.push(app.name);
+    }
+    const typecheck = await deps.typecheck();
+    return {
+        ok: typecheck.ok,
+        regenerated: { tables: !!layout.schemaDir, routes },
+        typecheck,
+    };
+}
+/** 프로젝트에 맞는 타입 체커를 골라 실행한다. .vue 가 있으면 vue-tsc. */
+function makeProjectTypecheck(cwd) {
+    return () => new Promise((resolve) => {
+        const tsconfig = join(cwd, 'tsconfig.json');
+        if (!existsSync(tsconfig)) {
+            resolve({
+                ok: false,
+                checker: 'none',
+                output: `[gaon check] tsconfig.json 이 없습니다: ${tsconfig}\n` +
+                    `→ 프로젝트 루트에 tsconfig.json 을 만들고 다시 실행하세요.`,
+            });
+            return;
+        }
+        const vueTsc = join(cwd, 'node_modules', '.bin', 'vue-tsc');
+        const useVue = existsSync(vueTsc);
+        const checker = useVue ? 'vue-tsc' : 'tsc';
+        const cmd = useVue ? vueTsc : process.execPath;
+        const args = useVue
+            ? ['--noEmit', '-p', tsconfig]
+            : [join(cwd, 'node_modules', 'typescript', 'bin', 'tsc'), '--noEmit', '-p', tsconfig];
+        const child = spawn(cmd, args, { cwd });
+        let output = '';
+        child.stdout.on('data', (b) => (output += b.toString()));
+        child.stderr.on('data', (b) => (output += b.toString()));
+        child.on('error', (e) => resolve({ ok: false, checker, output: String(e) }));
+        child.on('close', (code) => resolve({ ok: code === 0, checker, output }));
+    });
+}
+/** `gaon check` 진입점. */
+export async function runCheckCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    registerTsResolve(); // 사용자 .ts 의 `.js` 상대 import 를 런타임에 해석
+    const deps = {
+        layout: resolveDevLayout(cwd),
+        regenerateTables: generateTablesDts,
+        regenerateRoutes: generateRoutesDts,
+        typecheck: makeProjectTypecheck(cwd),
+    };
+    const result = await runCheck(deps);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(result) + '\n');
+    }
+    else {
+        const r = result.regenerated;
+        const gen = [r.tables ? 'tables.d.ts' : null, ...r.routes.map((a) => `${a}/routes.d.ts`)]
+            .filter(Boolean)
+            .join(', ');
+        process.stdout.write(`  재생성: ${gen || '(대상 없음)'}\n`);
+        if (result.ok) {
+            process.stdout.write(`  ✓ 타입 검사 통과 (${result.typecheck.checker})\n`);
+        }
+        else {
+            process.stdout.write(`  ✗ 타입 검사 실패 (${result.typecheck.checker})\n`);
+            process.stdout.write(result.typecheck.output);
+        }
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/dev.d.ts

@@ -0,0 +1,59 @@
+import { type WatchHandle, type WatchOptions } from '@gaonjs/data';
+export interface DevApp {
+    readonly name: string;
+    readonly appDir: string;
+    /** apps/<app>/.gaon/routes.d.ts */
+    readonly routesOut: string;
+}
+export interface DevLayout {
+    /** domain/schema (없으면 undefined — tables 워치 생략). */
+    readonly schemaDir?: string;
+    /** .gaon/tables.d.ts */
+    readonly tablesOut: string;
+    readonly apps: readonly DevApp[];
+}
+export interface DevDeps {
+    readonly layout: DevLayout;
+    regenerateTables(schemaDir: string, out: string): Promise<unknown>;
+    regenerateRoutes(appDir: string, out: string): Promise<unknown>;
+    watch(dir: string, opts: WatchOptions): WatchHandle;
+    log(event: DevEvent): void;
+    onError(err: Error): void;
+}
+export type DevEvent = {
+    readonly kind: 'ready';
+    readonly schema: boolean;
+    readonly apps: string[];
+} | {
+    readonly kind: 'regen';
+    readonly target: 'tables' | 'routes';
+    readonly app?: string;
+} | {
+    readonly kind: 'stopped';
+};
+export interface DevHandle {
+    /** 모든 워처를 닫는다. */
+    close(): void;
+}
+/**
+ * 초기 1회 전체 재생성 후, 스키마·앱 라우트를 감시해 변경 시 해당
+ * .gaon 파일을 재생성한다. 반환 핸들의 close() 로 멈춘다.
+ */
+export declare function startDev(deps: DevDeps): Promise<DevHandle>;
+/** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
+export declare function resolveDevLayout(cwd: string): DevLayout;
+export interface DevCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    /** 프로세스 시그널 등록·해제(테스트에서 주입 가능). 기본 process. */
+    readonly signals?: {
+        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
+    };
+}
+/**
+ * `gaon dev` 진입점. cwd 관례로 레이아웃을 엮고 워치 루프를 띄운 뒤
+ * SIGINT/SIGTERM 에 graceful stop. 프로세스는 워처가 살아 있는 동안
+ * 유지된다(활성 핸들). 반환 프라미스는 종료 시 resolve.
+ */
+export declare function runDevCommand(opts?: DevCommandOptions): Promise<void>;

package/dist/dev.js

@@ -0,0 +1,153 @@
+/**
+ * @gaonjs/cli · `gaon dev` — .gaon 갱신 파이프라인 (M3)
+ *
+ * 파일 워처(@gaonjs/data watchDir) → 재생성(tables.d.ts·routes.d.ts) →
+ * 디스크 mtime 갱신 → 편집기 tsserver 자동 반영(§6.3, 열린 질문 3).
+ *
+ * 오케스트레이션은 주입(deps)으로 순수하게 유지하고(테스트 용이·dbCli
+ * 패턴과 동일), CLI 진입점이 cwd 관례로 실제 경로·재생성기를 엮는다.
+ * 실제 웹 서버·Vite·Docker 인프라 기동은 후속 마일스톤이다 — M3 는
+ * 타입 브리지 갱신 루프만 담당한다.
+ */
+import { readdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { generateTablesDts, watchDir } from '@gaonjs/data';
+import { generateRoutesDts } from '@gaonjs/web';
+import { registerTsResolve } from './tsResolve.js';
+const isSchemaChange = (f) => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts') && !f.includes('.gaon');
+const isRoutesChange = (f) => !f.includes('.gaon') &&
+    f.endsWith('.ts') &&
+    !f.endsWith('.d.ts') &&
+    !f.endsWith('.test.ts') &&
+    (f === 'routes.ts' || f.startsWith('controllers'));
+/**
+ * 초기 1회 전체 재생성 후, 스키마·앱 라우트를 감시해 변경 시 해당
+ * .gaon 파일을 재생성한다. 반환 핸들의 close() 로 멈춘다.
+ */
+export async function startDev(deps) {
+    const { layout } = deps;
+    const handles = [];
+    // 1) 초기 전체 재생성 — 개발 서버가 뜨자마자 타입 체인이 최신이 되게.
+    if (layout.schemaDir) {
+        await deps.regenerateTables(layout.schemaDir, layout.tablesOut);
+        deps.log({ kind: 'regen', target: 'tables' });
+    }
+    for (const app of layout.apps) {
+        await deps.regenerateRoutes(app.appDir, app.routesOut);
+        deps.log({ kind: 'regen', target: 'routes', app: app.name });
+    }
+    // 2) 스키마 워치 → tables.d.ts 재생성.
+    if (layout.schemaDir) {
+        const schemaDir = layout.schemaDir;
+        handles.push(deps.watch(schemaDir, {
+            filter: isSchemaChange,
+            onChange: async () => {
+                await deps.regenerateTables(schemaDir, layout.tablesOut);
+                deps.log({ kind: 'regen', target: 'tables' });
+            },
+            onError: deps.onError,
+        }));
+    }
+    // 3) 앱별 워치 → routes.d.ts 재생성(자기 앱만).
+    for (const app of layout.apps) {
+        handles.push(deps.watch(app.appDir, {
+            filter: isRoutesChange,
+            onChange: async () => {
+                await deps.regenerateRoutes(app.appDir, app.routesOut);
+                deps.log({ kind: 'regen', target: 'routes', app: app.name });
+            },
+            onError: deps.onError,
+        }));
+    }
+    deps.log({ kind: 'ready', schema: !!layout.schemaDir, apps: layout.apps.map((a) => a.name) });
+    return {
+        close() {
+            for (const h of handles)
+                h.close();
+            deps.log({ kind: 'stopped' });
+        },
+    };
+}
+/** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
+export function resolveDevLayout(cwd) {
+    const root = resolve(cwd);
+    const schemaDirPath = join(root, 'domain', 'schema');
+    const appsDir = join(root, 'apps');
+    const apps = [];
+    if (existsSync(appsDir)) {
+        for (const entry of readdirSync(appsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const appDir = join(appsDir, entry.name);
+            if (!existsSync(join(appDir, 'routes.ts')))
+                continue;
+            apps.push({
+                name: entry.name,
+                appDir,
+                routesOut: join(appDir, '.gaon', 'routes.d.ts'),
+            });
+        }
+    }
+    return {
+        schemaDir: existsSync(schemaDirPath) ? schemaDirPath : undefined,
+        tablesOut: join(root, '.gaon', 'tables.d.ts'),
+        apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
+    };
+}
+/** 사람이 읽는 이벤트 텍스트. */
+function humanEvent(e) {
+    switch (e.kind) {
+        case 'ready': {
+            const parts = [];
+            if (e.schema)
+                parts.push('schema→tables.d.ts');
+            for (const a of e.apps)
+                parts.push(`${a}→routes.d.ts`);
+            const what = parts.length ? parts.join(', ') : '(감시 대상 없음 — domain/schema·apps/* 확인)';
+            return `  gaon dev · 워치 시작 — ${what}\n  파일을 저장하면 .gaon 이 재생성되고 편집기가 자동 반영합니다. (Ctrl+C 종료)`;
+        }
+        case 'regen':
+            return e.target === 'tables'
+                ? '  ↻ tables.d.ts 재생성'
+                : `  ↻ ${e.app}/.gaon/routes.d.ts 재생성`;
+        case 'stopped':
+            return '  gaon dev · 종료';
+    }
+}
+/**
+ * `gaon dev` 진입점. cwd 관례로 레이아웃을 엮고 워치 루프를 띄운 뒤
+ * SIGINT/SIGTERM 에 graceful stop. 프로세스는 워처가 살아 있는 동안
+ * 유지된다(활성 핸들). 반환 프라미스는 종료 시 resolve.
+ */
+export async function runDevCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = opts.json ?? false;
+    const signals = opts.signals ?? process;
+    registerTsResolve(); // 사용자 .ts 의 `.js` 상대 import 를 런타임에 해석
+    const layout = resolveDevLayout(cwd);
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    const deps = {
+        layout,
+        regenerateTables: generateTablesDts,
+        regenerateRoutes: generateRoutesDts,
+        watch: watchDir,
+        log: emit,
+        onError: (err) => process.stderr.write(`  ✗ ${err.message}\n`),
+    };
+    const handle = await startDev(deps);
+    await new Promise((resolvePromise) => {
+        const stop = () => {
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            handle.close();
+            resolvePromise();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { runDevCommand, startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type DevCommandOptions, } from "./dev.js";
+export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
 export interface RoadmapReport {
     readonly name: "gaon";
     readonly version: string;

package/dist/index.js

@@ -1,14 +1,19 @@
 /**
  * @gaonjs/cli — Gaon CLI 구현.
  *
- * M1(현재) 스텁: 로드맵·개발 상태·참여 안내를 출력한다.
- * 모든 명령은 `--json` 출력을 함께 제공한다 (CLAUDE.md §4).
- * 실제 제너레이터·스캐폴딩은 로드맵 이후 마일스톤에서 구현한다.
+ * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M3 부터
+ * `gaon dev` 가 실제로 동작한다 — .gaon 타입 브리지(tables·routes)를
+ * 감시·재생성한다(dev.ts). 모든 명령은 `--json` 출력을 함께 제공한다
+ * (CLAUDE.md §4). 스캐폴딩·나머지 제너레이터는 이후 마일스톤이다.
  *
  * 표시 버전은 호출자(파사드)가 주입한다 — 사용자가 설치한 패키지
  * (`gaonjs`) 버전을 그대로 보여주기 위함. 미주입 시 core 버전을 쓴다.
  */
 import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
+import { runDevCommand } from "./dev.js";
+import { runCheckCommand } from "./check.js";
+export { runDevCommand, startDev, resolveDevLayout, } from "./dev.js";
+export { runCheck, runCheckCommand, } from "./check.js";
 /** `--json` 출력용 구조화 리포트. */
 export function roadmapReport(version = VERSION) {
     return {
@@ -52,6 +57,9 @@ function renderHelp(version = VERSION) {
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
+        "    gaon dev           .gaon 타입 브리지를 감시·재생성 (스키마·라우트)",
+        "    gaon dev --json    재생성 이벤트를 JSON 으로 출력",
+        "    gaon check         .gaon 재생성 후 타입 검사 (CI·AI 정합)",
         "    gaon --json        같은 정보를 JSON 으로 출력",
         "    gaon --version     버전 출력",
         "    gaon --help        이 도움말",
@@ -63,6 +71,29 @@ function renderHelp(version = VERSION) {
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
+    // `gaon dev` — .gaon 갱신 파이프라인(장기 실행). 워처가 활성 핸들로
+    // 프로세스를 살려 두고, SIGINT 로 종료된다. 에러는 stderr + exit 1.
+    if (argv[0] === "dev") {
+        void runDevCommand({ json: argv.includes("--json") }).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon dev 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
+    // `gaon check` — .gaon 재생성 후 타입 검사(§13.4-5). 종료 코드로 결과 전달.
+    if (argv[0] === "check") {
+        void runCheckCommand({ json: argv.includes("--json") })
+            .then((code) => {
+            process.exitCode = code;
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`  ✗ gaon check 실패: ${msg}\n`);
+            process.exitCode = 1;
+        });
+        return;
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         process.stdout.write(renderHelp(version) + "\n");
         return;

package/dist/tsResolve.d.ts

@@ -0,0 +1,7 @@
+type NextResolve = (specifier: string, context: unknown) => unknown | Promise<unknown>;
+export declare function resolve(specifier: string, context: {
+    parentURL?: string;
+}, nextResolve: NextResolve): Promise<unknown>;
+/** 이 모듈을 ESM resolve 훅으로 등록한다(한 프로세스에서 1회). */
+export declare function registerTsResolve(): void;
+export {};

package/dist/tsResolve.js

@@ -0,0 +1,35 @@
+/**
+ * @gaonjs/cli · TS 상대경로 해석 훅 (M3)
+ *
+ * 생성기(tables·routes)는 사용자 스키마·컨트롤러 .ts 를 런타임 동적
+ * import 해 구조를 읽는다. TS-for-ESM 관례상 상대 import 는 `.js` 로
+ * 쓰지만(`import { Post } from '../models/post.js'`), 개발 중 소스는
+ * `.ts` 다 — Node 는 `.js`→`.ts` 재매핑을 하지 않아 그대로면 모듈을
+ * 못 찾는다(vitest 는 Vite 가 재작성해 문제 없음, 실 gaon dev/check 만
+ * 해당). 이 훅이 `.js` 가 없고 형제 `.ts` 가 있으면 `.ts` 로 넘긴다.
+ *
+ * bare 지정자(@gaonjs/data 등)와 실재하는 `.js`(컴파일된 프로덕션)는
+ * 건드리지 않는다 — 그 경우 훅은 무동작이다.
+ */
+import { existsSync } from 'node:fs';
+import { register } from 'node:module';
+import { fileURLToPath } from 'node:url';
+export async function resolve(specifier, context, nextResolve) {
+    if (/\.js$/.test(specifier) &&
+        (specifier.startsWith('./') || specifier.startsWith('../')) &&
+        context.parentURL) {
+        const jsPath = fileURLToPath(new URL(specifier, context.parentURL));
+        if (!existsSync(jsPath) && existsSync(jsPath.replace(/\.js$/, '.ts'))) {
+            return nextResolve(specifier.replace(/\.js$/, '.ts'), context);
+        }
+    }
+    return nextResolve(specifier, context);
+}
+let registered = false;
+/** 이 모듈을 ESM resolve 훅으로 등록한다(한 프로세스에서 1회). */
+export function registerTsResolve() {
+    if (registered)
+        return;
+    registered = true;
+    register(import.meta.url);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@gaonjs/core": "0.1.2"
+    "@gaonjs/core": "0.1.2",
+    "@gaonjs/data": "0.2.0",
+    "@gaonjs/web": "0.1.3"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"