kld-sdd 2.7.8-3 → 2.7.8-4

package/lib/command-bridge.js

@@ -2,9 +2,12 @@
  * KunlunZhima OPSX Command Bridge 生成与管理
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
-const { renderTemplate, validateRenderedContent } = require('./skills-bundle');
+const { validateRenderedContent } = require('./skills-bundle');
+const { STRATEGY, CONFLICT_POLICY, deployFile } = require('./deploy-strategy');
 
 const BRIDGE_MARKER = '# SDD KunlunZhima Skill Bridge';
 const BRIDGE_MAX_BYTES = 4096;
@@ -70,18 +73,27 @@ function isManagedBridgeFile(content) {
   return typeof content === 'string' && content.includes(BRIDGE_MARKER);
 }
 
-function assertNoUserCommandConflict(commandPath, commandName) {
-  if (!fs.existsSync(commandPath)) {
-    return;
-  }
-
-  const existing = fs.readFileSync(commandPath, 'utf8');
-  if (!isManagedBridgeFile(existing)) {
-    throw new Error(
-      `命令文件冲突: ${commandName}.md 已存在且不含 SDD 受管标记。` +
-      '请手动备份后删除或重命名该文件，再重新初始化。'
-    );
-  }
+/**
+ * 部署单个 bridge：受管标记文件才覆盖，用户文件 fail-closed。
+ *
+ * MARKER 策略的 marker 用 BRIDGE_MARKER，冲突时 ERROR（而非静默保留），
+ * 保持「命令文件冲突」的既有语义（由 deploy-strategy 统一实现冲突判定）。
+ */
+function deploySingleBridge(commandPath, commandName, content) {
+  const result = deployFile(null, commandPath, {
+    strategy: STRATEGY.MARKER,
+    marker: BRIDGE_MARKER,
+    conflictPolicy: CONFLICT_POLICY.ERROR,
+    conflictMessage:
+      `命令文件冲突: ${commandName}.md 已存在且不含 SDD 受管标记。`
+      + '请手动备份后删除或重命名该文件，再重新初始化。',
+    label: `${commandName}.md`,
+    generate: () => content,
+  });
+  if (!result.ok) {
+    throw new Error(result.message);
+  }
+  return result;
 }
 
 function deployKunlunCommandBridges({ profile, projectRoot, pkgPath, skillMetadata }) {
@@ -107,10 +119,8 @@ function deployKunlunCommandBridges({ profile, projectRoot, pkgPath, skillMetada
 
   for (const metadata of skillMetadata) {
     const commandPath = getBridgeCommandPath(profile, projectRoot, metadata.commandName);
-    assertNoUserCommandConflict(commandPath, metadata.commandName);
-
     const content = generateKunlunBridge(metadata, profile, projectRoot, pkgPath);
-    fs.writeFileSync(commandPath, content, 'utf8');
+    deploySingleBridge(commandPath, metadata.commandName, content);
     deployed.push({
       commandName: metadata.commandName,
       path: commandPath,
@@ -152,5 +162,4 @@ module.exports = {
   deployKunlunCommandBridges,
   cleanupManagedKunlunBridges,
   isManagedBridgeFile,
-  getBridgeCommandPath,
 };

package/lib/deploy-codebuddy-hooks.js

@@ -1,29 +1,16 @@
 /**
  * Deploy CodeBuddy SDD Hook Pack to a target project.
+ *
+ * 策略：`.codebuddy/hooks/*` 是 SDD 私有目录下的工具产物 → OVERWRITE；
+ * `.codebuddy/settings.json` 是用户配置 → MERGE（保留用户 hooks 与未知字段）。
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
-const { mergeCodebuddySettings } = require('./settings-merge');
-
-function copyFileSync(src, dest) {
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.copyFileSync(src, dest);
-}
-
-function copyDirSync(srcDir, destDir) {
-  if (!fs.existsSync(srcDir)) return;
-  fs.mkdirSync(destDir, { recursive: true });
-  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    const srcPath = path.join(srcDir, entry.name);
-    const destPath = path.join(destDir, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
+const { mergeCodebuddySettingsFromTemplate } = require('./settings-merge');
+const { STRATEGY, deployFile } = require('./deploy-strategy');
 
 function validateExistingSettings(settingsPath) {
   if (!fs.existsSync(settingsPath)) {
@@ -69,13 +56,21 @@ function deployCodebuddyHookPack(profile, cwd, pkgPath) {
   const targetHookDir = path.join(codebuddyDir, 'hooks');
   fs.mkdirSync(targetHookDir, { recursive: true });
 
+  // 工具产物 → OVERWRITE，随 init 升级
   for (const file of fs.readdirSync(hookSourceDir)) {
     if (file === 'hook-gate-core.cjs') continue;
-    copyFileSync(path.join(hookSourceDir, file), path.join(targetHookDir, file));
+    deployFile(path.join(hookSourceDir, file), path.join(targetHookDir, file), {
+      strategy: STRATEGY.OVERWRITE,
+      label: file,
+    });
   }
 
   if (fs.existsSync(coreSourcePath)) {
-    copyFileSync(coreSourcePath, path.join(targetHookDir, 'hook-gate-core.cjs'));
+    // hook-gate-core.cjs 以 lib/ 为唯一来源，覆盖模板目录里的同名副本
+    deployFile(coreSourcePath, path.join(targetHookDir, 'hook-gate-core.cjs'), {
+      strategy: STRATEGY.OVERWRITE,
+      label: 'hook-gate-core.cjs',
+    });
   } else {
     return {
       ok: false,
@@ -83,8 +78,8 @@ function deployCodebuddyHookPack(profile, cwd, pkgPath) {
     };
   }
 
-  const templateSettings = JSON.parse(fs.readFileSync(settingsTemplatePath, 'utf8'));
-  const mergeResult = mergeCodebuddySettings(targetSettingsPath, templateSettings);
+  // 用户配置 → MERGE：保留用户未知字段与自定义 hook
+  const mergeResult = mergeCodebuddySettingsFromTemplate(settingsTemplatePath, targetSettingsPath);
   if (!mergeResult.ok) {
     return mergeResult;
   }
@@ -94,6 +89,4 @@ function deployCodebuddyHookPack(profile, cwd, pkgPath) {
 
 module.exports = {
   deployCodebuddyHookPack,
-  copyDirSync,
-  validateExistingSettings,
 };

package/lib/deploy-strategy.js

@@ -0,0 +1,293 @@
+'use strict';
+
+/**
+ * KLD SDD 部署策略抽象层
+ *
+ * 所有 init 向用户仓库写入文件的操作统一走这里，策略在调用点显式声明。
+ * 目的是消除「各部署函数各自手写 fs.copyFileSync / existsSync 判定」导致的行为漂移，
+ * 并让「这个文件是工具产物还是用户产物」在代码里可读。
+ *
+ * 策略一览（与产物归属的对应关系）：
+ * - OVERWRITE      工具产物 / 只读模板 → 无条件覆盖
+ * - SKIP_IF_EXISTS 用户产物 / 用户配置 → 存在即跳过，绝不覆盖
+ * - MERGE          结构化配置（settings.json / .sdd.yaml）→ 委托 mergeFn 保守合并
+ * - MARKER         与用户共用命名空间（.git/hooks）→ 含 marker 才覆盖，否则保留
+ * - APPEND_LINES   追加式清单（.gitignore）→ 只补缺失行
+ * - GENERATE       由生成器产出（runtime-metadata.cjs / .sdd-spec-root）→ 总是重写
+ *
+ * 设计约束：本模块只在 init 期使用，不得被 skywalk-sdd/ 下的运行时脚本 require
+ * （运行时脚本会被部署到用户仓库，不应依赖 lib/）。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** 部署策略 */
+const STRATEGY = Object.freeze({
+  /** 无条件覆盖：工具产物、只读模板 */
+  OVERWRITE: 'overwrite',
+  /** 存在则跳过：用户产物、用户配置 */
+  SKIP_IF_EXISTS: 'skip-if-exists',
+  /** 保守合并：保留用户已有字段，只注入受管内容 */
+  MERGE: 'merge',
+  /** marker 判定：含受管标记才覆盖，否则保留 */
+  MARKER: 'marker',
+  /** 追加缺失行：用于 .gitignore 这类清单文件 */
+  APPEND_LINES: 'append-lines',
+  /** 生成器产出：内容由代码生成，总是重写 */
+  GENERATE: 'generate',
+});
+
+/** 部署动作（用于调用点决定日志与统计） */
+const ACTION = Object.freeze({
+  CREATED: 'created',
+  OVERWRITTEN: 'overwritten',
+  SKIPPED: 'skipped',
+  MERGED: 'merged',
+  APPENDED: 'appended',
+  GENERATED: 'generated',
+  PRESERVED: 'preserved',
+  FAILED: 'failed',
+});
+
+/** 冲突处理：MARKER 策略遇到非受管文件时，保留还是报错 */
+const CONFLICT_POLICY = Object.freeze({
+  PRESERVE: 'preserve',
+  ERROR: 'error',
+});
+
+/** 默认 marker：SDD shell hook 的受管标记 */
+const DEFAULT_HOOK_MARKER = 'KLD SDD quality gate';
+
+function ensureParentDir(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function readIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+/**
+ * 解析要写入的内容。
+ * - 提供 render：调用 render(srcPath, tgtPath) 取内容（模板渲染场景）
+ * - 否则从 source 读取原文
+ */
+function resolveContent(source, target, options) {
+  if (typeof options.render === 'function') {
+    return options.render(source, target);
+  }
+  if (!source) {
+    throw new Error(`部署需要 source 或 render 之一: ${target}`);
+  }
+  return fs.readFileSync(source, 'utf8');
+}
+
+/**
+ * 部署单个文件。
+ *
+ * @param {string|null} source 源文件绝对路径（GENERATE / render 场景可为 null）
+ * @param {string} target 目标文件绝对路径
+ * @param {object} [options]
+ * @param {string} [options.strategy] STRATEGY 之一，默认 OVERWRITE
+ * @param {string} [options.label] 日志用文件名，默认 target 的 basename
+ * @param {function} [options.render] (srcPath, tgtPath) => string，模板渲染
+ * @param {function} [options.mergeFn] ({source,target,readSource,readTarget}) => {ok, action?, error?}
+ * @param {string} [options.marker] MARKER 策略的受管标记
+ * @param {string} [options.conflictPolicy] MARKER 策略冲突处理，默认 PRESERVE
+ * @param {string} [options.conflictMessage] MARKER 冲突且 policy=ERROR 时的自定义报错文案
+ * @param {string[]} [options.lines] APPEND_LINES 策略的必需行清单
+ * @param {string} [options.block] APPEND_LINES 策略在目标不存在时写入的完整块
+ * @param {string} [options.requiresMarker] APPEND_LINES 策略的块级标记（无标记则追加整块）
+ * @param {string} [options.supplementHeader] APPEND_LINES 策略补行时的段落标题
+ * @param {number} [options.mode] 写文件权限（如 0o755），仅新建时尝试
+ * @returns {{ok: boolean, action: string, target: string, label: string, message?: string}}
+ */
+function deployFile(source, target, options = {}) {
+  const strategy = options.strategy || STRATEGY.OVERWRITE;
+  const label = options.label || path.basename(target);
+  const done = (action, message) => ({ ok: true, action, target, label, message });
+  const failed = (message) => ({ ok: false, action: ACTION.FAILED, target, label, message });
+
+  switch (strategy) {
+    case STRATEGY.OVERWRITE: {
+      const existed = fs.existsSync(target);
+      ensureParentDir(target);
+      if (typeof options.render === 'function') {
+        fs.writeFileSync(target, resolveContent(source, target, options), 'utf8');
+      } else {
+        if (!source) return failed('OVERWRITE 策略需要 source 或 render');
+        fs.copyFileSync(source, target);
+      }
+      applyMode(target, options);
+      return done(existed ? ACTION.OVERWRITTEN : ACTION.CREATED);
+    }
+
+    case STRATEGY.SKIP_IF_EXISTS: {
+      if (fs.existsSync(target)) {
+        return done(ACTION.SKIPPED);
+      }
+      ensureParentDir(target);
+      if (typeof options.render === 'function') {
+        fs.writeFileSync(target, resolveContent(source, target, options), 'utf8');
+      } else if (options.generate != null) {
+        fs.writeFileSync(target, options.generate(), 'utf8');
+      } else {
+        if (!source) return failed('SKIP_IF_EXISTS 策略需要 source 或 render/generate');
+        fs.copyFileSync(source, target);
+      }
+      applyMode(target, options);
+      return done(ACTION.CREATED);
+    }
+
+    case STRATEGY.MERGE: {
+      if (typeof options.mergeFn !== 'function') {
+        return failed('MERGE 策略需要 mergeFn');
+      }
+      ensureParentDir(target);
+      const result = options.mergeFn({
+        source,
+        target,
+        readSource: () => {
+          if (!source) throw new Error(`MERGE 策略 readSource 需要 source: ${target}`);
+          return fs.readFileSync(source, 'utf8');
+        },
+        readTarget: () => readIfExists(target),
+      });
+      if (!result || result.ok !== true) {
+        return failed((result && result.error) || '合并失败');
+      }
+      return done(result.action || ACTION.MERGED, result.message);
+    }
+
+    case STRATEGY.MARKER: {
+      const marker = options.marker || DEFAULT_HOOK_MARKER;
+      const existing = readIfExists(target);
+      if (existing !== null && !existing.includes(marker)) {
+        if (options.conflictPolicy === CONFLICT_POLICY.ERROR) {
+          return failed(
+            options.conflictMessage
+              || `${label} 已存在且不含 SDD 受管标记。请手动备份后删除或重命名该文件，再重新初始化。`,
+          );
+        }
+        return done(ACTION.PRESERVED, '已存在且非 SDD 受管，已保留不覆盖');
+      }
+      ensureParentDir(target);
+      const content = options.generate != null
+        ? options.generate()
+        : resolveContent(source, target, options);
+      fs.writeFileSync(target, content, 'utf8');
+      applyMode(target, options);
+      return done(existing === null ? ACTION.CREATED : ACTION.OVERWRITTEN);
+    }
+
+    case STRATEGY.APPEND_LINES: {
+      const lines = Array.isArray(options.lines) ? options.lines : [];
+      const existing = readIfExists(target);
+
+      if (existing === null) {
+        ensureParentDir(target);
+        const initial = options.block != null ? `${String(options.block).trim()}\n` : `${lines.join('\n')}\n`;
+        fs.writeFileSync(target, initial, 'utf8');
+        return done(ACTION.CREATED);
+      }
+
+      // 块级标记缺失 → 视为从未注入，追加整块
+      const marker = options.requiresMarker;
+      if (marker && !existing.includes(marker)) {
+        if (options.block == null) return done(ACTION.SKIPPED);
+        fs.appendFileSync(target, String(options.block));
+        return done(ACTION.APPENDED, '已追加完整忽略块');
+      }
+
+      const missing = lines.filter((line) => line && !existing.includes(line));
+      if (missing.length === 0) {
+        return done(ACTION.SKIPPED);
+      }
+      const header = options.supplementHeader ? `\n${options.supplementHeader}\n` : '\n';
+      fs.appendFileSync(target, `${header}${missing.join('\n')}\n`);
+      return done(ACTION.APPENDED, `补充 ${missing.length} 行`);
+    }
+
+    case STRATEGY.GENERATE: {
+      if (typeof options.generate !== 'function') {
+        return failed('GENERATE 策略需要 generate');
+      }
+      ensureParentDir(target);
+      fs.writeFileSync(target, options.generate(), 'utf8');
+      applyMode(target, options);
+      return done(ACTION.GENERATED);
+    }
+
+    default:
+      return failed(`未知部署策略: ${strategy}`);
+  }
+}
+
+function applyMode(target, options) {
+  if (!options.mode) return;
+  try {
+    fs.chmodSync(target, options.mode);
+  } catch {
+    // Windows 上 chmod 可能没有实际效果
+  }
+}
+
+/**
+ * 递归部署目录。文件级策略沿用 options，可额外提供 render 做模板渲染。
+ *
+ * @param {string} source 源目录
+ * @param {string} target 目标目录
+ * @param {object} [options] 同 deployFile
+ * @returns {Array} 每个文件的部署结果
+ */
+function deployDir(source, target, options = {}) {
+  const results = [];
+  if (!fs.existsSync(source)) {
+    return results;
+  }
+  if (!fs.existsSync(target)) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  for (const name of fs.readdirSync(source)) {
+    const srcPath = path.join(source, name);
+    const tgtPath = path.join(target, name);
+    if (fs.statSync(srcPath).isDirectory()) {
+      results.push(...deployDir(srcPath, tgtPath, options));
+      continue;
+    }
+    results.push(deployFile(srcPath, tgtPath, { ...options, label: options.label || name }));
+  }
+  return results;
+}
+
+/** 统计各动作数量，供调用点输出摘要 */
+function summarize(results) {
+  const counts = {};
+  for (const item of results) {
+    const key = item.action || ACTION.FAILED;
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+/** 过滤出失败项 */
+function failures(results) {
+  return results.filter((item) => !item.ok);
+}
+
+module.exports = {
+  STRATEGY,
+  ACTION,
+  CONFLICT_POLICY,
+  DEFAULT_HOOK_MARKER,
+  deployFile,
+  deployDir,
+  summarize,
+  failures,
+};

package/lib/hook-gate-core.js

@@ -1,7 +1,13 @@
 /**
  * Shared SDD hook gate utilities for Claude and CodeBuddy adapters.
+ *
+ * 注意：本文件在 templates/hooks/codebuddy/hooks/hook-gate-core.cjs 有一份
+ * 逐字节相同的副本（模板 hook 以 ./hook-gate-core.cjs 相对引用，需可就地 require）。
+ * 修改本文件后必须同步副本，否则 test/codebuddy-hooks.cjs UT-022 漂移守卫会失败。
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
 
@@ -666,7 +672,6 @@ function detectTddBatchPattern(events, sinceTimestamp, tasksMdContent) {
 }
 
 module.exports = {
-  PROJECT_ENV_KEYS,
   readStdin,
   parseHookInput,
   normalizeHookInput,
@@ -685,12 +690,6 @@ module.exports = {
   evaluateApplyWriteGate,
   evaluateSkillApplyGate,
   evaluatePreToolDangerGate,
-  // TDD 批量执行检测
-  extractTddTestEvents,
-  buildPairMap,
-  detectConsecutiveReds,
-  detectInterleavingViolation,
-  detectTimestampClustering,
-  detectRapidPairing,
+  // TDD 批量执行检测（子检测器仅内部使用，对外只暴露聚合入口）
   detectTddBatchPattern,
 };