docuking-mcp 2.5.7 → 2.7.0

package/handlers/kingcast.js

@@ -0,0 +1,569 @@
+/**
+ * DocuKing MCP - 킹캐스트 핸들러 모듈
+ * 오너의 Policy/Config를 협업자에게 자동 배포하는 시스템
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+import {
+  getLocalConfig,
+  getAiBasePath,
+} from '../lib/config.js';
+
+// 킹캐스트 대상 폴더
+const KINGCAST_FOLDERS = ['_Infra_Config', '_Policy'];
+
+// 킹캐스트 해시 저장 파일
+const KINGCAST_HASH_FILE = '.docuking/kingcast_hashes.json';
+
+/**
+ * 파일 해시 계산
+ */
+function calculateFileHash(filePath) {
+  try {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('md5').update(content).digest('hex');
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * 킹캐스트 대상 파일 수집
+ * yy_All_Docu/_Infra_Config/, yy_All_Docu/_Policy/ 내의 모든 파일
+ */
+function collectKingcastFiles(localPath) {
+  const allDocuPath = path.join(localPath, 'yy_All_Docu');
+  const files = {};
+
+  for (const folder of KINGCAST_FOLDERS) {
+    const folderPath = path.join(allDocuPath, folder);
+    if (!fs.existsSync(folderPath)) continue;
+
+    const collectRecursive = (dir, relativePath = '') => {
+      const items = fs.readdirSync(dir);
+      for (const item of items) {
+        const fullPath = path.join(dir, item);
+        const relPath = relativePath ? `${relativePath}/${item}` : item;
+        const stat = fs.statSync(fullPath);
+
+        if (stat.isDirectory()) {
+          collectRecursive(fullPath, relPath);
+        } else {
+          // 모든 파일 수집 (.md뿐 아니라 .env, .json 등 포함)
+          const key = `${folder}/${relPath}`;
+          files[key] = {
+            fullPath,
+            hash: calculateFileHash(fullPath),
+          };
+        }
+      }
+    };
+
+    collectRecursive(folderPath);
+  }
+
+  return files;
+}
+
+/**
+ * 저장된 킹캐스트 해시 로드
+ */
+function loadKingcastHashes(localPath) {
+  const hashFilePath = path.join(localPath, KINGCAST_HASH_FILE);
+  try {
+    if (fs.existsSync(hashFilePath)) {
+      return JSON.parse(fs.readFileSync(hashFilePath, 'utf-8'));
+    }
+  } catch (err) {
+    // 파싱 실패 시 빈 객체 반환
+  }
+  return {};
+}
+
+/**
+ * 킹캐스트 해시 저장
+ */
+function saveKingcastHashes(localPath, hashes) {
+  const hashFilePath = path.join(localPath, KINGCAST_HASH_FILE);
+  const dir = path.dirname(hashFilePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(hashFilePath, JSON.stringify(hashes, null, 2), 'utf-8');
+}
+
+/**
+ * 변경 감지: 추가/수정/삭제된 파일 찾기
+ */
+function detectChanges(localPath) {
+  const currentFiles = collectKingcastFiles(localPath);
+  const savedHashes = loadKingcastHashes(localPath);
+
+  const changes = {
+    added: [],    // 새로 추가된 파일
+    modified: [], // 수정된 파일
+    deleted: [],  // 삭제된 파일
+  };
+
+  // 추가/수정 감지
+  for (const [key, file] of Object.entries(currentFiles)) {
+    if (!savedHashes[key]) {
+      changes.added.push(key);
+    } else if (savedHashes[key] !== file.hash) {
+      changes.modified.push(key);
+    }
+  }
+
+  // 삭제 감지
+  for (const key of Object.keys(savedHashes)) {
+    if (!currentFiles[key]) {
+      changes.deleted.push(key);
+    }
+  }
+
+  return {
+    changes,
+    currentFiles,
+    hasChanges: changes.added.length > 0 || changes.modified.length > 0 || changes.deleted.length > 0,
+  };
+}
+
+/**
+ * _Policy 파일 내용에서 변수 치환 (협업자 로컬화)
+ * @param {string} content - 원본 파일 내용
+ * @param {object} config - 협업자 설정
+ * @returns {string} - 로컬화된 내용
+ */
+function localizeContent(content, config) {
+  if (!config.isCoworker) {
+    return content; // 오너는 그대로
+  }
+
+  const coworkerFolder = config.coworkerFolder || '';
+  const coworkerFolderName = `yy_Coworker_${coworkerFolder}`;
+
+  // 변수 치환
+  let localized = content;
+  localized = localized.replace(/\{COWORKER_NAME\}/g, coworkerFolder);
+  localized = localized.replace(/\{COWORKER_FOLDER\}/g, coworkerFolderName);
+  localized = localized.replace(/\{BRANCH_NAME\}/g, `coworker/${coworkerFolder}`);
+
+  return localized;
+}
+
+/**
+ * .claude/rules/local/ 폴더에 로컬화된 정책 생성
+ * _Policy/ 폴더 구조를 그대로 미러링 (서브파일 구조)
+ */
+function updateLocalRules(localPath, currentFiles, changes, config) {
+  const localRulesPath = path.join(localPath, '.claude', 'rules', 'local');
+  const allDocuPath = path.join(localPath, 'yy_All_Docu');
+
+  // 폴더 생성
+  if (!fs.existsSync(localRulesPath)) {
+    fs.mkdirSync(localRulesPath, { recursive: true });
+  }
+
+  const isCoworker = config?.isCoworker || false;
+  const coworkerFolder = config?.coworkerFolder || '';
+  const projectName = config?.projectName || 'Unknown Project';
+
+  // _Policy 파일들 분류 (번호순 정렬)
+  const policyFiles = Object.entries(currentFiles)
+    .filter(([key]) => key.startsWith('_Policy/'))
+    .map(([key, file]) => ({ key, ...file }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+
+  // _Infra_Config 파일들 분류
+  const infraConfigFiles = Object.entries(currentFiles)
+    .filter(([key]) => key.startsWith('_Infra_Config/'))
+    .map(([key, file]) => ({ key, ...file }));
+
+  const createdFiles = [];
+
+  // ========================================
+  // 1. _Policy 파일들을 서브파일 구조로 복사
+  // ========================================
+  for (const file of policyFiles) {
+    // _Policy/00_project_overview.md → 00_project_overview.md
+    const relativePath = file.key.replace('_Policy/', '');
+    const targetPath = path.join(localRulesPath, relativePath);
+
+    // 디렉토리 생성
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+
+    // 파일 읽기 및 로컬화
+    try {
+      const content = fs.readFileSync(file.fullPath, 'utf-8');
+      const localizedContent = localizeContent(content, config);
+      fs.writeFileSync(targetPath, localizedContent, 'utf-8');
+      createdFiles.push(relativePath);
+    } catch (e) {
+      console.error(`[KingCast] 정책 파일 복사 실패: ${file.key} - ${e.message}`);
+    }
+  }
+
+  // ========================================
+  // 2. 협업자용 설정 파일 생성 (_coworker_config.md)
+  // ========================================
+  if (isCoworker) {
+    const coworkerConfigContent = `# 협업자 설정 (킹캐스트 자동 생성)
+
+> 이 파일은 킹캐스트가 로컬에서 생성합니다.
+> 서버에서 내려오는 파일이 아니므로 Pull해도 덮어씌워지지 않습니다.
+> 킹캐스트 재실행 시 갱신됩니다.
+
+## 프로젝트 정보
+- 프로젝트: ${projectName}
+- 역할: 협업자
+- 협업자 폴더명: ${coworkerFolder}
+- 작업 폴더: yy_Coworker_${coworkerFolder}/
+- 권장 브랜치: coworker/${coworkerFolder}
+- 최종 동기화: ${new Date().toISOString()}
+
+## DocuKing 문서 작업 범위
+
+※ 아래는 DocuKing 동기화 대상 폴더(yy_All_Docu/, yy_Coworker_*/, zz_ai_*/)에만 해당
+※ 코드 파일(src/, backend/, frontend/ 등)은 자유롭게 수정 가능
+
+### 킹푸시 가능한 영역
+- \`yy_Coworker_${coworkerFolder}/\` 폴더 안의 모든 파일
+
+### 읽기만 가능한 영역
+- \`yy_All_Docu/\` - 오너의 문서
+- \`yy_Coworker_*/\` - 다른 협업자의 문서
+- \`zz_ai_*/\` - 오너의 AI 기록
+
+### 주의: 위 폴더들은 수정해도 Pull하면 원본으로 덮어씌워짐
+- 수정이 필요하면 자기 폴더에 사본을 만들거나 오너에게 연락하세요
+
+## Git과 킹푸시는 별개
+
+### Git 커밋/푸시 (소스 보호)
+- 단위 작업 완료 시 AI가 "커밋/푸시할까요?" 제안
+- 코드 변경사항 백업 목적
+
+### 킹푸시 (문서 동기화)
+- Plan 완료(docuking_done) 시 자동으로 킹푸시 실행
+- DocuKing 문서 동기화 목적
+
+## Git 브랜치 가이드
+
+### 권장 브랜치
+\`\`\`bash
+git checkout -b coworker/${coworkerFolder}
+\`\`\`
+
+### 절대 금지
+- \`git push origin main\` 실행 금지
+- \`git checkout main\`에서 작업 금지
+- 강제 푸시(\`--force\`) 금지
+
+## 정책 모순 발견 시
+정책 문서에 모순이나 문제가 있다면:
+1. 자기 폴더에 발견 내용 기록
+2. 오너에게 직접 연락 (카톡, 이메일 등)
+3. 오너가 정책 수정 후 Push하면 다음 Pull에서 반영됨
+
+## 환경 정보 (읽기 전용 참고)
+`;
+
+    // _Infra_Config에서 민감하지 않은 정보 추가
+    let infraInfo = '';
+    for (const file of infraConfigFiles) {
+      const fileName = path.basename(file.key);
+      // 배포 관련 정보만 참조 (민감 정보 제외)
+      if (fileName.includes('deploy') || fileName.includes('README')) {
+        infraInfo += `\n참고 문서: yy_All_Docu/${file.key}`;
+      }
+    }
+
+    if (infraInfo) {
+      const fullCoworkerConfig = coworkerConfigContent + infraInfo;
+      fs.writeFileSync(path.join(localRulesPath, '_coworker_config.md'), fullCoworkerConfig, 'utf-8');
+    } else {
+      fs.writeFileSync(path.join(localRulesPath, '_coworker_config.md'), coworkerConfigContent + '\n(환경 정보 없음)\n', 'utf-8');
+    }
+    createdFiles.push('_coworker_config.md');
+  }
+
+  // ========================================
+  // 3. 정책 목록 인덱스 파일 생성 (00_index.md)
+  // ========================================
+  let indexContent = `# 정책 문서 인덱스 (킹캐스트 자동 생성)
+
+> 이 파일은 DocuKing 킹캐스트에 의해 자동 생성되었습니다.
+> 수동 수정하지 마세요. Pull 시 덮어씌워집니다.
+
+## 프로젝트 정보
+- 프로젝트: ${projectName}
+- 역할: ${isCoworker ? `협업자 (${coworkerFolder})` : '오너'}
+- 최종 동기화: ${new Date().toISOString()}
+
+## AI 필독
+
+**아래 정책 문서들을 반드시 읽고 내용을 숙지하세요.**
+목록만 보지 말고, 각 파일의 내용을 읽어서 이해하세요.
+정책 문서의 규칙을 따라 작업해야 합니다.
+
+## 정책 문서 목록
+`;
+
+  if (policyFiles.length === 0) {
+    indexContent += '\n(정책 문서가 없습니다)\n';
+  } else {
+    for (const file of policyFiles) {
+      const relativePath = file.key.replace('_Policy/', '');
+      indexContent += `- [${relativePath}](./${relativePath})\n`;
+    }
+  }
+
+  if (isCoworker) {
+    indexContent += `\n## 협업자 설정\n- [_coworker_config.md](./_coworker_config.md)\n`;
+  }
+
+  fs.writeFileSync(path.join(localRulesPath, '00_index.md'), indexContent, 'utf-8');
+  createdFiles.push('00_index.md');
+
+  // ========================================
+  // 4. 삭제된 정책에 해당하는 로컬 파일 삭제
+  // ========================================
+  if (changes.deleted.length > 0) {
+    for (const deletedKey of changes.deleted) {
+      if (deletedKey.startsWith('_Policy/')) {
+        const relativePath = deletedKey.replace('_Policy/', '');
+        const targetPath = path.join(localRulesPath, relativePath);
+        if (fs.existsSync(targetPath)) {
+          try {
+            fs.unlinkSync(targetPath);
+            console.error(`[KingCast] 삭제된 정책 파일 제거: ${relativePath}`);
+          } catch (e) {
+            console.error(`[KingCast] 파일 삭제 실패: ${relativePath} - ${e.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    localRulesPath,
+    createdFiles,
+    policyCount: policyFiles.length,
+    infraConfigCount: infraConfigFiles.length,
+  };
+}
+
+/**
+ * .gitignore에 킹캐스트 민감 파일만 추가
+ *
+ * Git 제외 대상 (민감 정보):
+ * - .docuking/config.json: API 키 포함
+ * - _coworker_config.md: 협업자별 로컬 설정
+ *
+ * Git 포함 대상 (백업):
+ * - .claude/rules/local/*.md: 정책 파일 (폴더구조, API규칙 등)
+ */
+function updateGitignoreForKingcast(localPath) {
+  const gitignorePath = path.join(localPath, '.gitignore');
+
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  }
+
+  let changed = false;
+
+  // 이전 버전에서 .claude/rules/local/ 전체 제외했던 경우 → 수정
+  if (content.includes('.claude/rules/local/') && !content.includes('.claude/rules/local/_coworker_config.md')) {
+    content = content.replace('.claude/rules/local/', '.claude/rules/local/_coworker_config.md');
+    changed = true;
+  }
+
+  // _coworker_config.md가 없으면 추가
+  if (!content.includes('.claude/rules/local/_coworker_config.md')) {
+    content += '\n# DocuKing 킹캐스트 민감 파일 (Git 제외)\n';
+    content += '.claude/rules/local/_coworker_config.md\n';
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(gitignorePath, content, 'utf-8');
+  }
+
+  return changed;
+}
+
+/**
+ * 킹캐스트 실행 (Pull 시 호출)
+ * @returns 변경 사항 요약
+ */
+export async function executeKingcast(localPath) {
+  const config = getLocalConfig(localPath);
+
+  if (!config) {
+    return {
+      success: false,
+      message: 'DocuKing이 초기화되지 않았습니다. docuking_init을 먼저 실행하세요.',
+    };
+  }
+
+  // 변경 감지
+  const { changes, currentFiles, hasChanges } = detectChanges(localPath);
+
+  if (!hasChanges) {
+    return {
+      success: true,
+      hasChanges: false,
+      message: '정책/환경 변경 없음',
+    };
+  }
+
+  // 로컬 룰 업데이트 (서브파일 구조)
+  const result = updateLocalRules(localPath, currentFiles, changes, config);
+
+  // 해시 저장 (다음 비교용)
+  const newHashes = {};
+  for (const [key, file] of Object.entries(currentFiles)) {
+    newHashes[key] = file.hash;
+  }
+  saveKingcastHashes(localPath, newHashes);
+
+  // .gitignore 업데이트
+  updateGitignoreForKingcast(localPath);
+
+  // 변경 요약 메시지 생성
+  const summary = [];
+  if (changes.added.length > 0) {
+    summary.push(`추가: ${changes.added.length}개`);
+  }
+  if (changes.modified.length > 0) {
+    summary.push(`수정: ${changes.modified.length}개`);
+  }
+  if (changes.deleted.length > 0) {
+    summary.push(`삭제: ${changes.deleted.length}개`);
+  }
+
+  // 킹캐스트 결과 메시지
+  const isCoworker = config?.isCoworker || false;
+  let message = `📢 킹캐스트: 정책/환경 변경 감지 (${summary.join(', ')})`;
+
+  if (result.policyCount > 0) {
+    message += `\n   📄 정책 파일 ${result.policyCount}개 → .claude/rules/local/`;
+  }
+
+  // 정책 변경 시 경고 메시지 추가
+  if (changes.modified.length > 0) {
+    message += `\n\n⚠️ 중요: 정책이 변경되었습니다!`;
+    message += `\n   기존 코드가 새 정책과 맞지 않을 수 있습니다.`;
+    message += `\n   변경된 정책 파일을 읽고, 기존 코드에도 새 정책을 적용하세요.`;
+    message += `\n   적용하지 않으면 코드가 일관성을 잃고 스파게티가 됩니다.`;
+    message += `\n   리팩토링이 필요하더라도 반드시 수행하세요.`;
+  }
+
+  return {
+    success: true,
+    hasChanges: true,
+    changes,
+    summary: summary.join(', '),
+    message,
+    details: {
+      added: changes.added,
+      modified: changes.modified,
+      deleted: changes.deleted,
+      localRulesPath: result.localRulesPath,
+      createdFiles: result.createdFiles,
+      policyCount: result.policyCount,
+      infraConfigCount: result.infraConfigCount,
+    },
+  };
+}
+
+/**
+ * 킹캐스트 상태 확인
+ */
+export async function handleKingcastStatus(args) {
+  const localPath = args.localPath || process.cwd();
+  const config = getLocalConfig(localPath);
+
+  if (!config) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: '오류: DocuKing이 초기화되지 않았습니다.',
+        },
+      ],
+    };
+  }
+
+  const { changes, currentFiles, hasChanges } = detectChanges(localPath);
+  const savedHashes = loadKingcastHashes(localPath);
+
+  let statusText = `# 킹캐스트 상태
+
+## 프로젝트 정보
+- 프로젝트: ${config.projectName || 'Unknown'}
+- 역할: ${config.isCoworker ? `협업자 (${config.coworkerFolder})` : '오너'}
+
+## 킹캐스트 대상 파일
+`;
+
+  // _Infra_Config 파일
+  statusText += '\n### _Infra_Config/\n';
+  const infraConfigFiles = Object.keys(currentFiles).filter(k => k.startsWith('_Infra_Config/'));
+  if (infraConfigFiles.length === 0) {
+    statusText += '(없음)\n';
+  } else {
+    for (const key of infraConfigFiles) {
+      statusText += `- ${key}\n`;
+    }
+  }
+
+  // _Policy 파일
+  statusText += '\n### _Policy/\n';
+  const policyFiles = Object.keys(currentFiles).filter(k => k.startsWith('_Policy/'));
+  if (policyFiles.length === 0) {
+    statusText += '(없음)\n';
+  } else {
+    for (const key of policyFiles) {
+      statusText += `- ${key}\n`;
+    }
+  }
+
+  // 변경 사항
+  statusText += '\n## 변경 사항\n';
+  if (!hasChanges) {
+    statusText += '변경 없음 (동기화 완료)\n';
+  } else {
+    if (changes.added.length > 0) {
+      statusText += `\n### 추가됨 (${changes.added.length}개)\n`;
+      for (const key of changes.added) {
+        statusText += `- ${key}\n`;
+      }
+    }
+    if (changes.modified.length > 0) {
+      statusText += `\n### 수정됨 (${changes.modified.length}개)\n`;
+      for (const key of changes.modified) {
+        statusText += `- ${key}\n`;
+      }
+    }
+    if (changes.deleted.length > 0) {
+      statusText += `\n### 삭제됨 (${changes.deleted.length}개)\n`;
+      for (const key of changes.deleted) {
+        statusText += `- ${key}\n`;
+      }
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: statusText,
+      },
+    ],
+  };
+}