docuking-mcp 3.1.0 → 3.6.0

package/lib/index-cache.js

@@ -1,19 +1,26 @@
 /**
- * DocuKing MCP - 로컬 인덱스 캐시 모듈
+ * DocuKing MCP - 로컬 인덱스 캐시 모듈 (v2)
  *
  * Git의 .git/index처럼 마지막 동기화 상태를 저장하여
  * mtime 기반으로 변경된 파일만 빠르게 탐지합니다.
  *
+ * v2 변경사항 (2026-01-24):
+ * - deletedFiles 추적 (좀비 방지 핵심)
+ * - serverHash 캐시 (충돌 감지)
+ * - syncedAt 타임스탬프
+ * - lastPush, lastPull 분리
+ *
  * 효과:
  * - 변경되지 않은 파일은 해시 계산 스킵
  * - Pull/Push 시 변경된 파일만 처리
+ * - 로컬에서 삭제한 파일이 서버에서 다시 내려오지 않음 (좀비 방지)
  */
 
 import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 
-const INDEX_VERSION = 1;
+const INDEX_VERSION = 2;
 const INDEX_FILENAME = 'index.json';
 
 /**
@@ -25,7 +32,21 @@ function getIndexPath(localPath) {
 
 /**
  * 로컬 인덱스 로드
- * @returns {{ version: number, lastSync: string, files: Object }} 인덱스 객체
+ * @returns {IndexV2} 인덱스 객체
+ *
+ * v2 스키마:
+ * {
+ *   version: 2,
+ *   lastSync: string,
+ *   lastPush: string,
+ *   lastPull: string,
+ *   files: {
+ *     [path]: { hash, mtime, size, serverHash?, syncedAt?, source? }
+ *   },
+ *   deletedFiles: {
+ *     [path]: { deletedAt, lastHash }
+ *   }
+ * }
  */
 export function loadIndex(localPath) {
   const indexPath = getIndexPath(localPath);
@@ -34,13 +55,24 @@ export function loadIndex(localPath) {
     if (fs.existsSync(indexPath)) {
       const data = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
 
-      // 버전 체크 (호환되지 않으면 초기화)
-      if (data.version !== INDEX_VERSION) {
-        console.error('[DocuKing] 인덱스 버전 불일치, 재생성합니다.');
-        return createEmptyIndex();
+      // v1 → v2 마이그레이션
+      if (data.version === 1) {
+        console.error('[DocuKing] 인덱스 v1 → v2 마이그레이션 중...');
+        return migrateV1toV2(data);
+      }
+
+      // v2 확인
+      if (data.version === INDEX_VERSION) {
+        // deletedFiles가 없으면 추가 (안전성)
+        if (!data.deletedFiles) {
+          data.deletedFiles = {};
+        }
+        return data;
       }
 
-      return data;
+      // 알 수 없는 버전
+      console.error('[DocuKing] 알 수 없는 인덱스 버전, 재생성합니다.');
+      return createEmptyIndex();
     }
   } catch (e) {
     console.error('[DocuKing] 인덱스 로드 실패:', e.message);
@@ -50,13 +82,46 @@ export function loadIndex(localPath) {
 }
 
 /**
- * 빈 인덱스 생성
+ * v1 → v2 마이그레이션
+ */
+function migrateV1toV2(v1Data) {
+  const v2Index = {
+    version: 2,
+    lastSync: v1Data.lastSync,
+    lastPush: v1Data.lastSync,  // v1에서는 구분 없었음
+    lastPull: v1Data.lastSync,
+    files: {},
+    deletedFiles: {},
+  };
+
+  // 기존 파일 정보 마이그레이션
+  for (const [path, entry] of Object.entries(v1Data.files || {})) {
+    v2Index.files[path] = {
+      hash: entry.hash,
+      mtime: entry.mtime,
+      size: entry.size,
+      // v2 신규 필드 (값 없음)
+      serverHash: entry.hash,  // 마지막 동기화 시점의 해시를 서버 해시로 간주
+      syncedAt: v1Data.lastSync,
+      source: 'local',  // v1에서는 MCP만 사용했으므로 local로 간주
+    };
+  }
+
+  console.error(`[DocuKing] 마이그레이션 완료: ${Object.keys(v2Index.files).length}개 파일`);
+  return v2Index;
+}
+
+/**
+ * 빈 인덱스 생성 (v2)
  */
 function createEmptyIndex() {
   return {
     version: INDEX_VERSION,
     lastSync: null,
+    lastPush: null,
+    lastPull: null,
     files: {},
+    deletedFiles: {},  // 좀비 방지 핵심
   };
 }
 
@@ -149,9 +214,13 @@ export function detectChanges(localPath, index, filePaths, getFullPath) {
 }
 
 /**
- * 인덱스에 파일 정보 업데이트
+ * 인덱스에 파일 정보 업데이트 (v2)
+ *
+ * @param {Object} options - 추가 옵션
+ * @param {string} options.serverHash - 서버 해시 (서버와 동기화된 경우)
+ * @param {string} options.source - 파일 출처 (local | web)
  */
-export function updateIndexEntry(index, serverPath, fullPath, hash) {
+export function updateIndexEntry(index, serverPath, fullPath, hash, options = {}) {
   try {
     const stat = fs.statSync(fullPath);
 
@@ -159,8 +228,17 @@ export function updateIndexEntry(index, serverPath, fullPath, hash) {
       hash,
       mtime: stat.mtimeMs,
       size: stat.size,
+      // v2 필드
+      serverHash: options.serverHash || hash,
+      syncedAt: new Date().toISOString(),
+      source: options.source || 'local',
     };
 
+    // deletedFiles에서 제거 (부활한 경우)
+    if (index.deletedFiles && index.deletedFiles[serverPath]) {
+      delete index.deletedFiles[serverPath];
+    }
+
     return true;
   } catch (e) {
     return false;
@@ -174,6 +252,67 @@ export function removeIndexEntry(index, serverPath) {
   delete index.files[serverPath];
 }
 
+/**
+ * 파일을 삭제된 것으로 표시 (좀비 방지 핵심)
+ *
+ * 로컬에서 파일을 삭제하면 이 함수를 호출하여 deletedFiles에 기록.
+ * 이후 Pull 시 이 파일은 서버에 있어도 다운로드하지 않음.
+ *
+ * @param {Object} index - 인덱스 객체
+ * @param {string} serverPath - 서버 경로
+ * @param {string} lastHash - 삭제 전 마지막 해시
+ */
+export function markAsDeleted(index, serverPath, lastHash) {
+  // files에서 가져올 수 있으면 가져옴
+  const entry = index.files[serverPath];
+  const hash = lastHash || (entry ? entry.hash : null);
+
+  // deletedFiles에 기록
+  if (!index.deletedFiles) {
+    index.deletedFiles = {};
+  }
+
+  index.deletedFiles[serverPath] = {
+    deletedAt: new Date().toISOString(),
+    lastHash: hash,
+  };
+
+  // files에서 제거
+  delete index.files[serverPath];
+
+  console.error(`[DocuKing] 삭제 표시: ${serverPath}`);
+}
+
+/**
+ * 로컬에서 삭제된 파일인지 확인 (좀비 방지)
+ *
+ * Pull 시 이 함수로 확인하여 true면 다운로드 스킵.
+ *
+ * @param {Object} index - 인덱스 객체
+ * @param {string} serverPath - 서버 경로
+ * @returns {{ isDeleted: boolean, entry: Object | null }}
+ */
+export function wasDeletedLocally(index, serverPath) {
+  if (!index.deletedFiles) {
+    return { isDeleted: false, entry: null };
+  }
+
+  const entry = index.deletedFiles[serverPath];
+  return {
+    isDeleted: !!entry,
+    entry: entry || null,
+  };
+}
+
+/**
+ * 삭제 기록 제거 (서버에서도 삭제 완료된 경우)
+ */
+export function clearDeletedEntry(index, serverPath) {
+  if (index.deletedFiles) {
+    delete index.deletedFiles[serverPath];
+  }
+}
+
 /**
  * 인덱스의 해시와 비교하여 실제 변경 여부 확인
  * (mtime 변경됐지만 내용은 같을 수 있음)
@@ -208,35 +347,272 @@ export function verifyChanges(index, changedPaths, getFullPath) {
 }
 
 /**
- * 동기화 후 인덱스 일괄 업데이트
+ * 동기화 후 인덱스 일괄 업데이트 (v2)
  *
  * @param {Object} index - 인덱스 객체
- * @param {Array} syncedFiles - 동기화된 파일 목록 [{ serverPath, fullPath, hash }]
+ * @param {Array} syncedFiles - 동기화된 파일 목록 [{ serverPath, fullPath, hash, serverHash?, source? }]
  * @param {Array} deletedPaths - 삭제된 파일 경로 목록
+ * @param {Object} options - 추가 옵션
+ * @param {string} options.syncType - 'push' | 'pull' (lastPush/lastPull 업데이트용)
  */
-export function updateIndexAfterSync(index, syncedFiles, deletedPaths = []) {
+export function updateIndexAfterSync(index, syncedFiles, deletedPaths = [], options = {}) {
   // 동기화된 파일 업데이트
   for (const file of syncedFiles) {
-    updateIndexEntry(index, file.serverPath, file.fullPath, file.hash);
+    updateIndexEntry(index, file.serverPath, file.fullPath, file.hash, {
+      serverHash: file.serverHash || file.hash,
+      source: file.source || 'local',
+    });
   }
 
-  // 삭제된 파일 제거
+  // 삭제된 파일 처리
   for (const serverPath of deletedPaths) {
+    // Push로 서버에서도 삭제 완료된 경우: deletedFiles에서도 제거
+    if (options.syncType === 'push') {
+      clearDeletedEntry(index, serverPath);
+    }
+    // files에서 제거
     removeIndexEntry(index, serverPath);
   }
+
+  // syncType에 따라 lastPush/lastPull 업데이트
+  if (options.syncType === 'push') {
+    index.lastPush = new Date().toISOString();
+  } else if (options.syncType === 'pull') {
+    index.lastPull = new Date().toISOString();
+  }
 }
 
 /**
- * 인덱스 통계 반환
+ * 인덱스 통계 반환 (v2)
  */
 export function getIndexStats(index) {
   const files = Object.keys(index.files);
+  const deletedFiles = Object.keys(index.deletedFiles || {});
   const totalSize = Object.values(index.files).reduce((sum, f) => sum + (f.size || 0), 0);
 
   return {
     fileCount: files.length,
+    deletedCount: deletedFiles.length,
     totalSize,
     totalSizeMB: (totalSize / 1024 / 1024).toFixed(2),
     lastSync: index.lastSync,
+    lastPush: index.lastPush,
+    lastPull: index.lastPull,
+  };
+}
+
+/**
+ * 3-way 비교를 위한 파일 분류 (Push용)
+ *
+ * @param {Object} localFiles - 로컬 파일 맵 { serverPath: { hash, mtime, fullPath } }
+ * @param {Object} index - 인덱스 객체
+ * @param {Object} serverMeta - 서버 메타데이터 { pathToMeta, pathToHash }
+ * @returns {Object} 분류된 액션
+ */
+export function classifyForPush(localFiles, index, serverMeta) {
+  const actions = {
+    upload: [],     // 새 파일 또는 수정된 파일
+    delete: [],     // 로컬에서 삭제된 파일 (서버에서도 삭제)
+    skip: [],       // 변경 없음
+    conflict: [],   // 충돌 (양쪽 수정)
+    resurrect: [],  // 서버에서 삭제됐지만 로컬에서 수정됨
   };
+
+  // 1. 로컬 파일 처리
+  for (const [serverPath, local] of Object.entries(localFiles)) {
+    const inIndex = index.files[serverPath];
+    const onServer = serverMeta.pathToMeta?.[serverPath];
+
+    if (!inIndex && !onServer) {
+      // 새 파일 (인덱스에도, 서버에도 없음)
+      actions.upload.push({ path: serverPath, hash: local.hash, action: 'create' });
+    }
+    else if (!inIndex && onServer) {
+      // 인덱스에 없지만 서버에 있음
+      if (local.hash === onServer.hash) {
+        // 내용 동일 - 이미 동기화됨
+        actions.skip.push({ path: serverPath, reason: 'already-synced' });
+      } else {
+        // 내용 다름 - 업로드
+        actions.upload.push({ path: serverPath, hash: local.hash, action: 'update' });
+      }
+    }
+    else if (inIndex && !onServer) {
+      // 인덱스에 있지만 서버에 없음 (서버에서 삭제됨)
+      if (local.hash === inIndex.hash) {
+        // 로컬 수정 없음 - 서버 삭제 반영? 아니, 로컬 우선이므로 부활
+        actions.upload.push({ path: serverPath, hash: local.hash, action: 'create' });
+      } else {
+        // 로컬 수정됨 - 부활 (수정된 버전으로)
+        actions.resurrect.push({ path: serverPath, hash: local.hash });
+      }
+    }
+    else if (inIndex && onServer) {
+      // 인덱스에도 서버에도 있음 (정상 케이스)
+      const localModified = local.hash !== inIndex.hash;
+      const serverModified = onServer.hash !== (inIndex.serverHash || inIndex.hash);
+
+      if (!localModified && !serverModified) {
+        // 양쪽 다 수정 없음
+        actions.skip.push({ path: serverPath, reason: 'unchanged' });
+      }
+      else if (localModified && !serverModified) {
+        // 로컬만 수정됨 - 업로드
+        actions.upload.push({ path: serverPath, hash: local.hash, action: 'update' });
+      }
+      else if (!localModified && serverModified) {
+        // 서버만 수정됨 - Push에서는 무시 (Pull에서 처리)
+        actions.skip.push({ path: serverPath, reason: 'server-modified' });
+      }
+      else {
+        // 양쪽 다 수정됨 - 충돌 (로컬 우선 정책: 업로드)
+        actions.upload.push({ path: serverPath, hash: local.hash, action: 'update', conflict: true });
+      }
+    }
+  }
+
+  // 2. 삭제된 파일 처리 (인덱스에 있는데 로컬에 없는 파일)
+  for (const [serverPath, entry] of Object.entries(index.files)) {
+    if (localFiles[serverPath]) continue; // 로컬에 있음 - 스킵
+
+    const onServer = serverMeta.pathToMeta?.[serverPath];
+    if (!onServer) continue; // 서버에도 없음 - 스킵
+
+    // 로컬 삭제됨, 서버에 있음
+    if (onServer.source === 'web') {
+      // web 출처 파일은 삭제 보호
+      actions.skip.push({ path: serverPath, reason: 'protected-web-source' });
+    }
+    else if (onServer.hash !== (entry.serverHash || entry.hash)) {
+      // 서버가 수정됨 - 충돌 (로컬 삭제 vs 서버 수정)
+      actions.conflict.push({
+        path: serverPath,
+        type: 'delete-vs-modify',
+        localAction: 'delete',
+        serverHash: onServer.hash,
+      });
+    }
+    else {
+      // 안전하게 삭제 가능
+      actions.delete.push({ path: serverPath });
+    }
+  }
+
+  return actions;
+}
+
+/**
+ * 3-way 비교를 위한 파일 분류 (Pull용)
+ *
+ * @param {Object} localFiles - 로컬 파일 맵 { serverPath: { hash, mtime, fullPath } }
+ * @param {Object} index - 인덱스 객체
+ * @param {Object} serverMeta - 서버 메타데이터 { pathToMeta, deletedFiles }
+ * @returns {Object} 분류된 액션
+ */
+export function classifyForPull(localFiles, index, serverMeta) {
+  const actions = {
+    download: [],    // 새 서버 파일
+    update: [],      // 서버 수정됨, 로컬 수정 없음
+    deleteLocal: [], // 서버에서 삭제됨
+    skip: [],        // 변경 없음
+    conflict: [],    // 충돌
+  };
+
+  // 1. 서버 파일 처리
+  for (const [serverPath, server] of Object.entries(serverMeta.pathToMeta || {})) {
+    if (server.deletedAt) continue; // 삭제된 파일은 별도 처리
+
+    const inIndex = index.files[serverPath];
+    const local = localFiles[serverPath];
+    const deleted = wasDeletedLocally(index, serverPath);
+
+    if (!inIndex && !local && !deleted.isDeleted) {
+      // 새 서버 파일 (인덱스에도, 로컬에도 없음)
+      actions.download.push({ path: serverPath, hash: server.hash, source: server.source });
+    }
+    else if (!inIndex && !local && deleted.isDeleted) {
+      // 로컬에서 삭제한 파일 (좀비 방지)
+      if (server.hash === deleted.entry.lastHash) {
+        // 서버 변경 없음 - 스킵 (좀비 방지)
+        actions.skip.push({ path: serverPath, reason: 'locally-deleted-zombie-prevention' });
+      } else {
+        // 서버가 수정됨 - 충돌 (로컬 삭제 vs 서버 수정)
+        actions.conflict.push({
+          path: serverPath,
+          type: 'delete-vs-modify',
+          localAction: 'deleted',
+          serverHash: server.hash,
+        });
+      }
+    }
+    else if (inIndex && !local) {
+      // 인덱스에 있지만 로컬에 없음 (로컬에서 삭제됨)
+      // deletedFiles에 기록하고 스킵
+      actions.skip.push({ path: serverPath, reason: 'locally-deleted', markDeleted: true });
+    }
+    else if (inIndex && local) {
+      // 인덱스에도 로컬에도 있음
+      const localModified = local.hash !== inIndex.hash;
+      const serverModified = server.hash !== (inIndex.serverHash || inIndex.hash);
+
+      if (!localModified && !serverModified) {
+        actions.skip.push({ path: serverPath, reason: 'unchanged' });
+      }
+      else if (!localModified && serverModified) {
+        // 서버만 수정됨 - 다운로드
+        actions.update.push({ path: serverPath, hash: server.hash, source: server.source });
+      }
+      else if (localModified && !serverModified) {
+        // 로컬만 수정됨 - 스킵
+        actions.skip.push({ path: serverPath, reason: 'local-modified' });
+      }
+      else {
+        // 양쪽 다 수정됨 - 충돌
+        actions.conflict.push({
+          path: serverPath,
+          type: 'both-modified',
+          localHash: local.hash,
+          serverHash: server.hash,
+        });
+      }
+    }
+    else if (!inIndex && local) {
+      // 인덱스에 없지만 로컬에 있음
+      if (local.hash === server.hash) {
+        // 내용 동일 - 인덱스에 추가만
+        actions.skip.push({ path: serverPath, reason: 'already-have', addToIndex: true });
+      } else {
+        // 내용 다름 - 로컬 수정 보호
+        actions.skip.push({ path: serverPath, reason: 'local-different' });
+      }
+    }
+  }
+
+  // 2. 서버 삭제 파일 처리
+  for (const deleted of (serverMeta.deletedFiles || [])) {
+    const inIndex = index.files[deleted.path];
+    const local = localFiles[deleted.path];
+
+    if (inIndex && local) {
+      const localModified = local.hash !== inIndex.hash;
+
+      if (!localModified) {
+        // 로컬 수정 없음 - 삭제
+        const serverDeletedAt = new Date(deleted.deletedAt);
+        const localMtime = new Date(local.mtime);
+
+        if (serverDeletedAt > localMtime) {
+          actions.deleteLocal.push({ path: deleted.path });
+        } else {
+          // 로컬 mtime이 더 최신 - 유지 (다음 Push에서 부활)
+          actions.skip.push({ path: deleted.path, reason: 'local-newer-than-delete' });
+        }
+      } else {
+        // 로컬 수정됨 - 유지 (다음 Push에서 부활)
+        actions.skip.push({ path: deleted.path, reason: 'local-modified-server-deleted' });
+      }
+    }
+  }
+
+  return actions;
 }

package/lib/init.js

@@ -64,7 +64,7 @@ ${marker}
 - 의미 있는 작업 시작 시 (추적용)
 
 ### 규칙
-1. 동기화 대상: xx_*/ + yy_All_Docu/ + zz_ai_*/ 폴더 모두
+1. 동기화 대상: xx_*/ + xy_TalkTodoPlan/ + yy_All_Docu/ + zz_Coworker_*/ 폴더 모두
 2. 킹푸시는 Plan 완료(done) 시 자동 실행
 3. **Talk → Todo → Plan → Done** 순서 준수
 4. Plan 전에 반드시 Talk로 배경 기록
@@ -85,8 +85,8 @@ ${marker}
 
 | 역할 | Push (올리기) | Pull (내리기) | 삭제 |
 |------|---------------|---------------|------|
-| **오너** | \`xx_*/\` + \`yy_All_Docu/\` + \`zz_ai_*/\` | 합집합 전체 | 자기 영역만 |
-| **협업자** | \`yy_Coworker_{본인}/\` (안에 zz_ai_* 포함) | 합집합 전체 | 자기 영역만 |
+| **오너** | \`xx_*/\` + \`xy_TalkTodoPlan/\` + \`yy_All_Docu/\` | 합집합 전체 | 자기 영역만 |
+| **협업자** | \`zz_Coworker_{본인}/\` | 합집합 전체 | 자기 영역만 |
 
 ### 합집합이란?
 - 서버 = 오너 파일 + 모든 협업자 파일
@@ -97,7 +97,7 @@ ${marker}
 1. **초대 수락** (웹) → 프로젝트 진입, 자기 빈폴더 생성됨
 2. **MCP init** → 로컬에 자기 폴더 생성
 3. **Pull** → 합집합 전체 내려옴
-4. **작업** → \`yy_Coworker_{본인}/\` 안에서
+4. **작업** → \`zz_Coworker_{본인}/\` 안에서
 5. **Push** → 자기 폴더만 올라감
 
 ### 폴더 구조 (Pull 후)
@@ -108,14 +108,14 @@ project/
 ├── xx_Urgent/                   ← 긴급 보고 (킹어전트)
 ├── xy_TalkTodoPlan/             ← 오너 AI 기록 (Talk+Todo+Plan 통합)
 ├── yy_All_Docu/                 ← 오너 문서
-├── yy_Coworker_a_Kim/           ← 협업자 Kim
+├── zz_Coworker_Kim/             ← 협업자 Kim
 │   ├── 작업문서.md
-│   └── zz_TalkTodoPlan/         ← Kim의 AI 기록
-└── yy_Coworker_b_Lee/           ← 협업자 Lee
+│   └── Kim_TalkTodoPlan/        ← Kim의 AI 기록
+└── zz_Coworker_Lee/             ← 협업자 Lee
 \`\`\`
 
 ### AI가 협업자에게 안내할 것
-- 작업 폴더: \`yy_Coworker_{폴더명}/\`
+- 작업 폴더: \`zz_Coworker_{폴더명}/\`
 - 남의 파일: 읽기만 가능, 수정 불가
 - 수정 제안: 자기 폴더에 작성 또는 직접 연락
 
@@ -248,7 +248,7 @@ xx_Policy/
 xx_Urgent/
 xy_TalkTodoPlan/
 yy_All_Docu/
-yy_Coworker_*/
+zz_Coworker_*/
 .docuking/config.json
 .claude/rules/local/_coworker_config.md
 `;

package/lib/utils.js

@@ -47,7 +47,7 @@ export function generatePlanId() {
 
 /**
  * 계획 파일 찾기 (planId로 검색)
- * @param {string} planDir - AI 폴더 경로 (xy_TalkTodoPlan 또는 zz_TalkTodoPlan)
+ * @param {string} planDir - AI 폴더 경로 (xy_TalkTodoPlan 또는 {폴더명}_TalkTodoPlan)
  * @param {string} planId - 찾을 계획 ID
  */
 export function findPlanFiles(planDir, planId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docuking-mcp",
-  "version": "3.1.0",
+  "version": "3.6.0",
   "description": "DocuKing MCP Server - AI 시대의 문서 협업 플랫폼",
   "type": "module",
   "main": "index.js",