@gaonjs/web 0.1.1 → 0.1.3

package/dist/controller.d.ts

@@ -0,0 +1,14 @@
+export interface Rendered<P> {
+    readonly page: string;
+    readonly props: P;
+}
+/** 액션 본문의 `this` — M3 최소는 render 만. */
+export interface ControllerContext {
+    render<P>(page: string, props: P): Rendered<P>;
+}
+/**
+ * 액션 객체를 그대로 반환하되, 본문의 `this` 를 ControllerContext 로
+ * 준다(ThisType). 런타임에서는 각 액션을 context 에 바인딩해, 실제
+ * 호출 시 `this.render` 가 동작하게 한다.
+ */
+export declare function controller<A extends object>(actions: A & ThisType<ControllerContext>): A;

package/dist/controller.js

@@ -0,0 +1,29 @@
+// @gaonjs/web · controller() 최소 런타임 (M3 — 최소 웹 레이어)
+//
+// 설계 §5.2: `controller({ async index() { return this.render(...) } })`.
+// 액션은 `this.render(page, props)` 로 페이지와 props 를 반환하고, 그
+// 반환 타입(Rendered<P>)이 타입 브리지(.gaon/routes.d.ts)를 거쳐 Vue
+// 페이지의 pageProps<K>() 로 흐른다(§6.2·§6.3).
+//
+// ThisType 주의(§13.4-1 의 model 교훈과 동형): 액션 제네릭에 제약을
+// 걸면 ThisType 추론이 조용히 붕괴한다 → **무제약 A + ThisType 교차**로
+// 둔다. 타입 회귀 테스트(controller.test-d.ts)로 고정한다.
+//
+// this.params·auth·redirect 등 나머지 실행 시맨틱은 후속 마일스톤이다.
+const context = {
+    render(page, props) {
+        return { page, props };
+    },
+};
+/**
+ * 액션 객체를 그대로 반환하되, 본문의 `this` 를 ControllerContext 로
+ * 준다(ThisType). 런타임에서는 각 액션을 context 에 바인딩해, 실제
+ * 호출 시 `this.render` 가 동작하게 한다.
+ */
+export function controller(actions) {
+    const bound = {};
+    for (const [name, fn] of Object.entries(actions)) {
+        bound[name] = typeof fn === 'function' ? fn.bind(context) : fn;
+    }
+    return bound;
+}

package/dist/generator.d.ts

@@ -0,0 +1,23 @@
+export interface DiscoveredRoute {
+    /** 라우트 맵 키 — `<controller>#<action>`. */
+    readonly key: string;
+    /** 이 컨트롤러의 import 바인딩 이름(파일 내 유일·유효 식별자). */
+    readonly binding: string;
+    /** `.gaon/routes.d.ts` 기준 컨트롤러 import 지정자(.js, posix). */
+    readonly importPath: string;
+    /** 컨트롤러 액션 이름. */
+    readonly action: string;
+}
+/** outDir(.gaon) 기준 상대 import 지정자 (.ts→.js, posix, ./·../ 보정). */
+export declare function toImportSpecifier(outDir: string, file: string): string;
+/** 컨트롤러 이름 → 파일 내 유효·유일 import 바인딩. */
+export declare function bindingName(controller: string): string;
+/**
+ * 앱 디렉터리를 스캔해 라우트 목록을 수집한다.
+ * routes.ts 가 없으면 빈 목록(앱에 라우트가 아직 없을 수 있다).
+ */
+export declare function collectRoutes(appDir: string, outDir: string): Promise<DiscoveredRoute[]>;
+/** 수집된 라우트 목록 → routes.d.ts 소스 텍스트. */
+export declare function renderRoutesDts(routes: DiscoveredRoute[]): string;
+/** 전 과정: 앱 스캔 → 렌더 → apps/<app>/.gaon/routes.d.ts 기록. 텍스트 반환. */
+export declare function generateRoutesDts(appDir: string, outFile: string): Promise<string>;

package/dist/generator.js

@@ -0,0 +1,120 @@
+// @gaonjs/web · routes.d.ts 생성기 (M3 — 타입 브리지, 앱별)
+//
+// 앱 하나(apps/<app>)의 `routes.ts` 를 실행해 참조 컨트롤러를 얻고,
+// 각 컨트롤러 파일(controllers/<name>.ts)의 default export 에서 **실제
+// 구현된 액션 키**를 읽어 `.gaon/routes.d.ts` 를 낳는다.
+//
+// 생성 파일은 **타입 참조만** 담는다(CLAUDE.md 규칙 3):
+//   '<ctrl>#<action>': (typeof <ctrl>)['<action>']
+// TanStack Router·Nuxt 가 검증한 방식이며, 참조만 담아 tsserver 부하가
+// 거의 없다(설계 §6.3). 실제 액션 타입 계산은 전부 추론에 맡긴다.
+import { readdir, stat } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** outDir(.gaon) 기준 상대 import 지정자 (.ts→.js, posix, ./·../ 보정). */
+export function toImportSpecifier(outDir, file) {
+    let rel = relative(resolve(outDir), resolve(file)).replace(/\\/g, '/');
+    rel = rel.replace(/\.ts$/, '.js');
+    if (!rel.startsWith('.'))
+        rel = './' + rel;
+    return rel;
+}
+/** 컨트롤러 이름 → 파일 내 유효·유일 import 바인딩. */
+export function bindingName(controller) {
+    return 'c_' + controller.replace(/[^A-Za-z0-9_]/g, '_');
+}
+/** ESM 캐시 우회 — 워치 재생성 시 편집 반영(§generator.ts 와 동일 기법). */
+async function importFresh(file) {
+    const st = await stat(file);
+    return (await import(`${pathToFileURL(file).href}?t=${st.mtimeMs}-${st.size}`));
+}
+function isRouteDef(v) {
+    return typeof v === 'object' && v !== null && Array.isArray(v.controllers);
+}
+/** default export(actions 객체)에서 함수 값을 가진 키만 액션으로 취한다. */
+function actionKeys(mod) {
+    const def = mod.default;
+    if (typeof def !== 'object' || def === null)
+        return [];
+    return Object.entries(def)
+        .filter(([, v]) => typeof v === 'function')
+        .map(([k]) => k)
+        .sort();
+}
+/**
+ * 앱 디렉터리를 스캔해 라우트 목록을 수집한다.
+ * routes.ts 가 없으면 빈 목록(앱에 라우트가 아직 없을 수 있다).
+ */
+export async function collectRoutes(appDir, outDir) {
+    const routesFile = join(resolve(appDir), 'routes.ts');
+    const controllersDir = join(resolve(appDir), 'controllers');
+    const routesMod = await importFresh(routesFile);
+    const def = routesMod.default;
+    if (!isRouteDef(def)) {
+        throw new Error(`[@gaonjs/web] ${routesFile} 의 default export 가 routes(...) 결과가 아닙니다.\n` +
+            `→ routes.ts 를 \`export default routes((r) => { ... })\` 형태로 작성하세요.`);
+    }
+    const existing = new Set(await listControllerFiles(controllersDir));
+    const found = [];
+    for (const ctrl of def.controllers) {
+        const file = join(controllersDir, `${ctrl}.ts`);
+        if (!existing.has(file)) {
+            throw new Error(`[@gaonjs/web] 라우트가 참조하는 컨트롤러가 없습니다: ${ctrl}\n` +
+                `→ ${file} 에 \`export default controller({ ... })\` 를 만드세요.`);
+        }
+        const mod = await importFresh(file);
+        const importPath = toImportSpecifier(outDir, file);
+        const binding = bindingName(ctrl);
+        for (const action of actionKeys(mod)) {
+            found.push({ key: `${ctrl}#${action}`, binding, importPath, action });
+        }
+    }
+    return found.sort((a, b) => a.key.localeCompare(b.key));
+}
+async function listControllerFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return []; // controllers 디렉터리가 아직 없을 수 있다
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts'))
+        .map((e) => join(dir, e.name));
+}
+/** 수집된 라우트 목록 → routes.d.ts 소스 텍스트. */
+export function renderRoutesDts(routes) {
+    const lines = [];
+    lines.push('// AUTO-GENERATED by @gaonjs/web — 편집 금지.');
+    lines.push('// `gaon check` / `gaon dev` 가 검사·개발 중 이 파일을 재생성한다(§6.3).');
+    // 컨트롤러별 import (바인딩 유일) — 등장 순서 안정화.
+    const seen = new Map(); // binding → importPath
+    for (const r of routes)
+        if (!seen.has(r.binding))
+            seen.set(r.binding, r.importPath);
+    for (const [binding, importPath] of seen) {
+        lines.push(`import type ${binding} from '${importPath}'`);
+    }
+    lines.push('');
+    lines.push('declare global {');
+    lines.push('  interface GaonRouteMap {');
+    for (const r of routes) {
+        lines.push(`    '${r.key}': (typeof ${r.binding})['${r.action}']`);
+    }
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
+    lines.push('export {}');
+    lines.push('');
+    return lines.join('\n');
+}
+/** 전 과정: 앱 스캔 → 렌더 → apps/<app>/.gaon/routes.d.ts 기록. 텍스트 반환. */
+export async function generateRoutesDts(appDir, outFile) {
+    const outDir = dirname(resolve(outFile));
+    const text = renderRoutesDts(await collectRoutes(appDir, outDir));
+    await mkdir(outDir, { recursive: true });
+    await writeFile(outFile, text, 'utf8');
+    return text;
+}

package/dist/index.d.ts

@@ -1,2 +1,5 @@
-export declare const version = "0.1.0";
+export declare const version: string;
 export declare const status: "planned";
+export { routes, type RouteBuilder, type RouteDef, type HttpMethod, } from "./routes.js";
+export { controller, type Rendered, type ControllerContext, } from "./controller.js";
+export { collectRoutes, renderRoutesDts, generateRoutesDts, toImportSpecifier, bindingName, type DiscoveredRoute, } from "./generator.js";

package/dist/index.js

@@ -1,8 +1,16 @@
 /**
  * @gaonjs/web — Gaon 웹 레이어 (Fastify 통합·라우팅·보안 기본값).
  *
- * 구현은 로드맵 M2 이후. 현재는 개발 상태만 노출하는 스텁이다.
+ * 전체 실행 레이어(HTTP 바인딩·미들웨어·render)는 후속 마일스톤이다.
+ * M3 에서는 타입 브리지 이음새만 놓는다: routes() DSL·controller() 헬퍼와
+ * routes.d.ts 생성기(§6.3).
  */
 import { VERSION } from "@gaonjs/core";
 export const version = VERSION;
 export const status = "planned";
+// 라우팅 DSL (M3 최소 — 타입 브리지용)
+export { routes, } from "./routes.js";
+// controller() 최소 런타임 (M3 — this.render)
+export { controller, } from "./controller.js";
+// routes.d.ts 생성기 (앱별 타입 브리지)
+export { collectRoutes, renderRoutesDts, generateRoutesDts, toImportSpecifier, bindingName, } from "./generator.js";

package/dist/routes.d.ts

@@ -0,0 +1,22 @@
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+export interface RouteBuilder {
+    /** Rails 식 리소스 라우팅 — 표준 액션을 컨트롤러 <name> 에 연결. */
+    resources(name: string): void;
+    /** 단수 리소스(세션 등). */
+    resource(name: string): void;
+    get(path: string, target: string): void;
+    post(path: string, target: string): void;
+    put(path: string, target: string): void;
+    patch(path: string, target: string): void;
+    delete(path: string, target: string): void;
+}
+export interface RouteDef {
+    /** 이 앱 라우트가 참조하는 컨트롤러 이름들(정렬·중복제거). 타입 브리지 입력. */
+    readonly controllers: readonly string[];
+}
+/**
+ * 라우트 정의 빌더를 실행해 참조 컨트롤러 목록을 수집한다.
+ * `get('/about', 'pages#about')` 처럼 `controller#action` 대상은
+ * `#` 앞부분(컨트롤러)만 취한다.
+ */
+export declare function routes(build: (r: RouteBuilder) => void): RouteDef;

package/dist/routes.js

@@ -0,0 +1,30 @@
+// @gaonjs/web · 라우팅 DSL (M3 최소 구현 — 타입 브리지용)
+//
+// 설계 §5.1 의 `routes((r) => { r.resources('posts') })` 형태다. M3 는
+// 타입 브리지(routes.d.ts) 생성을 위해 **어느 컨트롤러가 이 앱 라우트에
+// 참조되는지**만 기록하면 된다. 실제 라우팅 매칭·미들웨어·HTTP 바인딩은
+// @gaonjs/web 후속 마일스톤이다 — 여기서는 그 이음새만 놓는다.
+/**
+ * 라우트 정의 빌더를 실행해 참조 컨트롤러 목록을 수집한다.
+ * `get('/about', 'pages#about')` 처럼 `controller#action` 대상은
+ * `#` 앞부분(컨트롤러)만 취한다.
+ */
+export function routes(build) {
+    const controllers = new Set();
+    const addTarget = (target) => {
+        const ctrl = target.split('#')[0]?.trim();
+        if (ctrl)
+            controllers.add(ctrl);
+    };
+    const r = {
+        resources: (name) => void controllers.add(name),
+        resource: (name) => void controllers.add(name),
+        get: (_p, t) => addTarget(t),
+        post: (_p, t) => addTarget(t),
+        put: (_p, t) => addTarget(t),
+        patch: (_p, t) => addTarget(t),
+        delete: (_p, t) => addTarget(t),
+    };
+    build(r);
+    return { controllers: [...controllers].sort() };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/web",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Gaon 웹 레이어: Fastify 통합·파일 기반 라우팅·보안 기본값 (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@gaonjs/core": "0.1.1"
+    "@gaonjs/core": "0.1.2"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"