kld-sdd 2.4.17 → 2.4.19

package/skywalk-sdd/apply-worktree-finish.cjs

@@ -0,0 +1,551 @@
+#!/usr/bin/env node
+/**
+ * SDD Apply Worktree Finish — 本地并行加速的收尾工具
+ *
+ * record-base: 记录 Apply 开始时主仓库的集成分支（merge 目标）
+ * finish:      merge apply 分支 → integration_base → remove worktree → 删 apply 分支
+ *
+ * 必须在主仓库根目录执行，不要在 .worktrees/ 内。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const TEMP_DIR_NAMES = ['node_modules', 'dist', '.turbo', '.next', 'coverage', 'build'];
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--') continue;
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      if (eq !== -1) {
+        args[token.slice(2, eq)] = token.slice(eq + 1);
+      } else {
+        const key = token.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+          args[key] = next;
+          i++;
+        } else {
+          args[key] = true;
+        }
+      }
+    }
+  }
+  return args;
+}
+
+function git(cwd, gitArgs, opts = {}) {
+  return execFileSync('git', gitArgs, {
+    cwd,
+    encoding: 'utf8',
+    stdio: opts.silent ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'inherit'],
+  }).trim();
+}
+
+function gitTry(cwd, gitArgs) {
+  try {
+    return git(cwd, gitArgs, { silent: true });
+  } catch {
+    return null;
+  }
+}
+
+function gitThrow(cwd, gitArgs) {
+  try {
+    return execFileSync('git', gitArgs, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch (err) {
+    const stderr = err.stderr ? err.stderr.toString().trim() : '';
+    const msg = stderr || err.message || String(err);
+    const e = new Error(msg);
+    e.stderr = stderr;
+    throw e;
+  }
+}
+
+function fail(message) {
+  console.error(`错误: ${message}`);
+  process.exit(1);
+}
+
+function info(message) {
+  console.log(message);
+}
+
+function warn(message) {
+  console.warn(`警告: ${message}`);
+}
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function assertMainRepo(repoRoot) {
+  const cwd = path.resolve(process.cwd());
+  const worktreesSegment = `${path.sep}.worktrees${path.sep}`;
+  if (cwd.includes(worktreesSegment)) {
+    fail(
+      `当前目录在 worktree 内 (${cwd})。请在主仓库根目录执行本脚本，不要在 .worktrees/ 子目录中运行。`
+    );
+  }
+  const commonDir = gitTry(repoRoot, ['rev-parse', '--git-common-dir']);
+  const gitDir = gitTry(repoRoot, ['rev-parse', '--git-dir']);
+  if (commonDir && gitDir && path.resolve(repoRoot, commonDir) !== path.resolve(repoRoot, gitDir)) {
+    fail('当前检出为 linked worktree，请 cd 到主仓库根目录后重试。');
+  }
+}
+
+function stateFilePath(repoRoot, change, capability) {
+  return path.join(repoRoot, 'skywalk-sdd', 'state', `apply-${change}-${capability}.json`);
+}
+
+function readApplyState(repoRoot, change, capability) {
+  const filePath = stateFilePath(repoRoot, change, capability);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeApplyState(repoRoot, change, capability, payload) {
+  const stateDir = path.join(repoRoot, 'skywalk-sdd', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const filePath = stateFilePath(repoRoot, change, capability);
+  fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return filePath;
+}
+
+function branchRef(branch) {
+  return branch.startsWith('refs/') ? branch : `refs/heads/${branch}`;
+}
+
+function branchExists(repoRoot, branch) {
+  return Boolean(gitTry(repoRoot, ['rev-parse', '--verify', branchRef(branch)]));
+}
+
+function isBranchMergedInto(repoRoot, branch, target) {
+  const merged = gitTry(repoRoot, ['branch', '--merged', target]);
+  if (!merged) return false;
+  return merged.split('\n').some((line) => {
+    const name = line.replace(/^\*?\s+/, '').trim();
+    return name === branch;
+  });
+}
+
+function listGitWorktrees(repoRoot) {
+  const raw = gitTry(repoRoot, ['worktree', 'list', '--porcelain']);
+  if (!raw) return [];
+  const entries = [];
+  let current = {};
+  for (const line of raw.split('\n')) {
+    if (!line) {
+      if (current.path) entries.push(current);
+      current = {};
+      continue;
+    }
+    if (line.startsWith('worktree ')) current.path = line.slice('worktree '.length);
+    if (line.startsWith('branch ')) current.branch = line.slice('branch '.length);
+    if (line.startsWith('detached')) current.detached = true;
+  }
+  if (current.path) entries.push(current);
+  return entries;
+}
+
+function resolveWorktreeDir(repoRoot, change, capability, applyBranch) {
+  const candidates = [
+    path.join(repoRoot, '.worktrees', `apply-${change}-${capability}`),
+    path.join(repoRoot, '.worktrees', `apply-${change}`),
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) {
+      return dir;
+    }
+  }
+
+  const state = readApplyState(repoRoot, change, capability);
+  if (state && state.worktree_dir && fs.existsSync(state.worktree_dir)) {
+    return state.worktree_dir;
+  }
+
+  const ref = branchRef(applyBranch);
+  for (const wt of listGitWorktrees(repoRoot)) {
+    if (wt.branch === ref || wt.branch === applyBranch) {
+      return wt.path;
+    }
+    const base = path.basename(wt.path);
+    if (base === `apply-${change}-${capability}` || base === `apply-${change}`) {
+      return wt.path;
+    }
+  }
+  return null;
+}
+
+function resolveMergeTarget(repoRoot, change, capability, explicitTarget) {
+  if (explicitTarget) return explicitTarget;
+
+  const state = readApplyState(repoRoot, change, capability);
+  if (state && state.integration_base) {
+    const current = gitTry(repoRoot, ['branch', '--show-current']);
+    if (current && current !== state.integration_base) {
+      warn(
+        `主仓库当前分支为 ${current}，与 record-base 记录的集成分支 ${state.integration_base} 不一致；仍将 merge 到 ${state.integration_base}。`
+      );
+    }
+    return state.integration_base;
+  }
+
+  fail(
+    '无法确定合并目标分支：缺少 state 文件且未传 --target。\n' +
+      '请在 §1.5 创建 worktree 前执行 --record-base，或收尾时传入 --target=<集成分支>。'
+  );
+}
+
+function warnIntegrationBaseDrift(repoRoot, state, target) {
+  if (!state || !state.integration_base_sha) return;
+  const head = gitTry(repoRoot, ['rev-parse', target]);
+  if (!head || head === state.integration_base_sha) return;
+  warn(
+    `集成分支 ${target} 的 HEAD (${head.slice(0, 7)}) 已不同于 record-base 时 (${state.integration_base_sha.slice(0, 7)})。` +
+      ' 若其它 capability 已 merge，请先在 apply worktree 内 merge/rebase 集成分支，再执行 finish。'
+  );
+}
+
+function rmTempDirs(worktreeDir, dryRun) {
+  if (!fs.existsSync(worktreeDir)) return;
+  for (const name of TEMP_DIR_NAMES) {
+    const target = path.join(worktreeDir, name);
+    if (!fs.existsSync(target)) continue;
+    if (dryRun) {
+      info(`  [dry-run] 删除 ${target}`);
+    } else {
+      fs.rmSync(target, { recursive: true, force: true });
+      info(`  ✓ 已删除 ${path.relative(process.cwd(), target) || target}`);
+    }
+  }
+}
+
+function checkWorktreeClean(worktreeDir) {
+  const status = git(worktreeDir, ['status', '--porcelain'], { silent: true });
+  if (status) {
+    fail(
+      `worktree 存在未提交变更 (${worktreeDir})。请先在 worktree 内 commit 全部实现代码后再执行收尾。`
+    );
+  }
+}
+
+function verifyWorktreeBranch(worktreeDir, applyBranch) {
+  const current = gitTry(worktreeDir, ['branch', '--show-current']);
+  if (current && current !== applyBranch) {
+    warn(`worktree 当前分支为 ${current}，预期 ${applyBranch}。`);
+  }
+}
+
+function listMergePaths(repoRoot, target, branch) {
+  const out = gitTry(repoRoot, ['diff', '--name-only', `${target}...${branch}`]);
+  if (!out) return [];
+  return out.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+function checkUntrackedConflicts(repoRoot, target, branch) {
+  const mergePaths = listMergePaths(repoRoot, target, branch);
+  if (mergePaths.length === 0) return;
+
+  const untrackedRaw = gitTry(repoRoot, ['ls-files', '--others', '--exclude-standard']);
+  if (!untrackedRaw) return;
+
+  const untracked = new Set(
+    untrackedRaw.split('\n').map((line) => line.trim()).filter(Boolean)
+  );
+  const conflicts = mergePaths.filter((p) => untracked.has(p));
+  if (conflicts.length > 0) {
+    fail(
+      `主仓库存在未跟踪文件，merge 将被覆盖：\n` +
+        conflicts.map((p) => `  - ${p}`).join('\n') +
+        `\n请在 Apply 开始前移走或提交这些文件。`
+    );
+  }
+}
+
+function cmdRecordBase(args) {
+  const change = args.change;
+  if (!change) {
+    fail('缺少 --change 参数');
+  }
+  const capability = args.capability || change;
+  const repoRoot = findRepoRoot(process.cwd());
+  if (!repoRoot) {
+    fail('未找到 Git 仓库根目录');
+  }
+  assertMainRepo(repoRoot);
+
+  const integrationBase = gitTry(repoRoot, ['branch', '--show-current']);
+  if (!integrationBase) {
+    fail(
+      '当前为 detached HEAD，无法记录集成分支。请先在主仓库 checkout 到具名分支再执行 --record-base。'
+    );
+  }
+  const integrationBaseSha = git(repoRoot, ['rev-parse', 'HEAD'], { silent: true });
+  const applyBranch = `kld-sdd/${change}/${capability}`;
+
+  const existing = readApplyState(repoRoot, change, capability);
+  if (existing && existing.integration_base && existing.integration_base !== integrationBase) {
+    warn(
+      `覆盖已有 state：原集成分支 ${existing.integration_base} → 现 ${integrationBase}。` +
+        ' 若已有进行中的 worktree，请确认是否应继续。'
+    );
+  }
+
+  const payload = {
+    change,
+    capability,
+    integration_base: integrationBase,
+    integration_base_sha: integrationBaseSha,
+    apply_branch: applyBranch,
+    recorded_at: new Date().toISOString(),
+    finished_at: null,
+  };
+
+  const filePath = writeApplyState(repoRoot, change, capability, payload);
+  info(`✓ 已记录集成分支: ${integrationBase} (${integrationBaseSha.slice(0, 7)})`);
+  info(`  apply 分支（建议）: ${applyBranch}`);
+  info(`  状态文件: ${path.relative(repoRoot, filePath)}`);
+  info(JSON.stringify(payload));
+}
+
+function showHelp() {
+  console.log(`
+SDD Apply Worktree — 记录集成分支 / 收尾 merge+清理
+
+记录集成分支（§1.5，创建 worktree 之前）:
+  node skywalk-sdd/apply-worktree-finish.cjs --record-base --change=<变更名> [--capability=<能力名>]
+
+收尾（§6.1，worktree 内已全部 commit）:
+  node skywalk-sdd/apply-worktree-finish.cjs --change=<变更名> [--capability=<能力名>] [--target=<集成分支>]
+
+选项:
+  --record-base / --target / --dry-run / --skip-merge / --keep-branch
+  --no-check-untracked  跳过主仓库未跟踪文件冲突检查
+  --force-worktree-remove  worktree remove 失败时尝试 --force
+
+状态文件: skywalk-sdd/state/apply-<change>-<capability>.json
+`);
+}
+
+function cmdFinish(args) {
+  const change = args.change;
+  if (!change) {
+    showHelp();
+    fail('缺少 --change 参数');
+  }
+
+  const capability = args.capability || change;
+  const repoRoot = findRepoRoot(process.cwd());
+  if (!repoRoot) {
+    fail('未找到 Git 仓库根目录');
+  }
+
+  assertMainRepo(repoRoot);
+
+  const branch = `kld-sdd/${change}/${capability}`;
+  const worktreeDir = resolveWorktreeDir(repoRoot, change, capability, branch);
+  if (!worktreeDir) {
+    fail(
+      `未找到 worktree。已尝试:\n` +
+        `  .worktrees/apply-${change}-${capability}\n` +
+        `  .worktrees/apply-${change}\n` +
+        `  git worktree list（匹配分支 ${branch}）`
+    );
+  }
+
+  const target = resolveMergeTarget(repoRoot, change, capability, args.target);
+  const dryRun = Boolean(args['dry-run'] || args.dryRun);
+  const skipMerge = Boolean(args['skip-merge'] || args.skipMerge);
+  const keepBranch = Boolean(args['keep-branch'] || args.keepBranch);
+  const checkUntracked = !(args['no-check-untracked'] || args.noCheckUntracked);
+  const forceRemove = Boolean(args['force-worktree-remove'] || args.forceWorktreeRemove);
+
+  if (!branchExists(repoRoot, branch)) {
+    fail(`apply 分支不存在: ${branch}`);
+  }
+  if (!branchExists(repoRoot, target)) {
+    fail(`集成分支不存在: ${target}`);
+  }
+
+  const state = readApplyState(repoRoot, change, capability);
+
+  info(`仓库根目录: ${repoRoot}`);
+  info(`Worktree:     ${worktreeDir}`);
+  info(`Apply 分支:   ${branch}`);
+  info(`集成分支:     ${target}${state ? ' (来自 state)' : args.target ? ' (来自 --target)' : ''}`);
+
+  checkWorktreeClean(worktreeDir);
+  verifyWorktreeBranch(worktreeDir, branch);
+  warnIntegrationBaseDrift(repoRoot, state, target);
+
+  const alreadyMerged = isBranchMergedInto(repoRoot, branch, target);
+
+  if (!skipMerge && !alreadyMerged && checkUntracked) {
+    if (dryRun) {
+      info('[dry-run] 检查主仓库未跟踪文件冲突');
+    } else {
+      checkUntrackedConflicts(repoRoot, target, branch);
+    }
+  }
+
+  if (dryRun) {
+    info('\n[dry-run] 计划步骤:');
+    if (!skipMerge && !alreadyMerged) {
+      info(`  1. git checkout ${target} && git merge --no-ff ${branch}`);
+    } else if (alreadyMerged) {
+      info('  1. 跳过 merge（apply 分支已合入集成分支）');
+    }
+    info(`  2. 删除 worktree 内临时目录`);
+    info(`  3. git worktree remove ${worktreeDir}`);
+    info(`  4. git worktree prune`);
+    if (!keepBranch) info(`  5. git branch -d ${branch}`);
+    return;
+  }
+
+  let mergeCommit = null;
+
+  if (!skipMerge) {
+    if (alreadyMerged) {
+      info(`⏭  apply 分支已合入 ${target}，跳过 merge`);
+      mergeCommit = gitTry(repoRoot, ['rev-parse', target]);
+    } else {
+      const current = git(repoRoot, ['branch', '--show-current'], { silent: true });
+      if (current !== target) {
+        git(repoRoot, ['checkout', target]);
+      }
+      try {
+        gitThrow(repoRoot, [
+          'merge',
+          '--no-ff',
+          branch,
+          '-m',
+          `merge(apply): ${change}/${capability}`,
+        ]);
+        mergeCommit = git(repoRoot, ['rev-parse', 'HEAD'], { silent: true });
+        info(`✓ 已合并到 ${target} (${mergeCommit.slice(0, 7)})`);
+      } catch (err) {
+        fail(
+          `merge 失败（可能存在冲突，请在主仓库解决后重试或 --skip-merge）：\n${err.message || err}`
+        );
+      }
+    }
+  } else {
+    info('⏭  跳过 merge (--skip-merge)');
+  }
+
+  rmTempDirs(worktreeDir, false);
+
+  try {
+    git(repoRoot, ['worktree', 'remove', worktreeDir]);
+    info(`✓ 已移除 worktree: ${path.relative(repoRoot, worktreeDir)}`);
+  } catch (err) {
+    if (forceRemove) {
+      try {
+        git(repoRoot, ['worktree', 'remove', '--force', worktreeDir]);
+        info(`✓ 已强制移除 worktree: ${path.relative(repoRoot, worktreeDir)}`);
+      } catch (err2) {
+        fail(`worktree remove 失败: ${err2.message || err2}`);
+      }
+    } else {
+      fail(
+        `worktree remove 失败: ${err.message || err}\n` +
+          '  若目录仍被占用可重试并加 --force-worktree-remove'
+      );
+    }
+  }
+
+  gitTry(repoRoot, ['worktree', 'prune']);
+
+  if (!keepBranch) {
+    try {
+      git(repoRoot, ['branch', '-d', branch]);
+      info(`✓ 已删除分支: ${branch}`);
+    } catch (err) {
+      info(`⚠️  分支删除失败（可手动 git branch -D ${branch}）: ${err.message || err}`);
+    }
+  } else {
+    info(`⏭  保留分支 (--keep-branch): ${branch}`);
+  }
+
+  const finishedAt = new Date().toISOString();
+  const nextState = {
+    ...(state || {}),
+    change,
+    capability,
+    integration_base: target,
+    apply_branch: branch,
+    worktree_dir: worktreeDir,
+    finished_at: finishedAt,
+    merge_commit: mergeCommit,
+    worktree_removed: true,
+    branch_deleted: !keepBranch,
+  };
+  writeApplyState(repoRoot, change, capability, nextState);
+
+  const summary = {
+    change,
+    capability,
+    integration_base: target,
+    branch,
+    merge_commit: mergeCommit,
+    worktree_removed: true,
+    branch_deleted: !keepBranch,
+    skipped_merge: alreadyMerged,
+  };
+
+  info('\n✅ Apply worktree 收尾完成');
+  info(JSON.stringify(summary));
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.help || args.h) {
+    showHelp();
+    return;
+  }
+
+  if (args['record-base'] || args.recordBase) {
+    cmdRecordBase(args);
+    return;
+  }
+
+  cmdFinish(args);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  main,
+  parseArgs,
+  resolveWorktreeDir,
+  readApplyState,
+  writeApplyState,
+  resolveMergeTarget,
+  branchExists,
+  branchRef,
+  stateFilePath,
+  listGitWorktrees,
+};

package/skywalk-sdd/index.cjs

@@ -2264,6 +2264,7 @@ function cmdRecord(args) {
     'survey_result',
     'baseline_record',
     'telemetry_warning',
+    'worktree_finish',
   ];
 
   if (!type) {
@@ -2640,6 +2641,11 @@ SDD Telemetry CLI - 流程度量采集工具
   node skywalk-sdd/log.cjs doctor --project=/my/project --change=user-auth
   node skywalk-sdd/log.cjs tasks-status --project=/my/project --change=user-auth --require-complete
   node skywalk-sdd/log.cjs archive-docs --project=/my/project --change=user-auth --reason="变更已完成实施" --event-id=evt_archive --report-output=skywalk-sdd/reports/user-auth-report.md
+  node skywalk-sdd/log.cjs record --type=worktree_finish --command=apply --project=/my/project --change=user-auth --capability=user-auth --result=success --summary="merge+remove completed"
+
+Apply worktree（主仓库根目录，非 log.cjs 子命令）:
+  node skywalk-sdd/apply-worktree-finish.cjs --record-base --change=<name> --capability=<name>
+  node skywalk-sdd/apply-worktree-finish.cjs --change=<name> --capability=<name> [--target=<integration-base>] [--dry-run]
 `);
 }