@mandujs/core 0.3.2 → 0.3.3

package/README.md

@@ -1,200 +1,200 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/konamgil/mandu/main/mandu_only_simbol.png" alt="Mandu" width="200" />
-</p>
-
-<h1 align="center">@mandujs/core</h1>
-
-<p align="center">
-  <strong>Mandu Framework Core</strong><br/>
-  Spec, Generator, Guard, Runtime, Filling
-</p>
-
-<p align="center">
-  English | <a href="./README.ko.md"><strong>한국어</strong></a>
-</p>
-
-## Installation
-
-```bash
-bun add @mandujs/core
-```
-
-> Typically used through `@mandujs/cli`. Direct usage is for advanced use cases.
-
-## Module Structure
-
-```
-@mandujs/core
-├── spec/      # Spec schema and loading
-├── generator/ # Code generation
-├── guard/     # Architecture checking and auto-correction
-├── runtime/   # Server and router
-└── report/    # Guard report generation
-```
-
-## Spec Module
-
-Route manifest schema definition and loading.
-
-```typescript
-import { loadManifest, RoutesManifest, RouteSpec } from "@mandujs/core";
-
-// Load and validate manifest
-const result = await loadManifest("spec/routes.manifest.json");
-
-if (result.success && result.data) {
-  const manifest: RoutesManifest = result.data;
-  manifest.routes.forEach((route: RouteSpec) => {
-    console.log(route.id, route.pattern, route.kind);
-  });
-}
-```
-
-### Lock File
-
-```typescript
-import { writeLock, readLock } from "@mandujs/core";
-
-// Write lock file
-const lock = await writeLock("spec/spec.lock.json", manifest);
-console.log(lock.routesHash);
-
-// Read lock file
-const existing = await readLock("spec/spec.lock.json");
-```
-
-## Generator Module
-
-Spec-based code generation.
-
-```typescript
-import { generateRoutes, GenerateResult } from "@mandujs/core";
-
-const result: GenerateResult = await generateRoutes(manifest, "./");
-
-console.log("Created:", result.created);
-console.log("Skipped:", result.skipped);  // Existing slot files
-```
-
-### Template Functions
-
-```typescript
-import {
-  generateApiHandler,
-  generateApiHandlerWithSlot,
-  generateSlotLogic,
-  generatePageComponent
-} from "@mandujs/core";
-
-// Generate API handler
-const code = generateApiHandler(route);
-
-// API handler with slot
-const codeWithSlot = generateApiHandlerWithSlot(route);
-
-// Slot logic file
-const slotCode = generateSlotLogic(route);
-```
-
-## Guard Module
-
-Architecture rule checking and auto-correction.
-
-```typescript
-import {
-  runGuardCheck,
-  runAutoCorrect,
-  GuardResult,
-  GuardViolation
-} from "@mandujs/core";
-
-// Run check
-const result: GuardResult = await runGuardCheck(manifest, "./");
-
-if (!result.passed) {
-  result.violations.forEach((v: GuardViolation) => {
-    console.log(`${v.rule}: ${v.message}`);
-  });
-
-  // Run auto-correction
-  const corrected = await runAutoCorrect(result.violations, manifest, "./");
-  console.log("Fixed:", corrected.steps);
-  console.log("Remaining violations:", corrected.remainingViolations);
-}
-```
-
-### Guard Rules
-
-| Rule ID | Description | Auto-correctable |
-|---------|-------------|------------------|
-| `SPEC_HASH_MISMATCH` | Spec and lock hash mismatch | ✅ |
-| `GENERATED_MANUAL_EDIT` | Manual edit to generated file | ✅ |
-| `HANDLER_NOT_FOUND` | Handler file not found | ❌ |
-| `COMPONENT_NOT_FOUND` | Component file not found | ❌ |
-| `SLOT_NOT_FOUND` | Slot file not found | ✅ |
-
-## Runtime Module
-
-Server startup and routing.
-
-```typescript
-import {
-  startServer,
-  registerApiHandler,
-  registerPageLoader
-} from "@mandujs/core";
-
-// Register API handler
-registerApiHandler("getUsers", async (req) => {
-  return { users: [] };
-});
-
-// Register page loader
-registerPageLoader("homePage", () => import("./pages/Home"));
-
-// Start server
-const server = startServer(manifest, { port: 3000 });
-
-// Stop
-server.stop();
-```
-
-## Report Module
-
-Guard result report generation.
-
-```typescript
-import { buildGuardReport } from "@mandujs/core";
-
-const report = buildGuardReport(guardResult, lockPath);
-console.log(report);  // Formatted text report
-```
-
-## Types
-
-```typescript
-import type {
-  RoutesManifest,
-  RouteSpec,
-  RouteKind,
-  SpecLock,
-  GuardResult,
-  GuardViolation,
-  GenerateResult,
-  AutoCorrectResult,
-} from "@mandujs/core";
-```
-
-## Requirements
-
-- Bun >= 1.0.0
-- React >= 18.0.0
-- Zod >= 3.0.0
-
-## Related Packages
-
-- [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI tool
-
-## License
-
-MIT
+<p align="center">
+  <img src="https://raw.githubusercontent.com/konamgil/mandu/main/mandu_only_simbol.png" alt="Mandu" width="200" />
+</p>
+
+<h1 align="center">@mandujs/core</h1>
+
+<p align="center">
+  <strong>Mandu Framework Core</strong><br/>
+  Spec, Generator, Guard, Runtime, Filling
+</p>
+
+<p align="center">
+  English | <a href="./README.ko.md"><strong>한국어</strong></a>
+</p>
+
+## Installation
+
+```bash
+bun add @mandujs/core
+```
+
+> Typically used through `@mandujs/cli`. Direct usage is for advanced use cases.
+
+## Module Structure
+
+```
+@mandujs/core
+├── spec/      # Spec schema and loading
+├── generator/ # Code generation
+├── guard/     # Architecture checking and auto-correction
+├── runtime/   # Server and router
+└── report/    # Guard report generation
+```
+
+## Spec Module
+
+Route manifest schema definition and loading.
+
+```typescript
+import { loadManifest, RoutesManifest, RouteSpec } from "@mandujs/core";
+
+// Load and validate manifest
+const result = await loadManifest("spec/routes.manifest.json");
+
+if (result.success && result.data) {
+  const manifest: RoutesManifest = result.data;
+  manifest.routes.forEach((route: RouteSpec) => {
+    console.log(route.id, route.pattern, route.kind);
+  });
+}
+```
+
+### Lock File
+
+```typescript
+import { writeLock, readLock } from "@mandujs/core";
+
+// Write lock file
+const lock = await writeLock("spec/spec.lock.json", manifest);
+console.log(lock.routesHash);
+
+// Read lock file
+const existing = await readLock("spec/spec.lock.json");
+```
+
+## Generator Module
+
+Spec-based code generation.
+
+```typescript
+import { generateRoutes, GenerateResult } from "@mandujs/core";
+
+const result: GenerateResult = await generateRoutes(manifest, "./");
+
+console.log("Created:", result.created);
+console.log("Skipped:", result.skipped);  // Existing slot files
+```
+
+### Template Functions
+
+```typescript
+import {
+  generateApiHandler,
+  generateApiHandlerWithSlot,
+  generateSlotLogic,
+  generatePageComponent
+} from "@mandujs/core";
+
+// Generate API handler
+const code = generateApiHandler(route);
+
+// API handler with slot
+const codeWithSlot = generateApiHandlerWithSlot(route);
+
+// Slot logic file
+const slotCode = generateSlotLogic(route);
+```
+
+## Guard Module
+
+Architecture rule checking and auto-correction.
+
+```typescript
+import {
+  runGuardCheck,
+  runAutoCorrect,
+  GuardResult,
+  GuardViolation
+} from "@mandujs/core";
+
+// Run check
+const result: GuardResult = await runGuardCheck(manifest, "./");
+
+if (!result.passed) {
+  result.violations.forEach((v: GuardViolation) => {
+    console.log(`${v.rule}: ${v.message}`);
+  });
+
+  // Run auto-correction
+  const corrected = await runAutoCorrect(result.violations, manifest, "./");
+  console.log("Fixed:", corrected.steps);
+  console.log("Remaining violations:", corrected.remainingViolations);
+}
+```
+
+### Guard Rules
+
+| Rule ID | Description | Auto-correctable |
+|---------|-------------|------------------|
+| `SPEC_HASH_MISMATCH` | Spec and lock hash mismatch | ✅ |
+| `GENERATED_MANUAL_EDIT` | Manual edit to generated file | ✅ |
+| `HANDLER_NOT_FOUND` | Handler file not found | ❌ |
+| `COMPONENT_NOT_FOUND` | Component file not found | ❌ |
+| `SLOT_NOT_FOUND` | Slot file not found | ✅ |
+
+## Runtime Module
+
+Server startup and routing.
+
+```typescript
+import {
+  startServer,
+  registerApiHandler,
+  registerPageLoader
+} from "@mandujs/core";
+
+// Register API handler
+registerApiHandler("getUsers", async (req) => {
+  return { users: [] };
+});
+
+// Register page loader
+registerPageLoader("homePage", () => import("./pages/Home"));
+
+// Start server
+const server = startServer(manifest, { port: 3000 });
+
+// Stop
+server.stop();
+```
+
+## Report Module
+
+Guard result report generation.
+
+```typescript
+import { buildGuardReport } from "@mandujs/core";
+
+const report = buildGuardReport(guardResult, lockPath);
+console.log(report);  // Formatted text report
+```
+
+## Types
+
+```typescript
+import type {
+  RoutesManifest,
+  RouteSpec,
+  RouteKind,
+  SpecLock,
+  GuardResult,
+  GuardViolation,
+  GenerateResult,
+  AutoCorrectResult,
+} from "@mandujs/core";
+```
+
+## Requirements
+
+- Bun >= 1.0.0
+- React >= 18.0.0
+- Zod >= 3.0.0
+
+## Related Packages
+
+- [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI tool
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -29,8 +29,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "peerDependencies": {
-    "bun": ">=1.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "zod": ">=3.0.0"

package/src/change/history.ts

@@ -0,0 +1,145 @@
+import path from "path";
+import type { ChangeRecord, HistoryConfig } from "./types";
+import { deleteSnapshot, listSnapshotIds } from "./snapshot";
+import { DEFAULT_HISTORY_CONFIG } from "./types";
+
+const SPEC_DIR = "spec";
+const HISTORY_DIR = "history";
+const CHANGES_FILE = "changes.json";
+
+/**
+ * Changes 파일 경로
+ */
+function getChangesPath(rootDir: string): string {
+  return path.join(rootDir, SPEC_DIR, HISTORY_DIR, CHANGES_FILE);
+}
+
+/**
+ * 모든 변경 기록 조회
+ */
+export async function listChanges(rootDir: string): Promise<ChangeRecord[]> {
+  const changesPath = getChangesPath(rootDir);
+  try {
+    const file = Bun.file(changesPath);
+    if (!(await file.exists())) {
+      return [];
+    }
+    return await file.json();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 특정 변경 기록 조회
+ */
+export async function getChange(rootDir: string, id: string): Promise<ChangeRecord | null> {
+  const changes = await listChanges(rootDir);
+  return changes.find((c) => c.id === id) || null;
+}
+
+/**
+ * 변경 기록 저장
+ */
+async function writeChanges(rootDir: string, changes: ChangeRecord[]): Promise<void> {
+  const changesPath = getChangesPath(rootDir);
+  const historyDir = path.join(rootDir, SPEC_DIR, HISTORY_DIR);
+
+  // 디렉토리 확보
+  await Bun.write(path.join(historyDir, ".gitkeep"), "");
+
+  await Bun.write(changesPath, JSON.stringify(changes, null, 2));
+}
+
+/**
+ * 오래된 스냅샷 정리
+ * @param rootDir 프로젝트 루트 디렉토리
+ * @param keepCount 유지할 스냅샷 수 (기본: 5)
+ * @returns 삭제된 스냅샷 ID 목록
+ */
+export async function pruneHistory(
+  rootDir: string,
+  keepCount: number = DEFAULT_HISTORY_CONFIG.maxSnapshots
+): Promise<string[]> {
+  const deletedIds: string[] = [];
+
+  // 모든 스냅샷 ID 조회 (최신 순으로 정렬됨)
+  const snapshotIds = await listSnapshotIds(rootDir);
+
+  if (snapshotIds.length <= keepCount) {
+    return deletedIds;
+  }
+
+  // 변경 기록 조회
+  const changes = await listChanges(rootDir);
+
+  // 활성 트랜잭션의 스냅샷 ID 수집 (삭제 불가)
+  const activeSnapshotIds = new Set(
+    changes.filter((c) => c.status === "active").map((c) => c.snapshotId)
+  );
+
+  // 유지할 스냅샷 외의 것들 삭제
+  const toDelete = snapshotIds.slice(keepCount);
+
+  for (const snapshotId of toDelete) {
+    // 활성 트랜잭션의 스냅샷은 삭제하지 않음
+    if (activeSnapshotIds.has(snapshotId)) {
+      continue;
+    }
+
+    const deleted = await deleteSnapshot(rootDir, snapshotId);
+    if (deleted) {
+      deletedIds.push(snapshotId);
+    }
+  }
+
+  // 삭제된 스냅샷에 연결된 변경 기록도 정리
+  if (deletedIds.length > 0) {
+    const deletedSet = new Set(deletedIds);
+    const remainingChanges = changes.filter((c) => {
+      // 활성 상태는 유지
+      if (c.status === "active") {
+        return true;
+      }
+      // 스냅샷이 삭제되지 않은 것만 유지
+      return !deletedSet.has(c.snapshotId);
+    });
+
+    await writeChanges(rootDir, remainingChanges);
+  }
+
+  return deletedIds;
+}
+
+/**
+ * History 설정 로드 (향후 mandu.config.json에서 로드)
+ */
+export async function loadHistoryConfig(rootDir: string): Promise<HistoryConfig> {
+  // 향후 mandu.config.json에서 로드하도록 확장
+  // 현재는 기본값 반환
+  return DEFAULT_HISTORY_CONFIG;
+}
+
+/**
+ * 변경 통계 조회
+ */
+export async function getChangeStats(
+  rootDir: string
+): Promise<{
+  total: number;
+  active: number;
+  committed: number;
+  rolledBack: number;
+  snapshotCount: number;
+}> {
+  const changes = await listChanges(rootDir);
+  const snapshotIds = await listSnapshotIds(rootDir);
+
+  return {
+    total: changes.length,
+    active: changes.filter((c) => c.status === "active").length,
+    committed: changes.filter((c) => c.status === "committed").length,
+    rolledBack: changes.filter((c) => c.status === "rolled_back").length,
+    snapshotCount: snapshotIds.length,
+  };
+}

package/src/change/index.ts

@@ -0,0 +1,40 @@
+// Types
+export type {
+  ChangeRecord,
+  Snapshot,
+  TransactionState,
+  HistoryConfig,
+  RestoreResult,
+  CommitResult,
+  RollbackResult,
+  BeginChangeOptions,
+} from "./types";
+
+export { DEFAULT_HISTORY_CONFIG } from "./types";
+
+// Integrity
+export { computeFileHash, collectFileHashes, collectFilePaths } from "./integrity";
+
+// Snapshot
+export {
+  createSnapshot,
+  readSnapshot,
+  writeSnapshot,
+  readSnapshotById,
+  restoreSnapshot,
+  deleteSnapshot,
+  listSnapshotIds,
+} from "./snapshot";
+
+// Transaction
+export {
+  beginChange,
+  commitChange,
+  rollbackChange,
+  hasActiveTransaction,
+  getActiveTransaction,
+  getTransactionStatus,
+} from "./transaction";
+
+// History
+export { listChanges, getChange, pruneHistory, loadHistoryConfig, getChangeStats } from "./history";

package/src/change/integrity.ts

@@ -0,0 +1,81 @@
+import { createHash } from "crypto";
+import path from "path";
+
+/**
+ * 파일의 SHA-256 해시를 계산
+ */
+export async function computeFileHash(filePath: string): Promise<string> {
+  try {
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    const content = await file.text();
+    return createHash("sha256").update(content).digest("hex");
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("File not found")) {
+      throw error;
+    }
+    throw new Error(
+      `Failed to compute hash for ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * 여러 파일의 해시를 수집
+ * @param rootDir 프로젝트 루트 디렉토리
+ * @param relativePaths 상대 경로 배열
+ * @returns 상대 경로 → 해시 맵
+ */
+export async function collectFileHashes(
+  rootDir: string,
+  relativePaths: string[]
+): Promise<Record<string, string>> {
+  const hashes: Record<string, string> = {};
+
+  await Promise.all(
+    relativePaths.map(async (relativePath) => {
+      const absolutePath = path.join(rootDir, relativePath);
+      try {
+        const hash = await computeFileHash(absolutePath);
+        hashes[relativePath] = hash;
+      } catch {
+        // 파일이 없는 경우 무시 (스냅샷 시점에 없었을 수 있음)
+      }
+    })
+  );
+
+  return hashes;
+}
+
+/**
+ * 디렉토리 내 모든 파일 경로를 재귀적으로 수집
+ */
+export async function collectFilePaths(
+  dirPath: string,
+  basePath: string = dirPath
+): Promise<string[]> {
+  const paths: string[] = [];
+
+  try {
+    const entries = await Array.fromAsync(
+      new Bun.Glob("**/*").scan({
+        cwd: dirPath,
+        onlyFiles: true,
+      })
+    );
+
+    for (const entry of entries) {
+      const relativePath = path.relative(basePath, path.join(dirPath, entry));
+      paths.push(relativePath);
+    }
+  } catch {
+    // 디렉토리가 없는 경우 빈 배열 반환
+  }
+
+  return paths;
+}