kenaz 0.0.0-stage → 0.3.2

package/core/.collaboration/hooks/install.js

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * install.js
+ * Git Hooks 安裝/卸載工具
+ *
+ * 功能:
+ * - 安裝 post-merge 和 pre-commit hooks 到 .git/hooks/
+ * - 卸載 hooks
+ * - 啟用/停用特定 hooks
+ * - 配置管理
+ *
+ * 使用方式:
+ *   node .collaboration/hooks/install.js install      # 安裝所有 hooks
+ *   node .collaboration/hooks/install.js uninstall    # 卸載所有 hooks
+ *   node .collaboration/hooks/install.js enable post-merge   # 啟用特定 hook
+ *   node .collaboration/hooks/install.js disable pre-commit  # 停用特定 hook
+ *   node .collaboration/hooks/install.js status       # 顯示狀態
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const GIT_HOOKS_DIR = path.join(PROJECT_ROOT, '.git/hooks');
+const COLLAB_HOOKS_DIR = path.join(PROJECT_ROOT, '.collaboration/hooks');
+const HOOKS_CONFIG_PATH = path.join(COLLAB_HOOKS_DIR, 'config.json');
+
+const AVAILABLE_HOOKS = ['post-merge', 'pre-commit'];
+
+/**
+ * 確保配置文件存在
+ */
+function ensureConfig() {
+  if (!fs.existsSync(HOOKS_CONFIG_PATH)) {
+    const defaultConfig = {
+      hooks: {
+        'post-merge': { enabled: true },
+        'pre-commit': { enabled: true }
+      }
+    };
+    fs.writeFileSync(HOOKS_CONFIG_PATH, JSON.stringify(defaultConfig, null, 2));
+  }
+}
+
+/**
+ * 讀取配置
+ */
+function readConfig() {
+  ensureConfig();
+  return JSON.parse(fs.readFileSync(HOOKS_CONFIG_PATH, 'utf8'));
+}
+
+/**
+ * 寫入配置
+ */
+function writeConfig(config) {
+  fs.writeFileSync(HOOKS_CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+/**
+ * 安裝單個 hook
+ */
+function installHook(hookName) {
+  const sourceHook = path.join(COLLAB_HOOKS_DIR, `${hookName}.js`);
+  const targetHook = path.join(GIT_HOOKS_DIR, hookName);
+
+  // 檢查 .git/hooks 目錄
+  if (!fs.existsSync(GIT_HOOKS_DIR)) {
+    console.error(`❌ 錯誤: .git/hooks 目錄不存在`);
+    console.error(`   請確認這是一個 Git 倉庫`);
+    return false;
+  }
+
+  // 檢查源文件
+  if (!fs.existsSync(sourceHook)) {
+    console.error(`❌ 錯誤: 找不到 ${hookName}.js`);
+    return false;
+  }
+
+  // 建立 wrapper 腳本（支援 core 專案 + 子專案）
+  // 子專案透過 .kenaz/project.yaml 的 core_path 找到 hook 腳本
+  // Fallback chain: project.yaml -> KENAZ_SOURCE_DIR -> LOCALAPPDATA auto-discover
+  const wrapperScript = `#!/usr/bin/env bash
+# Auto-generated wrapper for ${hookName} hook
+# DO NOT EDIT - managed by .collaboration/hooks/install.js
+
+# 解析 hook 腳本路徑（支援 core + 子專案，含 core_path 驗證和 fallback）
+HOOK_SCRIPT=".collaboration/hooks/${hookName}.js"
+if [ ! -f "$HOOK_SCRIPT" ] && [ -f ".kenaz/project.yaml" ]; then
+  # 子專案：從 .kenaz/project.yaml 讀取 core_path，含驗證與 fallback
+  CORE_PATH=$(node -e "
+const fs=require('fs'),path=require('path'),os=require('os');
+function isDir(p){try{return p&&fs.existsSync(p)&&fs.statSync(p).isDirectory();}catch{return false;}}
+// 1. project.yaml core_path (validated)
+let c='';
+try{const y=fs.readFileSync('.kenaz/project.yaml','utf8');const m=y.match(/core_path:\\s*['\\\"]?([^'\\\"\\\\n]+)/);if(m)c=m[1].trim();}catch(e){}
+if(c==='__kenaz_core__')c='';
+if(isDir(c)){console.log(c);process.exit(0);}
+// 2. KENAZ_SOURCE_DIR env var
+c=process.env.KENAZ_SOURCE_DIR||'';
+if(isDir(c)){console.log(c);process.exit(0);}
+// 3. Standard install locations (auto-discover)
+const la=process.env.LOCALAPPDATA||'';
+if(la){c=path.join(la,'Kenaz Dashboard','kenaz-core');if(isDir(c)){console.log(c);process.exit(0);}}
+const hd=process.env.HOME||os.homedir();
+if(hd){c=path.join(hd,'.local','share','kenaz-dashboard','kenaz-core');if(isDir(c)){console.log(c);process.exit(0);}}
+" 2>/dev/null)
+  if [ -n "$CORE_PATH" ] && [ -d "$CORE_PATH" ] && [ -f "$CORE_PATH/$HOOK_SCRIPT" ]; then
+    HOOK_SCRIPT="$CORE_PATH/$HOOK_SCRIPT"
+  fi
+fi
+
+if [ -f "$HOOK_SCRIPT" ]; then
+  node "$HOOK_SCRIPT" "$@"
+  exit $?
+else
+  # Hook 腳本不存在，靜默跳過
+  exit 0
+fi
+`;
+
+  try {
+    // 寫入 wrapper 腳本
+    fs.writeFileSync(targetHook, wrapperScript, { mode: 0o755 });
+    console.log(`✅ 安裝 ${hookName} hook 成功`);
+    console.log(`   源文件: ${sourceHook}`);
+    console.log(`   目標位置: ${targetHook}`);
+    return true;
+  } catch (error) {
+    console.error(`❌ 安裝 ${hookName} hook 失敗: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * 卸載單個 hook
+ */
+function uninstallHook(hookName) {
+  const targetHook = path.join(GIT_HOOKS_DIR, hookName);
+
+  if (!fs.existsSync(targetHook)) {
+    console.log(`ℹ️  ${hookName} hook 不存在，跳過卸載`);
+    return true;
+  }
+
+  try {
+    fs.unlinkSync(targetHook);
+    console.log(`✅ 卸載 ${hookName} hook 成功`);
+    return true;
+  } catch (error) {
+    console.error(`❌ 卸載 ${hookName} hook 失敗: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * 安裝所有 hooks
+ */
+function installAll() {
+  console.log('開始安裝 Git Hooks...\n');
+
+  let successCount = 0;
+  for (const hookName of AVAILABLE_HOOKS) {
+    if (installHook(hookName)) {
+      successCount++;
+    }
+    console.log('');
+  }
+
+  console.log(`========================================`);
+  console.log(`安裝完成: ${successCount}/${AVAILABLE_HOOKS.length} 個 hooks`);
+  console.log(`========================================\n`);
+
+  // Install the Kenaz post-commit hook (TASK_1660; record-only since TASK_2363).
+  // Idempotent, cross-platform, chains over any existing user post-commit, and
+  // appends the commit sha to .kenaz/specialist/heimdall_commits.jsonl.
+  try {
+    const synapseHookPath = path.join(COLLAB_HOOKS_DIR, 'synapse-hook.js');
+    if (fs.existsSync(synapseHookPath)) {
+      const { installHook: installSynapseHook } = require(synapseHookPath);
+      const r = installSynapseHook(PROJECT_ROOT);
+      if (r.ok) {
+        console.log(`✅ 安裝 synapse post-commit hook ${r.action === 'noop' ? '(已存在，已刷新)' : '成功'}`);
+      } else {
+        console.log(`ℹ️  synapse post-commit hook 跳過: ${r.message}`);
+      }
+    }
+  } catch (err) {
+    console.log(`ℹ️  synapse post-commit hook 設定跳過: ${err.message}`);
+  }
+
+  // Auto-register Codex MCP (idempotent)
+  try {
+    const setupCodexPath = path.join(PROJECT_ROOT, '.formation', 'bifrost', 'setup-codex.js');
+    if (fs.existsSync(setupCodexPath)) {
+      const { setup } = require(setupCodexPath);
+      setup({ silent: false });
+    }
+  } catch (err) {
+    console.log(`ℹ️  Codex MCP 設定跳過: ${err.message}`);
+  }
+
+  // 顯示配置
+  const config = readConfig();
+  console.log('\n當前配置:');
+  AVAILABLE_HOOKS.forEach(hookName => {
+    const enabled = config.hooks[hookName]?.enabled !== false;
+    console.log(`  ${hookName}: ${enabled ? '✅ 啟用' : '❌ 停用'}`);
+  });
+}
+
+/**
+ * 卸載所有 hooks
+ */
+function uninstallAll() {
+  console.log('開始卸載 Git Hooks...\n');
+
+  let successCount = 0;
+  for (const hookName of AVAILABLE_HOOKS) {
+    if (uninstallHook(hookName)) {
+      successCount++;
+    }
+  }
+
+  // TASK_1660: also remove the Synapse post-commit hook (restores chained one).
+  try {
+    const { removeHook: removeSynapseHook } = require(path.join(COLLAB_HOOKS_DIR, 'synapse-hook.js'));
+    const r = removeSynapseHook(PROJECT_ROOT);
+    if (r.ok && r.action !== 'noop') console.log('removed synapse post-commit hook: ' + r.action);
+  } catch (err) {
+    console.log('synapse post-commit hook uninstall skipped: ' + err.message);
+  }
+
+  console.log(`\n========================================`);
+  console.log(`卸載完成: ${successCount}/${AVAILABLE_HOOKS.length} 個 hooks`);
+  console.log(`========================================`);
+}
+
+/**
+ * 啟用 hook
+ */
+function enableHook(hookName) {
+  if (!AVAILABLE_HOOKS.includes(hookName)) {
+    console.error(`❌ 錯誤: 未知的 hook: ${hookName}`);
+    console.error(`   可用的 hooks: ${AVAILABLE_HOOKS.join(', ')}`);
+    return false;
+  }
+
+  const config = readConfig();
+  config.hooks[hookName] = { enabled: true };
+  writeConfig(config);
+
+  console.log(`✅ 已啟用 ${hookName} hook`);
+  return true;
+}
+
+/**
+ * 停用 hook
+ */
+function disableHook(hookName) {
+  if (!AVAILABLE_HOOKS.includes(hookName)) {
+    console.error(`❌ 錯誤: 未知的 hook: ${hookName}`);
+    console.error(`   可用的 hooks: ${AVAILABLE_HOOKS.join(', ')}`);
+    return false;
+  }
+
+  const config = readConfig();
+  config.hooks[hookName] = { enabled: false };
+  writeConfig(config);
+
+  console.log(`✅ 已停用 ${hookName} hook`);
+  return true;
+}
+
+/**
+ * 顯示狀態
+ */
+function showStatus() {
+  console.log('========================================');
+  console.log('Git Hooks 狀態');
+  console.log('========================================\n');
+
+  const config = readConfig();
+
+  for (const hookName of AVAILABLE_HOOKS) {
+    const targetHook = path.join(GIT_HOOKS_DIR, hookName);
+    const installed = fs.existsSync(targetHook);
+    const enabled = config.hooks[hookName]?.enabled !== false;
+
+    console.log(`${hookName}:`);
+    console.log(`  安裝狀態: ${installed ? '✅ 已安裝' : '❌ 未安裝'}`);
+    console.log(`  啟用狀態: ${enabled ? '✅ 啟用' : '❌ 停用'}`);
+    console.log('');
+  }
+}
+
+/**
+ * 顯示幫助
+ */
+function showHelp() {
+  console.log(`
+Git Hooks 安裝工具
+
+用法:
+  node install.js install                # 安裝所有 hooks
+  node install.js uninstall              # 卸載所有 hooks
+  node install.js enable <hook-name>     # 啟用特定 hook
+  node install.js disable <hook-name>    # 停用特定 hook
+  node install.js status                 # 顯示狀態
+  node install.js doctor                 # 掃描+修復所有已註冊專案的 Synapse hook
+  node install.js --help                 # 顯示幫助
+
+可用的 hooks:
+  ${AVAILABLE_HOOKS.join('\n  ')}
+
+範例:
+  node install.js install                # 安裝所有 hooks
+  node install.js enable post-merge      # 啟用 post-merge hook
+  node install.js disable pre-commit     # 停用 pre-commit hook
+  node install.js status                 # 查看狀態
+  `);
+}
+
+/**
+ * 主函數
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const command = args[0];
+
+  switch (command) {
+    case 'install':
+      installAll();
+      break;
+
+    case 'uninstall':
+      uninstallAll();
+      break;
+
+    case 'enable':
+      if (args.length < 2) {
+        console.error('❌ 錯誤: 請指定 hook 名稱');
+        console.error('   用法: node install.js enable <hook-name>');
+        process.exit(1);
+      }
+      enableHook(args[1]);
+      break;
+
+    case 'disable':
+      if (args.length < 2) {
+        console.error('❌ 錯誤: 請指定 hook 名稱');
+        console.error('   用法: node install.js disable <hook-name>');
+        process.exit(1);
+      }
+      disableHook(args[1]);
+      break;
+
+    case 'status':
+      showStatus();
+      break;
+
+    case 'doctor':
+      // TASK_1660: scan + repair Synapse post-commit hooks across ALL
+      // registered projects (~/.kenaz/projects.json). GameArk remediation path.
+      try {
+        const { doctor } = require(path.join(COLLAB_HOOKS_DIR, 'synapse-hook.js'));
+        doctor({ dryRun: args.includes('--dry-run') });
+      } catch (err) {
+        console.error('synapse hook doctor failed: ' + err.message);
+        process.exit(1);
+      }
+      break;
+
+    default:
+      console.error(`❌ 錯誤: 未知命令: ${command}`);
+      console.error('   使用 --help 查看用法');
+      process.exit(1);
+  }
+}
+
+// 執行
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  installHook,
+  uninstallHook,
+  installAll,
+  uninstallAll,
+  enableHook,
+  disableHook,
+  showStatus
+};

package/core/.collaboration/hooks/post-merge.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Git Post-Merge Hook
+ *
+ * 功能：
+ * - 合併後自動重建 JSONL 索引
+ * - 偵測任務文件變更
+ * - 記錄執行日誌
+ *
+ * 使用方式：
+ * - 由 Git 自動調用（透過 .githooks/post-merge）
+ * - 或手動執行：node .collaboration/hooks/post-merge.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// 配置
+const CONFIG = {
+  projectRoot: path.resolve(__dirname, '../..'),
+  logFile: path.join(__dirname, '../.logs/post-merge.log'),
+  enabled: true // 可以透過環境變數覆蓋
+};
+
+/**
+ * 記錄日誌
+ */
+function log(message, level = 'INFO') {
+  const timestamp = new Date().toISOString();
+  const logMessage = `[${timestamp}] [${level}] ${message}\n`;
+
+  // 確保日誌目錄存在
+  const logDir = path.dirname(CONFIG.logFile);
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  // 寫入日誌文件
+  fs.appendFileSync(CONFIG.logFile, logMessage);
+
+  // 同時輸出到控制台
+  console.log(logMessage.trim());
+}
+
+/**
+ * 檢查是否啟用
+ */
+function isEnabled() {
+  // 環境變數可以覆蓋配置
+  if (process.env.COLLAB_HOOKS_DISABLED === 'true') {
+    return false;
+  }
+  return CONFIG.enabled;
+}
+
+/**
+ * 取得已變更的任務文件（支援 core + 子專案路徑）
+ */
+function getChangedTaskFiles() {
+  try {
+    // 取得最近一次 merge 的變更
+    const output = execSync('git diff --name-only HEAD@{1} HEAD', {
+      cwd: CONFIG.projectRoot,
+      encoding: 'utf8'
+    });
+
+    const changedFiles = output.split('\n').filter(Boolean);
+
+    // 篩選出任務文件（新系統 YAML + 子專案 .kenaz/ + 舊系統 JSON）
+    const taskFiles = changedFiles.filter(file => {
+      const isTaskFile = /TASK_\d+/.test(file);
+      if (!isTaskFile) return false;
+
+      // 新系統: .collaboration/tasks/{status}/TASK_*.yaml
+      if (file.startsWith('.collaboration/tasks/') && file.endsWith('.yaml')) return true;
+      // 子專案: .kenaz/tasks/{status}/TASK_*.yaml
+      if (file.startsWith('.kenaz/tasks/') && file.endsWith('.yaml')) return true;
+      // 舊系統（向下相容）: .collaboration/tasks/db/all/TASK_*.json
+      if (file.startsWith('.collaboration/tasks/db/all/TASK_') && file.endsWith('.json')) return true;
+
+      return false;
+    });
+
+    return taskFiles;
+  } catch (error) {
+    log(`取得變更文件失敗: ${error.message}`, 'WARN');
+    return [];
+  }
+}
+
+/**
+ * 重建索引
+ */
+function rebuildIndex() {
+  try {
+    log('開始重建索引...');
+
+    // 調用 index-manager.js
+    const indexManager = path.join(__dirname, '../core/index-manager.js');
+
+    if (!fs.existsSync(indexManager)) {
+      log('index-manager.js 不存在，跳過索引重建', 'WARN');
+      return false;
+    }
+
+    // 執行重建
+    execSync(`node "${indexManager}" rebuild`, {
+      cwd: CONFIG.projectRoot,
+      encoding: 'utf8',
+      stdio: 'inherit'
+    });
+
+    log('索引重建完成');
+    return true;
+  } catch (error) {
+    log(`索引重建失敗: ${error.message}`, 'ERROR');
+    return false;
+  }
+}
+
+/**
+ * 主函數
+ */
+function main() {
+  log('=== Post-Merge Hook 開始執行 ===');
+
+  // 檢查是否啟用
+  if (!isEnabled()) {
+    log('Hook 已停用，跳過執行');
+    return 0;
+  }
+
+  // 取得變更的任務文件
+  const changedFiles = getChangedTaskFiles();
+
+  if (changedFiles.length === 0) {
+    log('沒有任務文件變更，跳過索引重建');
+    return 0;
+  }
+
+  log(`偵測到 ${changedFiles.length} 個任務文件變更:`);
+  changedFiles.forEach(file => log(`  - ${file}`));
+
+  // 重建索引
+  const success = rebuildIndex();
+
+  if (success) {
+    log('=== Post-Merge Hook 執行成功 ===');
+    return 0;
+  } else {
+    log('=== Post-Merge Hook 執行失敗 ===', 'ERROR');
+    return 1;
+  }
+}
+
+// 執行
+if (require.main === module) {
+  const exitCode = main();
+  process.exit(exitCode);
+}
+
+module.exports = { main, rebuildIndex, getChangedTaskFiles };