@mandujs/core 0.3.3 → 0.4.0

package/src/filling/filling.ts

@@ -15,10 +15,14 @@ export type Guard = (ctx: ManduContext) => symbol | Response | Promise<symbol |
 /** HTTP methods */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 
-interface FillingConfig {
+/** Loader function type - SSR 데이터 로딩 */
+export type Loader<T = unknown> = (ctx: ManduContext) => T | Promise<T>;
+
+interface FillingConfig<TLoaderData = unknown> {
   handlers: Map<HttpMethod, Handler>;
   guards: Guard[];
   methodGuards: Map<HttpMethod, Guard[]>;
+  loader?: Loader<TLoaderData>;
 }
 
 /**
@@ -30,14 +34,64 @@ interface FillingConfig {
  *   .get(ctx => ctx.ok({ message: 'Hello!' }))
  *   .post(ctx => ctx.created({ id: 1 }))
  * ```
+ *
+ * @example with loader
+ * ```typescript
+ * export default Mandu.filling<{ todos: Todo[] }>()
+ *   .loader(async (ctx) => {
+ *     const todos = await db.todos.findMany();
+ *     return { todos };
+ *   })
+ *   .get(ctx => ctx.ok(ctx.get('loaderData')))
+ * ```
  */
-export class ManduFilling {
-  private config: FillingConfig = {
+export class ManduFilling<TLoaderData = unknown> {
+  private config: FillingConfig<TLoaderData> = {
     handlers: new Map(),
     guards: [],
     methodGuards: new Map(),
   };
 
+  // ============================================
+  // 🥟 SSR Loader
+  // ============================================
+
+  /**
+   * Define SSR data loader
+   * 페이지 렌더링 전 서버에서 데이터를 로드합니다.
+   * 로드된 데이터는 클라이언트로 전달되어 hydration에 사용됩니다.
+   *
+   * @example
+   * ```typescript
+   * .loader(async (ctx) => {
+   *   const todos = await db.todos.findMany();
+   *   return { todos, user: ctx.get('user') };
+   * })
+   * ```
+   */
+  loader(loaderFn: Loader<TLoaderData>): this {
+    this.config.loader = loaderFn;
+    return this;
+  }
+
+  /**
+   * Execute loader and return data
+   * @internal Used by SSR runtime
+   */
+  async executeLoader(ctx: ManduContext): Promise<TLoaderData | undefined> {
+    if (!this.config.loader) {
+      return undefined;
+    }
+    return await this.config.loader(ctx);
+  }
+
+  /**
+   * Check if loader is defined
+   */
+  hasLoader(): boolean {
+    return !!this.config.loader;
+  }
+
   // ============================================
   // 🥟 HTTP Method Handlers
   // ============================================
@@ -242,9 +296,26 @@ export const Mandu = {
    * export default Mandu.filling()
    *   .get(ctx => ctx.ok({ message: 'Hello!' }))
    * ```
+   *
+   * @example with loader data type
+   * ```typescript
+   * import { Mandu } from '@mandujs/core'
+   *
+   * interface LoaderData {
+   *   todos: Todo[];
+   *   user: User | null;
+   * }
+   *
+   * export default Mandu.filling<LoaderData>()
+   *   .loader(async (ctx) => {
+   *     const todos = await db.todos.findMany();
+   *     return { todos, user: null };
+   *   })
+   *   .get(ctx => ctx.ok(ctx.get('loaderData')))
+   * ```
    */
-  filling(): ManduFilling {
-    return new ManduFilling();
+  filling<TLoaderData = unknown>(): ManduFilling<TLoaderData> {
+    return new ManduFilling<TLoaderData>();
   },
 
   /**

package/src/index.ts

@@ -6,3 +6,5 @@ export * from "./report";
 export * from "./filling";
 export * from "./change";
 export * from "./error";
+export * from "./slot";
+export * from "./bundler";

package/src/runtime/ssr.ts

@@ -1,14 +1,120 @@
 import { renderToString } from "react-dom/server";
 import type { ReactElement } from "react";
+import type { BundleManifest } from "../bundler/types";
+import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 
 export interface SSROptions {
   title?: string;
   lang?: string;
+  /** 서버에서 로드한 데이터 (클라이언트로 전달) */
+  serverData?: Record<string, unknown>;
+  /** Hydration 설정 */
+  hydration?: HydrationConfig;
+  /** 번들 매니페스트 */
+  bundleManifest?: BundleManifest;
+  /** 라우트 ID (island 식별용) */
+  routeId?: string;
+  /** 추가 head 태그 */
+  headTags?: string;
+  /** 추가 body 끝 태그 */
+  bodyEndTags?: string;
+}
+
+/**
+ * SSR 데이터를 안전하게 직렬화
+ */
+function serializeServerData(data: Record<string, unknown>): string {
+  // XSS 방지를 위한 이스케이프
+  const json = JSON.stringify(data)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/'/g, "\\u0027");
+
+  return `<script id="__MANDU_DATA__" type="application/json">${json}</script>
+<script>window.__MANDU_DATA__ = JSON.parse(document.getElementById('__MANDU_DATA__').textContent);</script>`;
+}
+
+/**
+ * Hydration 스크립트 태그 생성
+ */
+function generateHydrationScripts(
+  routeId: string,
+  manifest: BundleManifest
+): string {
+  const scripts: string[] = [];
+
+  // Runtime 로드
+  if (manifest.shared.runtime) {
+    scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
+  }
+
+  // Vendor 로드
+  if (manifest.shared.vendor) {
+    scripts.push(`<script type="module" src="${manifest.shared.vendor}"></script>`);
+  }
+
+  // Island 번들 로드
+  const bundle = manifest.bundles[routeId];
+  if (bundle) {
+    // Preload (선택적)
+    scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);
+    scripts.push(`<script type="module" src="${bundle.js}"></script>`);
+  }
+
+  return scripts.join("\n");
+}
+
+/**
+ * Island 래퍼로 컨텐츠 감싸기
+ */
+export function wrapWithIsland(
+  content: string,
+  routeId: string,
+  priority: HydrationPriority = "visible"
+): string {
+  return `<div data-mandu-island="${routeId}" data-mandu-priority="${priority}">${content}</div>`;
 }
 
 export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const { title = "Mandu App", lang = "ko" } = options;
-  const content = renderToString(element);
+  const {
+    title = "Mandu App",
+    lang = "ko",
+    serverData,
+    hydration,
+    bundleManifest,
+    routeId,
+    headTags = "",
+    bodyEndTags = "",
+  } = options;
+
+  let content = renderToString(element);
+
+  // Island 래퍼 적용 (hydration 필요 시)
+  const needsHydration =
+    hydration && hydration.strategy !== "none" && routeId && bundleManifest;
+
+  if (needsHydration) {
+    content = wrapWithIsland(content, routeId, hydration.priority);
+  }
+
+  // 서버 데이터 스크립트
+  let dataScript = "";
+  if (serverData && routeId) {
+    const wrappedData = {
+      [routeId]: {
+        serverData,
+        timestamp: Date.now(),
+      },
+    };
+    dataScript = serializeServerData(wrappedData);
+  }
+
+  // Hydration 스크립트
+  let hydrationScripts = "";
+  if (needsHydration && bundleManifest) {
+    hydrationScripts = generateHydrationScripts(routeId, bundleManifest);
+  }
 
   return `<!doctype html>
 <html lang="${lang}">
@@ -16,9 +122,13 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
+  ${headTags}
 </head>
 <body>
   <div id="root">${content}</div>
+  ${dataScript}
+  ${hydrationScripts}
+  ${bodyEndTags}
 </body>
 </html>`;
 }
@@ -36,3 +146,33 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
   const html = renderToHTML(element, options);
   return createHTMLResponse(html);
 }
+
+/**
+ * Hydration이 포함된 SSR 렌더링
+ *
+ * @example
+ * ```typescript
+ * const response = await renderWithHydration(
+ *   <TodoList todos={todos} />,
+ *   {
+ *     title: "할일 목록",
+ *     routeId: "todos",
+ *     serverData: { todos },
+ *     hydration: { strategy: "island", priority: "visible" },
+ *     bundleManifest,
+ *   }
+ * );
+ * ```
+ */
+export async function renderWithHydration(
+  element: ReactElement,
+  options: SSROptions & {
+    routeId: string;
+    serverData: Record<string, unknown>;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
+): Promise<Response> {
+  const html = renderToHTML(element, options);
+  return createHTMLResponse(html);
+}

package/src/slot/corrector.ts

@@ -0,0 +1,282 @@
+/**
+ * Slot Content Corrector
+ * 슬롯 파일의 자동 수정 가능한 문제를 해결합니다.
+ */
+
+import type { SlotValidationIssue } from "./validator";
+
+export interface CorrectionResult {
+  corrected: boolean;
+  content: string;
+  appliedFixes: AppliedFix[];
+  remainingIssues: SlotValidationIssue[];
+}
+
+export interface AppliedFix {
+  code: string;
+  description: string;
+  before?: string;
+  after?: string;
+}
+
+// 금지된 import를 대체할 안전한 패턴
+const SAFE_ALTERNATIVES: Record<string, string> = {
+  fs: "// Use Bun.file() or Bun.write() instead of fs",
+  "node:fs": "// Use Bun.file() or Bun.write() instead of fs",
+  child_process: "// Use Bun.spawn() or Bun.spawnSync() instead",
+  "node:child_process": "// Use Bun.spawn() or Bun.spawnSync() instead",
+  cluster: "// Clustering should be handled at the infrastructure level",
+  "node:cluster": "// Clustering should be handled at the infrastructure level",
+  worker_threads: "// Use Bun workers or external job queues",
+  "node:worker_threads": "// Use Bun workers or external job queues",
+};
+
+/**
+ * 슬롯 내용을 자동 수정합니다.
+ */
+export function correctSlotContent(
+  content: string,
+  issues: SlotValidationIssue[]
+): CorrectionResult {
+  let correctedContent = content;
+  const appliedFixes: AppliedFix[] = [];
+  const remainingIssues: SlotValidationIssue[] = [];
+
+  for (const issue of issues) {
+    if (!issue.autoFixable) {
+      remainingIssues.push(issue);
+      continue;
+    }
+
+    const result = applyFix(correctedContent, issue);
+    if (result.fixed) {
+      correctedContent = result.content;
+      appliedFixes.push({
+        code: issue.code,
+        description: issue.message,
+        before: result.before,
+        after: result.after,
+      });
+    } else {
+      remainingIssues.push(issue);
+    }
+  }
+
+  return {
+    corrected: appliedFixes.length > 0,
+    content: correctedContent,
+    appliedFixes,
+    remainingIssues,
+  };
+}
+
+interface FixResult {
+  fixed: boolean;
+  content: string;
+  before?: string;
+  after?: string;
+}
+
+function applyFix(content: string, issue: SlotValidationIssue): FixResult {
+  switch (issue.code) {
+    case "FORBIDDEN_IMPORT":
+      return fixForbiddenImport(content, issue);
+
+    case "MISSING_MANDU_IMPORT":
+      return fixMissingManduImport(content);
+
+    case "MISSING_DEFAULT_EXPORT":
+      return fixMissingDefaultExport(content);
+
+    default:
+      return { fixed: false, content };
+  }
+}
+
+/**
+ * 금지된 import를 제거하고 주석으로 대체
+ */
+function fixForbiddenImport(
+  content: string,
+  issue: SlotValidationIssue
+): FixResult {
+  const lines = content.split("\n");
+
+  if (!issue.line) {
+    return { fixed: false, content };
+  }
+
+  const lineIndex = issue.line - 1;
+  const originalLine = lines[lineIndex];
+
+  // 어떤 금지된 모듈인지 찾기
+  let forbiddenModule = "";
+  for (const [module, alternative] of Object.entries(SAFE_ALTERNATIVES)) {
+    if (originalLine.includes(`'${module}'`) || originalLine.includes(`"${module}"`)) {
+      forbiddenModule = module;
+      break;
+    }
+  }
+
+  if (!forbiddenModule) {
+    return { fixed: false, content };
+  }
+
+  // import 문을 주석으로 대체
+  const alternative = SAFE_ALTERNATIVES[forbiddenModule];
+  lines[lineIndex] = `// REMOVED: ${originalLine.trim()}\n${alternative}`;
+
+  return {
+    fixed: true,
+    content: lines.join("\n"),
+    before: originalLine,
+    after: lines[lineIndex],
+  };
+}
+
+/**
+ * Mandu import 추가
+ */
+function fixMissingManduImport(content: string): FixResult {
+  const manduImport = `import { Mandu } from "@mandujs/core";\n`;
+
+  // 이미 다른 import가 있는지 확인
+  const hasImports = /^import\s+/m.test(content);
+
+  let newContent: string;
+  if (hasImports) {
+    // 첫 번째 import 앞에 추가
+    newContent = content.replace(/^(import\s+)/m, `${manduImport}$1`);
+  } else {
+    // 파일 맨 앞에 추가
+    newContent = manduImport + content;
+  }
+
+  return {
+    fixed: true,
+    content: newContent,
+    before: "(없음)",
+    after: manduImport.trim(),
+  };
+}
+
+/**
+ * default export 추가
+ */
+function fixMissingDefaultExport(content: string): FixResult {
+  // Mandu.filling()이 있는지 확인
+  const fillingMatch = content.match(/Mandu\s*\.\s*filling\s*\(\s*\)/);
+
+  if (!fillingMatch) {
+    // filling 패턴이 없으면 수정 불가
+    return { fixed: false, content };
+  }
+
+  // export default가 없는 Mandu.filling() 찾기
+  // 예: const handler = Mandu.filling()... -> export default Mandu.filling()...
+  const patterns = [
+    // const/let/var handler = Mandu.filling()
+    /^(\s*)(const|let|var)\s+\w+\s*=\s*(Mandu\s*\.\s*filling\s*\(\s*\))/m,
+    // 단독 Mandu.filling()
+    /^(\s*)(Mandu\s*\.\s*filling\s*\(\s*\))/m,
+  ];
+
+  for (const pattern of patterns) {
+    if (pattern.test(content)) {
+      const newContent = content.replace(pattern, "$1export default $3");
+      return {
+        fixed: true,
+        content: newContent,
+        before: content.match(pattern)?.[0],
+        after: newContent.match(/export default Mandu\.filling\(\)/)?.[0],
+      };
+    }
+  }
+
+  // 파일 끝에 export default 추가 시도
+  if (content.includes("Mandu.filling()") && !content.includes("export default")) {
+    // 마지막 세미콜론 또는 중괄호 뒤에 추가
+    const lastLine = content.trimEnd();
+    if (!lastLine.endsWith(";") && !lastLine.endsWith("}")) {
+      return { fixed: false, content };
+    }
+  }
+
+  return { fixed: false, content };
+}
+
+/**
+ * 여러 번의 수정 시도 (Self-correction loop)
+ */
+export async function runSlotCorrection(
+  content: string,
+  validateFn: (content: string) => { valid: boolean; issues: SlotValidationIssue[] },
+  maxRetries: number = 3
+): Promise<{
+  success: boolean;
+  finalContent: string;
+  attempts: number;
+  allFixes: AppliedFix[];
+  remainingIssues: SlotValidationIssue[];
+}> {
+  let currentContent = content;
+  let attempts = 0;
+  const allFixes: AppliedFix[] = [];
+
+  while (attempts < maxRetries) {
+    attempts++;
+
+    // 1. 검증
+    const validation = validateFn(currentContent);
+
+    if (validation.valid) {
+      return {
+        success: true,
+        finalContent: currentContent,
+        attempts,
+        allFixes,
+        remainingIssues: [],
+      };
+    }
+
+    // 2. 자동 수정 가능한 문제가 있는지 확인
+    const autoFixable = validation.issues.filter((i) => i.autoFixable);
+    if (autoFixable.length === 0) {
+      // 자동 수정 불가능한 문제만 남음
+      return {
+        success: false,
+        finalContent: currentContent,
+        attempts,
+        allFixes,
+        remainingIssues: validation.issues,
+      };
+    }
+
+    // 3. 수정 적용
+    const correction = correctSlotContent(currentContent, validation.issues);
+    allFixes.push(...correction.appliedFixes);
+
+    if (!correction.corrected) {
+      // 수정이 적용되지 않음
+      return {
+        success: false,
+        finalContent: currentContent,
+        attempts,
+        allFixes,
+        remainingIssues: validation.issues,
+      };
+    }
+
+    currentContent = correction.content;
+  }
+
+  // maxRetries 도달
+  const finalValidation = validateFn(currentContent);
+  return {
+    success: finalValidation.valid,
+    finalContent: currentContent,
+    attempts,
+    allFixes,
+    remainingIssues: finalValidation.issues,
+  };
+}

package/src/slot/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Slot Module
+ * 슬롯 파일 검증 및 자동 수정 기능
+ */
+
+export {
+  validateSlotContent,
+  summarizeValidationIssues,
+  type SlotValidationIssue,
+  type SlotValidationResult,
+} from "./validator";
+
+export {
+  correctSlotContent,
+  runSlotCorrection,
+  type CorrectionResult,
+  type AppliedFix,
+} from "./corrector";