@mandujs/core 0.11.0 → 0.12.1

package/README.ko.md

@@ -25,11 +25,16 @@ bun add @mandujs/core
 
 ```
 @mandujs/core
-├── spec/      # Spec 스키마 및 로딩
-├── generator/ # 코드 생성
+├── router/    # 파일 시스템 기반 라우팅
 ├── guard/     # 아키텍처 검사 및 자동 수정
-├── runtime/   # 서버 및 라우터
-└── report/    # Guard 리포트 생성
+├── runtime/   # 서버, SSR, 스트리밍
+├── filling/   # 핸들러 체인 API
+├── contract/  # 타입 안전 API 계약
+├── content/   # Content Layer - 빌드 타임 콘텐츠 로딩 🆕
+├── bundler/   # 클라이언트 번들링, HMR
+├── client/    # Island 하이드레이션, 클라이언트 라우터
+├── brain/     # Doctor, Watcher, 아키텍처 분석
+└── change/    # 트랜잭션 & 히스토리
 ```
 
 ## Spec 모듈
@@ -133,6 +138,73 @@ if (!result.passed) {
 | `COMPONENT_NOT_FOUND` | 컴포넌트 파일 없음 | ❌ |
 | `SLOT_NOT_FOUND` | slot 파일 없음 | ✅ |
 
+## Content Layer 🆕
+
+Astro에서 영감받은 빌드 타임 콘텐츠 로딩 시스템.
+
+```typescript
+// content.config.ts
+import { defineContentConfig, glob, file, api } from "@mandujs/core/content";
+import { z } from "zod";
+
+const postSchema = z.object({
+  title: z.string(),
+  date: z.coerce.date(),
+  tags: z.array(z.string()).default([]),
+});
+
+export default defineContentConfig({
+  collections: {
+    // Markdown 파일 (프론트매터 지원)
+    posts: {
+      loader: glob({ pattern: "content/posts/**/*.md" }),
+      schema: postSchema,
+    },
+    // 단일 JSON/YAML 파일
+    settings: {
+      loader: file({ path: "data/settings.json" }),
+    },
+    // 외부 API
+    products: {
+      loader: api({
+        url: "https://api.example.com/products",
+        cacheTTL: 3600,
+      }),
+    },
+  },
+});
+```
+
+### 콘텐츠 조회
+
+```typescript
+import { getCollection, getEntry } from "@mandujs/core/content";
+
+// 전체 컬렉션 조회
+const posts = await getCollection("posts");
+
+// 단일 엔트리 조회
+const post = await getEntry("posts", "hello-world");
+console.log(post?.data.title, post?.body);
+```
+
+### 내장 로더
+
+| 로더 | 설명 | 예시 |
+|------|------|------|
+| `file()` | 단일 파일 (JSON, YAML, TOML) | `file({ path: "data/config.json" })` |
+| `glob()` | 패턴 매칭 (Markdown, JSON) | `glob({ pattern: "content/**/*.md" })` |
+| `api()` | HTTP API (캐싱 지원) | `api({ url: "https://...", cacheTTL: 3600 })` |
+
+### 주요 기능
+
+- **Digest 기반 캐싱**: 변경된 파일만 재파싱
+- **Zod 검증**: 스키마 기반 타입 안전 콘텐츠
+- **프론트매터 지원**: Markdown YAML 프론트매터
+- **Dev 모드 감시**: 콘텐츠 변경 시 자동 리로드
+
+---
+
 ## Contract 모듈
 
 Zod 기반 계약(Contract) 정의 및 타입 안전 클라이언트 생성.
@@ -209,6 +281,11 @@ import type {
   GuardViolation,
   GenerateResult,
   AutoCorrectResult,
+  // Content Layer
+  DataEntry,
+  ContentConfig,
+  CollectionConfig,
+  Loader,
 } from "@mandujs/core";
 ```
 

package/README.md

@@ -81,6 +81,8 @@ const handlers = Mandu.handler(userContract, {
 ├── runtime/         # Server, SSR, streaming
 ├── filling/         # Handler chain API (Mandu.filling())
 ├── contract/        # Type-safe API contracts
+├── content/         # Content Layer - build-time content loading 🆕
+│   └── loaders      # file(), glob(), api() loaders
 ├── bundler/         # Client bundling, HMR
 ├── client/          # Island hydration, client router
 ├── brain/           # Doctor, Watcher, Architecture analyzer
@@ -453,6 +455,78 @@ function Navigation() {
 
 ---
 
+## Content Layer 🆕
+
+Astro-inspired build-time content loading system.
+
+```typescript
+// content.config.ts
+import { defineContentConfig, glob, file, api } from "@mandujs/core/content";
+import { z } from "zod";
+
+const postSchema = z.object({
+  title: z.string(),
+  date: z.coerce.date(),
+  tags: z.array(z.string()).default([]),
+});
+
+export default defineContentConfig({
+  collections: {
+    // Markdown files with frontmatter
+    posts: {
+      loader: glob({ pattern: "content/posts/**/*.md" }),
+      schema: postSchema,
+    },
+    // Single JSON/YAML file
+    settings: {
+      loader: file({ path: "data/settings.json" }),
+    },
+    // External API
+    products: {
+      loader: api({
+        url: "https://api.example.com/products",
+        headers: () => ({ Authorization: `Bearer ${process.env.API_KEY}` }),
+        cacheTTL: 3600,
+      }),
+    },
+  },
+});
+```
+
+### Querying Content
+
+```typescript
+import { getCollection, getEntry } from "@mandujs/core/content";
+
+// Get all entries
+const posts = await getCollection("posts");
+posts.forEach(post => {
+  console.log(post.id, post.data.title);
+});
+
+// Get single entry
+const post = await getEntry("posts", "hello-world");
+console.log(post?.data.title, post?.body);
+```
+
+### Built-in Loaders
+
+| Loader | Description | Example |
+|--------|-------------|---------|
+| `file()` | Single file (JSON, YAML, TOML) | `file({ path: "data/config.json" })` |
+| `glob()` | Pattern matching (Markdown, JSON) | `glob({ pattern: "content/**/*.md" })` |
+| `api()` | HTTP API with caching | `api({ url: "https://...", cacheTTL: 3600 })` |
+
+### Features
+
+- **Digest-based caching**: Only re-parse changed files
+- **Zod validation**: Type-safe content with schema validation
+- **Frontmatter support**: YAML frontmatter in Markdown files
+- **Dev mode watching**: Auto-reload on content changes
+- **Incremental updates**: Efficient builds with change detection
+
+---
+
 ## Brain (AI Assistant)
 
 Doctor and architecture analyzer.
@@ -551,6 +625,13 @@ import type {
 
   // Filling
   ManduContext,
+
+  // Content Layer
+  DataEntry,
+  ContentConfig,
+  CollectionConfig,
+  Loader,
+  LoaderContext,
 } from "@mandujs/core";
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,12 +13,6 @@
   "files": [
     "src/**/*"
   ],
-  "scripts": {
-    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
-    "test:hydration": "bun test tests/hydration",
-    "test:streaming": "bun test tests/streaming-ssr",
-    "test:watch": "bun test --watch"
-  },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.0.0"
   },
@@ -35,7 +29,7 @@
     "directory": "packages/core"
   },
   "author": "konamgil",
-  "license": "MIT",
+  "license": "MPL-2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -49,8 +43,15 @@
   },
   "dependencies": {
     "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.2",
     "glob": "^13.0.0",
     "minimatch": "^10.1.1",
     "ollama": "^0.6.3"
+  },
+  "scripts": {
+    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
+    "test:hydration": "bun test tests/hydration",
+    "test:streaming": "bun test tests/streaming-ssr",
+    "test:watch": "bun test --watch"
   }
-}
+}

package/src/constants.ts

@@ -23,3 +23,18 @@ export const LIMITS = {
   ROUTER_PATTERN_CACHE: 200,
   ROUTER_PREFETCH_CACHE: 500,
 } as const;
+
+export const CONTENT = {
+  /** 로더 기본 타임아웃 (ms) */
+  LOADER_TIMEOUT: 10000,
+  /** 데이터 스토어 파일 경로 */
+  STORE_FILE: ".mandu/content-store.json",
+  /** 메타 스토어 파일 경로 */
+  META_FILE: ".mandu/content-meta.json",
+  /** 저장 디바운스 (ms) */
+  DEBOUNCE_SAVE: 500,
+  /** 기본 콘텐츠 디렉토리 */
+  DEFAULT_DIR: "content",
+  /** API 로더 기본 캐시 TTL (초) */
+  API_CACHE_TTL: 3600,
+} as const;

package/src/content/content-layer.ts

@@ -0,0 +1,314 @@
+/**
+ * ContentLayer - 콘텐츠 레이어 메인 클래스
+ *
+ * 빌드 타임에 모든 컬렉션을 로드하고 관리
+ * getCollection(), getEntry() API 제공
+ */
+
+import type {
+  ContentConfig,
+  CollectionConfig,
+  DataEntry,
+  ManduContentConfig,
+  ContentWatcher,
+  RenderedContent,
+} from "./types";
+import { LoaderError } from "./types";
+import { ContentDataStore, createDataStore } from "./data-store";
+import { ContentMetaStore, createMetaStore } from "./meta-store";
+import { createLoaderContext, createSimpleMarkdownRenderer } from "./loader-context";
+import { CONTENT } from "../constants";
+import type { ZodSchema } from "zod";
+import * as path from "path";
+
+/**
+ * ContentLayer 옵션
+ */
+export interface ContentLayerOptions {
+  /** 콘텐츠 설정 */
+  contentConfig: ContentConfig;
+  /** Mandu 설정 */
+  manduConfig: ManduContentConfig;
+  /** Markdown 렌더러 (선택) */
+  markdownRenderer?: (content: string) => Promise<RenderedContent>;
+  /** 파일 감시자 (dev 모드) */
+  watcher?: ContentWatcher;
+}
+
+/**
+ * ContentLayer 클래스
+ *
+ * 빌드 타임 콘텐츠 로딩 및 관리
+ */
+export class ContentLayer {
+  private contentConfig: ContentConfig;
+  private manduConfig: ManduContentConfig;
+  private dataStore: ContentDataStore;
+  private metaStore: ContentMetaStore;
+  private markdownRenderer: (content: string) => Promise<RenderedContent>;
+  private watcher?: ContentWatcher;
+  private loaded: boolean = false;
+  private loading: Promise<void> | null = null;
+
+  constructor(options: ContentLayerOptions) {
+    const { contentConfig, manduConfig, markdownRenderer, watcher } = options;
+
+    this.contentConfig = contentConfig;
+    this.manduConfig = manduConfig;
+    this.watcher = watcher;
+    this.markdownRenderer = markdownRenderer ?? createSimpleMarkdownRenderer();
+
+    // 스토어 초기화
+    const storeFile = path.join(manduConfig.root, CONTENT.STORE_FILE);
+    const metaFile = path.join(manduConfig.root, CONTENT.META_FILE);
+
+    this.dataStore = createDataStore({
+      filePath: storeFile,
+      autoSave: true,
+      saveDebounce: CONTENT.DEBOUNCE_SAVE,
+    });
+
+    this.metaStore = createMetaStore({
+      filePath: metaFile,
+      autoSave: true,
+    });
+  }
+
+  /**
+   * 모든 컬렉션 로드
+   */
+  async load(): Promise<void> {
+    // 이미 로딩 중이면 기다림
+    if (this.loading) {
+      return this.loading;
+    }
+
+    // 이미 로드됨
+    if (this.loaded) {
+      return;
+    }
+
+    this.loading = this.doLoad();
+    await this.loading;
+    this.loading = null;
+    this.loaded = true;
+  }
+
+  private async doLoad(): Promise<void> {
+    // 캐시에서 로드
+    await Promise.all([this.dataStore.load(), this.metaStore.load()]);
+
+    const collections = Object.entries(this.contentConfig.collections);
+
+    // 병렬로 모든 컬렉션 로드
+    await Promise.all(
+      collections.map(([name, config]) => this.loadCollection(name, config))
+    );
+
+    // 저장
+    await Promise.all([this.dataStore.save(), this.metaStore.save()]);
+  }
+
+  /**
+   * 단일 컬렉션 로드
+   */
+  private async loadCollection(name: string, config: CollectionConfig): Promise<void> {
+    const { loader, schema } = config;
+
+    // 로더 스키마와 컬렉션 스키마 병합 (컬렉션 우선)
+    let finalSchema: ZodSchema | undefined = schema;
+    if (!finalSchema && loader.schema) {
+      finalSchema =
+        typeof loader.schema === "function" ? await loader.schema() : loader.schema;
+    }
+
+    // LoaderContext 생성
+    const context = createLoaderContext({
+      collection: name,
+      store: this.dataStore.getStore(name),
+      meta: this.metaStore.getStore(name),
+      config: this.manduConfig,
+      schema: finalSchema,
+      markdownRenderer: this.markdownRenderer,
+      watcher: this.watcher,
+    });
+
+    try {
+      // 타임아웃 처리
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new LoaderError(`Loader "${loader.name}" timed out`, name)),
+          CONTENT.LOADER_TIMEOUT
+        );
+      });
+
+      await Promise.race([loader.load(context), timeoutPromise]);
+
+      context.logger.info(`Loaded ${context.store.size()} entries`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      context.logger.error(`Failed to load: ${message}`);
+
+      if (error instanceof LoaderError) {
+        throw error;
+      }
+
+      throw new LoaderError(`Failed to load collection "${name}": ${message}`, name);
+    }
+  }
+
+  /**
+   * 단일 컬렉션 다시 로드
+   */
+  async reloadCollection(name: string): Promise<void> {
+    const config = this.contentConfig.collections[name];
+    if (!config) {
+      throw new Error(`Collection "${name}" not found`);
+    }
+
+    await this.loadCollection(name, config);
+    await this.dataStore.save();
+    await this.metaStore.save();
+  }
+
+  /**
+   * 컬렉션의 모든 엔트리 조회
+   */
+  getCollection<T = Record<string, unknown>>(
+    collection: string
+  ): Array<DataEntry<T>> {
+    this.ensureLoaded();
+
+    const store = this.dataStore.getStore(collection);
+    return store.values<T>();
+  }
+
+  /**
+   * 컬렉션에서 단일 엔트리 조회
+   */
+  getEntry<T = Record<string, unknown>>(
+    collection: string,
+    id: string
+  ): DataEntry<T> | undefined {
+    this.ensureLoaded();
+
+    const store = this.dataStore.getStore(collection);
+    return store.get<T>(id);
+  }
+
+  /**
+   * 컬렉션 존재 여부 확인
+   */
+  hasCollection(collection: string): boolean {
+    return collection in this.contentConfig.collections;
+  }
+
+  /**
+   * 모든 컬렉션 이름 조회
+   */
+  getCollectionNames(): string[] {
+    return Object.keys(this.contentConfig.collections);
+  }
+
+  /**
+   * 컬렉션 통계
+   */
+  getStats(): {
+    collections: number;
+    totalEntries: number;
+    byCollection: Record<string, number>;
+  } {
+    this.ensureLoaded();
+
+    const byCollection: Record<string, number> = {};
+    let totalEntries = 0;
+
+    for (const name of this.getCollectionNames()) {
+      const store = this.dataStore.getStore(name);
+      const count = store.size();
+      byCollection[name] = count;
+      totalEntries += count;
+    }
+
+    return {
+      collections: Object.keys(byCollection).length,
+      totalEntries,
+      byCollection,
+    };
+  }
+
+  /**
+   * 로드 확인
+   */
+  private ensureLoaded(): void {
+    if (!this.loaded) {
+      throw new Error(
+        "ContentLayer not loaded. Call await contentLayer.load() first."
+      );
+    }
+  }
+
+  /**
+   * 리소스 정리
+   */
+  dispose(): void {
+    this.dataStore.dispose();
+    this.watcher?.close();
+  }
+}
+
+/**
+ * ContentLayer 팩토리
+ */
+export function createContentLayer(options: ContentLayerOptions): ContentLayer {
+  return new ContentLayer(options);
+}
+
+// ============================================================================
+// 전역 ContentLayer 인스턴스 (싱글톤)
+// ============================================================================
+
+let globalContentLayer: ContentLayer | null = null;
+
+/**
+ * 전역 ContentLayer 설정
+ */
+export function setGlobalContentLayer(layer: ContentLayer): void {
+  globalContentLayer = layer;
+}
+
+/**
+ * 전역 ContentLayer 조회
+ */
+export function getGlobalContentLayer(): ContentLayer | null {
+  return globalContentLayer;
+}
+
+/**
+ * 컬렉션 조회 (전역 ContentLayer 사용)
+ */
+export async function getCollection<T = Record<string, unknown>>(
+  collection: string
+): Promise<Array<DataEntry<T>>> {
+  if (!globalContentLayer) {
+    throw new Error("ContentLayer not initialized. Call setGlobalContentLayer() first.");
+  }
+
+  await globalContentLayer.load();
+  return globalContentLayer.getCollection<T>(collection);
+}
+
+/**
+ * 단일 엔트리 조회 (전역 ContentLayer 사용)
+ */
+export async function getEntry<T = Record<string, unknown>>(
+  collection: string,
+  id: string
+): Promise<DataEntry<T> | undefined> {
+  if (!globalContentLayer) {
+    throw new Error("ContentLayer not initialized. Call setGlobalContentLayer() first.");
+  }
+
+  await globalContentLayer.load();
+  return globalContentLayer.getEntry<T>(collection, id);
+}