@mandujs/core 0.3.2 → 0.3.3

package/src/change/snapshot.ts

@@ -0,0 +1,233 @@
+import path from "path";
+import type { Snapshot, RestoreResult } from "./types";
+import type { RoutesManifest } from "../spec/schema";
+import type { SpecLock } from "../spec/lock";
+
+const SPEC_DIR = "spec";
+const MANIFEST_FILE = "routes.manifest.json";
+const LOCK_FILE = "spec.lock.json";
+const SLOTS_DIR = "slots";
+const HISTORY_DIR = "history";
+const SNAPSHOTS_DIR = "snapshots";
+
+/**
+ * 스냅샷 ID 생성 (YYYYMMDD-HHmmss-xxx)
+ */
+function generateSnapshotId(): string {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const time = now.toISOString().slice(11, 19).replace(/:/g, "");
+  const random = Math.random().toString(36).slice(2, 5);
+  return `${date}-${time}-${random}`;
+}
+
+/**
+ * 스냅샷 저장 경로 반환
+ */
+function getSnapshotPath(rootDir: string, snapshotId: string): string {
+  return path.join(rootDir, SPEC_DIR, HISTORY_DIR, SNAPSHOTS_DIR, `${snapshotId}.snapshot.json`);
+}
+
+/**
+ * Slot 파일들의 내용을 수집
+ */
+async function collectSlotContents(rootDir: string): Promise<Record<string, string>> {
+  const slotsDir = path.join(rootDir, SPEC_DIR, SLOTS_DIR);
+  const contents: Record<string, string> = {};
+
+  try {
+    const entries = await Array.fromAsync(
+      new Bun.Glob("**/*.ts").scan({
+        cwd: slotsDir,
+        onlyFiles: true,
+      })
+    );
+
+    await Promise.all(
+      entries.map(async (entry) => {
+        const filePath = path.join(slotsDir, entry);
+        const file = Bun.file(filePath);
+        if (await file.exists()) {
+          contents[entry] = await file.text();
+        }
+      })
+    );
+  } catch {
+    // slots 디렉토리가 없는 경우 빈 객체 반환
+  }
+
+  return contents;
+}
+
+/**
+ * 현재 spec 상태의 스냅샷 생성
+ */
+export async function createSnapshot(rootDir: string): Promise<Snapshot> {
+  const specDir = path.join(rootDir, SPEC_DIR);
+  const manifestPath = path.join(specDir, MANIFEST_FILE);
+  const lockPath = path.join(specDir, LOCK_FILE);
+
+  // Manifest 읽기 (필수)
+  const manifestFile = Bun.file(manifestPath);
+  if (!(await manifestFile.exists())) {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  const manifest: RoutesManifest = await manifestFile.json();
+
+  // Lock 읽기 (선택)
+  let lock: SpecLock | null = null;
+  const lockFile = Bun.file(lockPath);
+  if (await lockFile.exists()) {
+    lock = await lockFile.json();
+  }
+
+  // Slot 내용 수집
+  const slotContents = await collectSlotContents(rootDir);
+
+  const id = generateSnapshotId();
+
+  return {
+    id,
+    timestamp: new Date().toISOString(),
+    manifest,
+    lock,
+    slotContents,
+  };
+}
+
+/**
+ * 스냅샷 파일 읽기
+ */
+export async function readSnapshot(snapshotPath: string): Promise<Snapshot | null> {
+  try {
+    const file = Bun.file(snapshotPath);
+    if (!(await file.exists())) {
+      return null;
+    }
+    return await file.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 스냅샷 파일 저장
+ */
+export async function writeSnapshot(rootDir: string, snapshot: Snapshot): Promise<void> {
+  const snapshotPath = getSnapshotPath(rootDir, snapshot.id);
+  const snapshotDir = path.dirname(snapshotPath);
+
+  // 디렉토리 생성
+  await Bun.write(path.join(snapshotDir, ".gitkeep"), "");
+
+  // 스냅샷 저장
+  await Bun.write(snapshotPath, JSON.stringify(snapshot, null, 2));
+}
+
+/**
+ * 스냅샷 ID로 스냅샷 읽기
+ */
+export async function readSnapshotById(rootDir: string, snapshotId: string): Promise<Snapshot | null> {
+  const snapshotPath = getSnapshotPath(rootDir, snapshotId);
+  return readSnapshot(snapshotPath);
+}
+
+/**
+ * 스냅샷으로부터 상태 복원
+ */
+export async function restoreSnapshot(rootDir: string, snapshot: Snapshot): Promise<RestoreResult> {
+  const specDir = path.join(rootDir, SPEC_DIR);
+  const manifestPath = path.join(specDir, MANIFEST_FILE);
+  const lockPath = path.join(specDir, LOCK_FILE);
+  const slotsDir = path.join(specDir, SLOTS_DIR);
+
+  const restoredFiles: string[] = [];
+  const failedFiles: string[] = [];
+  const errors: string[] = [];
+
+  // 1. Manifest 복원
+  try {
+    await Bun.write(manifestPath, JSON.stringify(snapshot.manifest, null, 2));
+    restoredFiles.push(MANIFEST_FILE);
+  } catch (error) {
+    failedFiles.push(MANIFEST_FILE);
+    errors.push(`Failed to restore manifest: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // 2. Lock 복원 (있는 경우)
+  if (snapshot.lock) {
+    try {
+      await Bun.write(lockPath, JSON.stringify(snapshot.lock, null, 2));
+      restoredFiles.push(LOCK_FILE);
+    } catch (error) {
+      failedFiles.push(LOCK_FILE);
+      errors.push(`Failed to restore lock: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  // 3. Slot 파일들 복원
+  for (const [relativePath, content] of Object.entries(snapshot.slotContents)) {
+    const filePath = path.join(slotsDir, relativePath);
+    try {
+      // 디렉토리 확보
+      const dir = path.dirname(filePath);
+      await Bun.write(path.join(dir, ".gitkeep"), "");
+
+      await Bun.write(filePath, content);
+      restoredFiles.push(`${SLOTS_DIR}/${relativePath}`);
+    } catch (error) {
+      failedFiles.push(`${SLOTS_DIR}/${relativePath}`);
+      errors.push(
+        `Failed to restore slot ${relativePath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  return {
+    success: failedFiles.length === 0,
+    restoredFiles,
+    failedFiles,
+    errors,
+  };
+}
+
+/**
+ * 스냅샷 삭제
+ */
+export async function deleteSnapshot(rootDir: string, snapshotId: string): Promise<boolean> {
+  const snapshotPath = getSnapshotPath(rootDir, snapshotId);
+  try {
+    const file = Bun.file(snapshotPath);
+    if (await file.exists()) {
+      const { unlink } = await import("fs/promises");
+      await unlink(snapshotPath);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 모든 스냅샷 ID 목록 조회
+ */
+export async function listSnapshotIds(rootDir: string): Promise<string[]> {
+  const snapshotsDir = path.join(rootDir, SPEC_DIR, HISTORY_DIR, SNAPSHOTS_DIR);
+
+  try {
+    const entries = await Array.fromAsync(
+      new Bun.Glob("*.snapshot.json").scan({
+        cwd: snapshotsDir,
+        onlyFiles: true,
+      })
+    );
+
+    return entries
+      .map((entry) => entry.replace(".snapshot.json", ""))
+      .sort()
+      .reverse(); // 최신 순
+  } catch {
+    return [];
+  }
+}

package/src/change/transaction.ts

@@ -0,0 +1,293 @@
+import path from "path";
+import type {
+  ChangeRecord,
+  TransactionState,
+  BeginChangeOptions,
+  CommitResult,
+  RollbackResult,
+} from "./types";
+import { createSnapshot, writeSnapshot, readSnapshotById, restoreSnapshot } from "./snapshot";
+
+const SPEC_DIR = "spec";
+const HISTORY_DIR = "history";
+const CHANGES_FILE = "changes.json";
+const ACTIVE_FILE = "active.json";
+
+/**
+ * 변경 ID 생성 (YYYYMMDD-HHmmss-xxx)
+ */
+function generateChangeId(): string {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const time = now.toISOString().slice(11, 19).replace(/:/g, "");
+  const random = Math.random().toString(36).slice(2, 5);
+  return `${date}-${time}-${random}`;
+}
+
+/**
+ * History 디렉토리 경로
+ */
+function getHistoryDir(rootDir: string): string {
+  return path.join(rootDir, SPEC_DIR, HISTORY_DIR);
+}
+
+/**
+ * Changes 파일 경로
+ */
+function getChangesPath(rootDir: string): string {
+  return path.join(getHistoryDir(rootDir), CHANGES_FILE);
+}
+
+/**
+ * Active 파일 경로
+ */
+function getActivePath(rootDir: string): string {
+  return path.join(getHistoryDir(rootDir), ACTIVE_FILE);
+}
+
+/**
+ * 모든 변경 기록 읽기
+ */
+async function readChanges(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 [];
+  }
+}
+
+/**
+ * 변경 기록 저장
+ */
+async function writeChanges(rootDir: string, changes: ChangeRecord[]): Promise<void> {
+  const changesPath = getChangesPath(rootDir);
+  const historyDir = getHistoryDir(rootDir);
+
+  // 디렉토리 확보
+  await Bun.write(path.join(historyDir, ".gitkeep"), "");
+
+  await Bun.write(changesPath, JSON.stringify(changes, null, 2));
+}
+
+/**
+ * 현재 트랜잭션 상태 읽기
+ */
+async function readActiveState(rootDir: string): Promise<TransactionState> {
+  const activePath = getActivePath(rootDir);
+  try {
+    const file = Bun.file(activePath);
+    if (!(await file.exists())) {
+      return { active: false, changeId: null, snapshotId: null };
+    }
+    return await file.json();
+  } catch {
+    return { active: false, changeId: null, snapshotId: null };
+  }
+}
+
+/**
+ * 트랜잭션 상태 저장
+ */
+async function writeActiveState(rootDir: string, state: TransactionState): Promise<void> {
+  const activePath = getActivePath(rootDir);
+  const historyDir = getHistoryDir(rootDir);
+
+  // 디렉토리 확보
+  await Bun.write(path.join(historyDir, ".gitkeep"), "");
+
+  await Bun.write(activePath, JSON.stringify(state, null, 2));
+}
+
+/**
+ * 활성 트랜잭션 존재 여부 확인
+ */
+export async function hasActiveTransaction(rootDir: string): Promise<boolean> {
+  const state = await readActiveState(rootDir);
+  return state.active;
+}
+
+/**
+ * 현재 활성 트랜잭션 정보 조회
+ */
+export async function getActiveTransaction(rootDir: string): Promise<ChangeRecord | null> {
+  const state = await readActiveState(rootDir);
+  if (!state.active || !state.changeId) {
+    return null;
+  }
+
+  const changes = await readChanges(rootDir);
+  return changes.find((c) => c.id === state.changeId) || null;
+}
+
+/**
+ * 변경 트랜잭션 시작
+ * - 스냅샷 생성 후 활성 트랜잭션으로 등록
+ */
+export async function beginChange(
+  rootDir: string,
+  options: BeginChangeOptions = {}
+): Promise<ChangeRecord> {
+  // 이미 활성 트랜잭션이 있는지 확인
+  const existingState = await readActiveState(rootDir);
+  if (existingState.active) {
+    const existingChange = await getActiveTransaction(rootDir);
+    throw new Error(
+      `이미 활성화된 트랜잭션이 있습니다: ${existingState.changeId}${existingChange?.message ? ` (${existingChange.message})` : ""}`
+    );
+  }
+
+  // 스냅샷 생성
+  const snapshot = await createSnapshot(rootDir);
+  await writeSnapshot(rootDir, snapshot);
+
+  // 변경 기록 생성
+  const changeId = generateChangeId();
+  const change: ChangeRecord = {
+    id: changeId,
+    message: options.message,
+    status: "active",
+    createdAt: new Date().toISOString(),
+    snapshotId: snapshot.id,
+    autoGenerated: options.autoGenerated,
+  };
+
+  // 변경 기록 추가
+  const changes = await readChanges(rootDir);
+  changes.push(change);
+  await writeChanges(rootDir, changes);
+
+  // 활성 상태 업데이트
+  const activeState: TransactionState = {
+    active: true,
+    changeId: change.id,
+    snapshotId: snapshot.id,
+  };
+  await writeActiveState(rootDir, activeState);
+
+  return change;
+}
+
+/**
+ * 변경 트랜잭션 커밋
+ * - 현재 상태를 확정하고 트랜잭션 종료
+ */
+export async function commitChange(rootDir: string, changeId?: string): Promise<CommitResult> {
+  const state = await readActiveState(rootDir);
+
+  if (!state.active) {
+    throw new Error("활성화된 트랜잭션이 없습니다");
+  }
+
+  const targetChangeId = changeId || state.changeId;
+  if (!targetChangeId) {
+    throw new Error("커밋할 변경 ID를 찾을 수 없습니다");
+  }
+
+  if (changeId && state.changeId !== changeId) {
+    throw new Error(`지정된 변경(${changeId})이 현재 활성 트랜잭션(${state.changeId})과 다릅니다`);
+  }
+
+  // 변경 기록 업데이트
+  const changes = await readChanges(rootDir);
+  const changeIndex = changes.findIndex((c) => c.id === targetChangeId);
+
+  if (changeIndex === -1) {
+    throw new Error(`변경 기록을 찾을 수 없습니다: ${targetChangeId}`);
+  }
+
+  const change = changes[changeIndex];
+  change.status = "committed";
+  await writeChanges(rootDir, changes);
+
+  // 활성 상태 초기화
+  await writeActiveState(rootDir, {
+    active: false,
+    changeId: null,
+    snapshotId: null,
+  });
+
+  return {
+    success: true,
+    changeId: targetChangeId,
+    message: change.message,
+  };
+}
+
+/**
+ * 변경 트랜잭션 롤백
+ * - 스냅샷으로 복원하고 트랜잭션 종료
+ */
+export async function rollbackChange(rootDir: string, changeId?: string): Promise<RollbackResult> {
+  const state = await readActiveState(rootDir);
+
+  // 활성 트랜잭션이 없으면 changeId로 찾기
+  let targetChangeId: string;
+  let targetSnapshotId: string;
+
+  if (state.active && state.changeId) {
+    targetChangeId = changeId || state.changeId;
+    if (changeId && state.changeId !== changeId) {
+      throw new Error(`지정된 변경(${changeId})이 현재 활성 트랜잭션(${state.changeId})과 다릅니다`);
+    }
+    targetSnapshotId = state.snapshotId!;
+  } else if (changeId) {
+    // 활성 트랜잭션이 없지만 changeId가 지정된 경우
+    const changes = await readChanges(rootDir);
+    const change = changes.find((c) => c.id === changeId);
+    if (!change) {
+      throw new Error(`변경 기록을 찾을 수 없습니다: ${changeId}`);
+    }
+    targetChangeId = changeId;
+    targetSnapshotId = change.snapshotId;
+  } else {
+    throw new Error("롤백할 트랜잭션이 없습니다");
+  }
+
+  // 스냅샷 읽기
+  const snapshot = await readSnapshotById(rootDir, targetSnapshotId);
+  if (!snapshot) {
+    throw new Error(`스냅샷을 찾을 수 없습니다: ${targetSnapshotId}`);
+  }
+
+  // 스냅샷으로 복원
+  const restoreResult = await restoreSnapshot(rootDir, snapshot);
+
+  // 변경 기록 업데이트
+  const changes = await readChanges(rootDir);
+  const changeIndex = changes.findIndex((c) => c.id === targetChangeId);
+
+  if (changeIndex !== -1) {
+    changes[changeIndex].status = "rolled_back";
+    await writeChanges(rootDir, changes);
+  }
+
+  // 활성 상태 초기화
+  await writeActiveState(rootDir, {
+    active: false,
+    changeId: null,
+    snapshotId: null,
+  });
+
+  return {
+    success: restoreResult.success,
+    changeId: targetChangeId,
+    restoreResult,
+  };
+}
+
+/**
+ * 트랜잭션 상태 조회
+ */
+export async function getTransactionStatus(
+  rootDir: string
+): Promise<{ state: TransactionState; change: ChangeRecord | null }> {
+  const state = await readActiveState(rootDir);
+  const change = state.active ? await getActiveTransaction(rootDir) : null;
+
+  return { state, change };
+}

package/src/change/types.ts

@@ -0,0 +1,102 @@
+import type { RoutesManifest } from "../spec/schema";
+import type { SpecLock } from "../spec/lock";
+
+/**
+ * 변경 기록 - 하나의 트랜잭션을 나타냄
+ */
+export interface ChangeRecord {
+  /** 고유 ID: YYYYMMDD-HHmmss-xxx 형식 */
+  id: string;
+  /** 변경 설명 (선택) */
+  message?: string;
+  /** 상태: active(진행중), committed(확정), rolled_back(롤백됨) */
+  status: "active" | "committed" | "rolled_back";
+  /** 생성 시각 ISO 문자열 */
+  createdAt: string;
+  /** 연결된 스냅샷 ID */
+  snapshotId: string;
+  /** Auto-correct에 의해 생성됨 여부 */
+  autoGenerated?: boolean;
+}
+
+/**
+ * 스냅샷 - 특정 시점의 spec 상태를 저장
+ */
+export interface Snapshot {
+  /** 고유 ID */
+  id: string;
+  /** 생성 시각 ISO 문자열 */
+  timestamp: string;
+  /** routes.manifest.json 내용 (~1KB) */
+  manifest: RoutesManifest;
+  /** spec.lock.json 내용 (~0.1KB, 없을 수 있음) */
+  lock: SpecLock | null;
+  /** Slot 파일 내용만 저장 (Generated 파일은 재생성 가능) */
+  slotContents: Record<string, string>;
+}
+
+/**
+ * 현재 트랜잭션 상태
+ */
+export interface TransactionState {
+  /** 트랜잭션 활성화 여부 */
+  active: boolean;
+  /** 현재 활성 변경 ID */
+  changeId: string | null;
+  /** 현재 활성 스냅샷 ID */
+  snapshotId: string | null;
+}
+
+/**
+ * History 설정
+ */
+export interface HistoryConfig {
+  /** 최대 보관 스냅샷 수 (기본: 5) */
+  maxSnapshots: number;
+  /** 자동 정리 활성화 (기본: true) */
+  autoCleanup: boolean;
+}
+
+/**
+ * 스냅샷 복원 결과
+ */
+export interface RestoreResult {
+  success: boolean;
+  restoredFiles: string[];
+  failedFiles: string[];
+  errors: string[];
+}
+
+/**
+ * 커밋 결과
+ */
+export interface CommitResult {
+  success: boolean;
+  changeId: string;
+  message?: string;
+}
+
+/**
+ * 롤백 결과
+ */
+export interface RollbackResult {
+  success: boolean;
+  changeId: string;
+  restoreResult: RestoreResult;
+}
+
+/**
+ * beginChange 옵션
+ */
+export interface BeginChangeOptions {
+  message?: string;
+  autoGenerated?: boolean;
+}
+
+/**
+ * 기본 History 설정
+ */
+export const DEFAULT_HISTORY_CONFIG: HistoryConfig = {
+  maxSnapshots: 5,
+  autoCleanup: true,
+};