docuking-mcp 2.9.2 → 2.10.0

package/handlers/sync.js

@@ -540,9 +540,10 @@ docuking_init을 먼저 실행하세요.`,
     console.error('[DocuKing] Sync 시작 알림 실패:', e.message);
   }
 
-  // 서버에서 파일 해시 조회 (Git 스타일 동기화용)
+  // 서버에서 파일 해시 및 메타 정보 조회 (Git 스타일 동기화용)
   let serverPathToHash = {};
   let serverHashToPath = {};
+  let serverPathToMeta = {}; // source, type, deletedAt 정보 포함
   let serverAllPaths = [];
   try {
     const hashResponse = await fetch(
@@ -557,6 +558,7 @@ docuking_init을 먼저 실행하세요.`,
       const hashData = await hashResponse.json();
       serverPathToHash = hashData.pathToHash || {};
       serverHashToPath = hashData.hashToPath || {};
+      serverPathToMeta = hashData.pathToMeta || {};
       serverAllPaths = hashData.allPaths || [];
     }
   } catch (e) {
@@ -734,24 +736,48 @@ docuking_init을 먼저 실행하세요.`,
     }
   }
 
+  // ========================================
   // 4. 서버에만 있고 로컬에 없는 파일 soft-delete (deleted_at 기반)
+  // ========================================
   // 단, 협업자 폴더(yy_Coworker_*)는 삭제하지 않음 (오너가 협업자 파일을 삭제하면 안됨)
-  // 기존 hard delete(delete-batch) → soft delete(soft-delete)로 변경
-  // 3일 후 크론잡에서 hard delete 수행
+  // source: 'web' 파일은 MCP에서 삭제 시도하지 않음 (클라이언트에서 필터링)
   // 중요: localPathsBeforePull 사용 (Pull 전에 수집한 목록)
   //       processedLocalPaths는 Pull로 내려받은 파일도 포함하므로 사용 금지
   let deleted = 0;
   const deletedFilePaths = [];
   let protectedFiles = []; // source: 'web' 파일 (보호됨)
+  const webProtectedPaths = []; // MCP에서 미리 필터링한 웹 파일
+
   if (serverAllPaths.length > 0 && !isCoworker) {
-    // 코워커가 아닌 경우에만 삭제 수행 (오너 전용)
+    // 오너만 삭제 수행
     // yy_Coworker_*로 시작하는 경로는 삭제 대상에서 제외
     // localPathsBeforePull: Pull 전에 수집한 로컬 파일 목록 (좀비 파일 방지)
-    const pathsToDelete = serverAllPaths.filter(p =>
-      !localPathsBeforePull.has(p) && !p.startsWith('yy_Coworker_')
-    );
+    //
+    // ★ 핵심: source: 'web' 파일은 삭제 대상에서 미리 제외!
+    // 이렇게 하면 웹에서 생성한 파일이 절대 삭제되지 않음
+    const pathsToDelete = serverAllPaths.filter(p => {
+      // 1. 로컬에 있으면 제외 (삭제 대상 아님)
+      if (localPathsBeforePull.has(p)) return false;
+
+      // 2. 협업자 폴더는 제외
+      if (p.startsWith('yy_Coworker_')) return false;
+
+      // 3. source: 'web' 파일은 제외 (웹에서 생성된 파일 보호)
+      const meta = serverPathToMeta[p];
+      if (meta && meta.source === 'web') {
+        webProtectedPaths.push(p);
+        return false;
+      }
 
-    console.error(`[DocuKing] soft-delete 대상: ${pathsToDelete.length}개 (서버에만 있고 Pull 전 로컬에 없던 파일)`);
+      return true;
+    });
+
+    // 웹 보호 파일 로그
+    if (webProtectedPaths.length > 0) {
+      console.error(`[DocuKing] source:web 파일 ${webProtectedPaths.length}개 삭제에서 제외:`, webProtectedPaths.slice(0, 5));
+    }
+
+    console.error(`[DocuKing] soft-delete 대상: ${pathsToDelete.length}개 (서버에만 있고 Pull 전 로컬에 없던 파일, source:local만)`);
 
     if (pathsToDelete.length > 0) {
       try {
@@ -774,15 +800,18 @@ docuking_init을 먼저 실행하세요.`,
           deletedFilePaths.push(...(deleteResult.deletedPaths || []));
           protectedFiles = deleteResult.protected || [];
 
-          // 보호된 파일이 있으면 로그 출력
+          // 보호된 파일이 있으면 로그 출력 (Backend에서 추가로 보호한 파일)
           if (protectedFiles.length > 0) {
-            console.error(`[DocuKing] 보호된 파일 ${protectedFiles.length}개 (source: web):`, protectedFiles.slice(0, 5));
+            console.error(`[DocuKing] Backend에서 추가 보호된 파일 ${protectedFiles.length}개:`, protectedFiles.slice(0, 5));
           }
         }
       } catch (e) {
         console.error('[DocuKing] 파일 soft-delete 실패:', e.message);
       }
     }
+
+    // MCP에서 미리 제외한 웹 파일도 보호 목록에 추가 (결과 표시용)
+    protectedFiles = [...protectedFiles, ...webProtectedPaths];
   }
 
   // 5. 빈 폴더 생성
@@ -1018,54 +1047,79 @@ export async function handlePullInternal(args) {
     fs.mkdirSync(mainFolderPath, { recursive: true });
   }
 
-  // 파일 목록 조회
-  let files = [];
-  let deletedFiles = []; // 삭제된 파일 목록 (deleted_at 기반)
+  // ========================================
+  // 서버 메타정보 조회 (pathToMeta: source, type, deletedAt 포함)
+  // ========================================
+  let serverPathToHash = {};
+  let serverHashToPath = {};
+  let serverPathToMeta = {};
+  let serverAllPaths = [];
+  let deletedFiles = [];
 
   try {
-    const response = await fetch(
-      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+    const hashResponse = await fetch(
+      `${API_ENDPOINT}/files/hashes-for-sync?projectId=${projectId}`,
       {
         headers: {
           'Authorization': `Bearer ${apiKey}`,
         },
       }
     );
-
-    if (!response.ok) {
-      throw new Error(await response.text());
+    if (hashResponse.ok) {
+      const hashData = await hashResponse.json();
+      serverPathToHash = hashData.pathToHash || {};
+      serverHashToPath = hashData.hashToPath || {};
+      serverPathToMeta = hashData.pathToMeta || {};
+      serverAllPaths = hashData.allPaths || [];
+      deletedFiles = hashData.deletedFiles || [];
     }
-
-    const data = await response.json();
-    files = flattenTree(data.tree || []);
   } catch (e) {
-    throw new Error(`파일 목록 조회 실패 - ${e.message}`);
+    console.error('[DocuKing] 서버 메타정보 조회 실패:', e.message);
   }
 
-  // 서버에서 삭제된 파일 목록 조회 (deleted_at 기반 동기화)
+  // 파일 트리 조회 (폴더 포함)
+  let files = [];
   try {
-    const hashResponse = await fetch(
-      `${API_ENDPOINT}/files/hashes-for-sync?projectId=${projectId}`,
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
       {
         headers: {
           'Authorization': `Bearer ${apiKey}`,
         },
       }
     );
-    if (hashResponse.ok) {
-      const hashData = await hashResponse.json();
-      deletedFiles = hashData.deletedFiles || [];
+
+    if (!response.ok) {
+      throw new Error(await response.text());
     }
+
+    const data = await response.json();
+    files = flattenTree(data.tree || [], '', true); // 폴더 포함
   } catch (e) {
-    console.error('[DocuKing] 삭제 파일 목록 조회 실패:', e.message);
+    throw new Error(`파일 목록 조회 실패 - ${e.message}`);
   }
 
   if (filePath) {
     files = files.filter(f => f.path === filePath || f.path.startsWith(filePath + '/'));
   }
 
-  if (files.length === 0) {
-    // 빈 파일은 에러가 아님 - 정상 결과 반환
+  // ========================================
+  // 완전판 Pull 로직
+  // 1. 폴더 먼저 정렬 (상위 폴더 → 하위 폴더)
+  // 2. 파일 다운로드 (source:web 파일도 Pull)
+  // 3. mark-as-pulled 호출 (source: web → local 변경)
+  // ========================================
+
+  // 폴더를 먼저 정렬 (상위 폴더부터 생성해야 함)
+  const sortedFiles = [...files].sort((a, b) => {
+    // 폴더 먼저
+    if (a.type === 'folder' && b.type !== 'folder') return -1;
+    if (a.type !== 'folder' && b.type === 'folder') return 1;
+    // 경로 깊이 순 (상위 먼저)
+    return a.path.split('/').length - b.path.split('/').length;
+  });
+
+  if (sortedFiles.length === 0 && deletedFiles.length === 0) {
     return {
       text: 'Pull할 파일이 없습니다.',
       total: 0,
@@ -1076,20 +1130,64 @@ export async function handlePullInternal(args) {
     };
   }
 
-  // 파일 다운로드
   const results = [];
-  const total = files.length;
+  const total = sortedFiles.length;
   let current = 0;
   let downloaded = 0;   // 새로 다운로드
   let updated = 0;      // 업데이트 (변경됨)
   let skipped = 0;      // 스킵 (변경 없음)
   let failed = 0;       // 실패
+  let foldersCreated = 0; // 생성된 폴더
 
-  for (const file of files) {
+  // Pull 후 mark-as-pulled할 파일 목록 (source: web 파일들)
+  const filesToMarkAsPulled = [];
+
+  for (const file of sortedFiles) {
     current++;
     const progress = `${current}/${total}`;
 
+    // 서버 메타 정보 조회
+    const serverMeta = serverPathToMeta[file.path];
+
+    // 서버 경로에 따라 로컬 저장 위치 결정
+    let fullPath;
+    if (file.path.startsWith('xx_') ||
+        file.path.startsWith('yy_All_Docu/') ||
+        file.path.startsWith('yy_All_Docu') ||
+        file.path.startsWith('yy_Coworker_') ||
+        file.path.startsWith('zz_ai_')) {
+      fullPath = path.join(localPath, file.path);
+    } else {
+      fullPath = path.join(mainFolderPath, file.path);
+    }
+
     try {
+      // ========================================
+      // 폴더 처리 (type === 'folder')
+      // ========================================
+      if (file.type === 'folder') {
+        if (fs.existsSync(fullPath)) {
+          // 이미 있음 → 스킵
+          results.push({ type: 'skip', path: file.path, itemType: 'folder' });
+          skipped++;
+        } else {
+          // 폴더 생성
+          fs.mkdirSync(fullPath, { recursive: true });
+          results.push({ type: 'download', path: file.path, itemType: 'folder' });
+          foldersCreated++;
+          downloaded++;
+
+          // source: 'web' 폴더면 mark-as-pulled 대상
+          if (serverMeta && serverMeta.source === 'web') {
+            filesToMarkAsPulled.push(file.path);
+          }
+        }
+        continue;
+      }
+
+      // ========================================
+      // 파일 처리 (type === 'file')
+      // ========================================
       const response = await fetch(
         `${API_ENDPOINT}/files?projectId=${projectId}&path=${encodeURIComponent(file.path)}`,
         {
@@ -1107,25 +1205,6 @@ export async function handlePullInternal(args) {
 
       const data = await response.json();
 
-      // 서버 경로에 따라 로컬 저장 위치 결정
-      // 프로젝트 루트 기준 절대경로 그대로 사용
-      // - xx_Infra_Config/xxx → xx_Infra_Config/xxx (시스템/인프라)
-      // - xx_Policy/xxx → xx_Policy/xxx (정책)
-      // - yy_All_Docu/xxx → yy_All_Docu/xxx (오너 문서)
-      // - yy_Coworker_xxx/yyy → yy_Coworker_xxx/yyy (협업자 폴더)
-      // - zz_ai_xxx/yyy → zz_ai_xxx/yyy (AI 폴더)
-      let fullPath;
-      if (file.path.startsWith('xx_') ||
-          file.path.startsWith('yy_All_Docu/') ||
-          file.path.startsWith('yy_Coworker_') ||
-          file.path.startsWith('zz_ai_')) {
-        // 서버 경로 그대로 로컬에 저장
-        fullPath = path.join(localPath, file.path);
-      } else {
-        // 기타 (구버전 호환): yy_All_Docu/ 안에 저장
-        fullPath = path.join(mainFolderPath, file.path);
-      }
-
       // 인코딩에 따라 저장
       const content = data.file?.content || data.content || '';
       const encoding = data.file?.encoding || data.encoding || 'utf-8';
@@ -1145,6 +1224,13 @@ export async function handlePullInternal(args) {
 
       if (localExists) {
         try {
+          const localStat = fs.statSync(fullPath);
+          if (localStat.isDirectory()) {
+            // 로컬에 같은 이름의 폴더가 있으면 건너뜀
+            results.push({ type: 'skip', path: file.path, error: '같은 이름의 폴더 존재' });
+            skipped++;
+            continue;
+          }
           const localBuffer = fs.readFileSync(fullPath);
           localHash = crypto.createHash('sha256').update(localBuffer).digest('hex');
         } catch (e) {
@@ -1171,20 +1257,49 @@ export async function handlePullInternal(args) {
       }
 
       if (localExists) {
-        // 기존 파일 업데이트
         results.push({ type: 'update', path: file.path });
         updated++;
       } else {
-        // 새로 다운로드
         results.push({ type: 'download', path: file.path });
         downloaded++;
       }
+
+      // source: 'web' 파일이면 mark-as-pulled 대상
+      if (serverMeta && serverMeta.source === 'web') {
+        filesToMarkAsPulled.push(file.path);
+      }
     } catch (e) {
       results.push({ type: 'fail', path: file.path, error: e.message });
       failed++;
     }
   }
 
+  // ========================================
+  // mark-as-pulled 호출 (source: 'web' → 'local' 변경)
+  // Pull된 웹 파일/폴더는 이제 로컬이 관리권한을 가짐
+  // ========================================
+  if (filesToMarkAsPulled.length > 0) {
+    try {
+      const markResponse = await fetch(`${API_ENDPOINT}/files/mark-as-pulled`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          projectId,
+          paths: filesToMarkAsPulled,
+        }),
+      });
+
+      if (markResponse.ok) {
+        console.error(`[DocuKing] mark-as-pulled 완료: ${filesToMarkAsPulled.length}개`);
+      }
+    } catch (e) {
+      console.error('[DocuKing] mark-as-pulled 실패:', e.message);
+    }
+  }
+
   // 상세 결과 구성 (Push 스타일)
   let resultText = `✓ Pull 완료!
 

package/index.js

@@ -713,6 +713,13 @@ zz_ai_3_Plan/
 - planId로 계획 찾기
 - 완료 요약 및 산출물 기록
 
+### 12. docuking_delete
+서버에서 파일/폴더를 직접 삭제합니다.
+- 로컬에서 삭제한 파일이 Push 후에도 서버에 남아있을 때
+- 서버에만 존재하는 불필요한 파일 정리
+- soft-delete 처리 (3일 후 영구 삭제)
+- 권한: 오너는 자기 영역, 협업자는 자기 폴더만
+
 ## Git과의 유사성
 
 | DocuKing | Git | 설명 |
@@ -737,6 +744,7 @@ zz_ai_3_Plan/
 | "DocuKing에 올려줘" | docuking_push({ localPath, message: "..." }) |
 | "DocuKing에서 가져와" | docuking_pull({ localPath }) |
 | "DocuKing에 뭐 있어?" | docuking_list({ localPath }) |
+| "서버에서 삭제해줘" | docuking_delete({ localPath, paths: [...] }) |
 
 ## 협업 핵심 원칙: 남의 제사상을 건드리지 않는다
 

package/lib/files.js

@@ -193,18 +193,33 @@ export function collectFiles(basePath, relativePath, results, excludedFiles = nu
 }
 
 /**
- * 트리 구조를 평탄화
+ * 트리 구조를 평탄화 (파일 + 폴더 모두 포함)
+ * @param {Array} tree - 트리 구조
+ * @param {string} prefix - 경로 접두어
+ * @param {boolean} includeEmpty - 빈 폴더도 포함 (기본: true)
+ * @returns {Array} - { path, name, type } 배열
  */
-export function flattenTree(tree, prefix = '') {
+export function flattenTree(tree, prefix = '', includeEmpty = true) {
   const results = [];
 
   for (const item of tree) {
     const itemPath = prefix ? `${prefix}/${item.name}` : item.name;
 
     if (item.type === 'file') {
-      results.push({ path: itemPath, name: item.name });
+      // 파일
+      results.push({ path: itemPath, name: item.name, type: 'file' });
+    } else if (item.type === 'folder') {
+      // 폴더도 결과에 추가 (빈 폴더 동기화를 위해)
+      if (includeEmpty) {
+        results.push({ path: itemPath, name: item.name, type: 'folder' });
+      }
+      // 자식 탐색
+      if (item.children && item.children.length > 0) {
+        results.push(...flattenTree(item.children, itemPath, includeEmpty));
+      }
     } else if (item.children) {
-      results.push(...flattenTree(item.children, itemPath));
+      // 구버전 호환: type 없이 children만 있는 경우
+      results.push(...flattenTree(item.children, itemPath, includeEmpty));
     }
   }
 

package/package.json

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