kld-sdd 2.7.8-2 → 2.7.8-4

package/lib/uninstall.js

@@ -0,0 +1,764 @@
+/**
+ * KLD SDD 卸载
+ *
+ * 与 init 共用同一套「产物归属」判定，方向相反：
+ * - 工具产物（安装时 OVERWRITE）→ 删除
+ * - 用户配置（安装时 SKIP_IF_EXISTS）→ 默认保留，仅 --purge 才删
+ * - MERGE 类（settings.json）→ 只摘除 SDD 受管 hook，文件其余内容原样保留
+ * - MARKER 类（.git/hooks）→ 只删含受管标记的，非受管 hook 保留
+ * - APPEND_LINES（.gitignore）→ 只摘除 SDD 块，其余行保留
+ * - 运行时数据（events/state）→ 默认保留（含用户历史度量），仅 --purge 才删
+ * - 团队/项目配置（project-identity.json、git-hooks/hooks.config）→ 默认保留。
+ *   二者都不是「工具可重置」的产物：前者是团队共享的 KB 身份（需提交 Git），
+ *   后者是项目级门禁参数（init 用 SKIP_IF_EXISTS 保护），重跑 init 不得重置。
+ *
+ * 两种模式：
+ * - MODE.TOOLS_ONLY（默认）：只删工具产物，保留全部用户配置与数据
+ * - MODE.FULL（--purge）：连用户配置与运行时数据一并删除
+ *
+ * 安全约束：
+ * - 任何删除前先经 scope 白名单校验（只允许操作 SDD 自有目录 / 受管标记文件）
+ * - --dry-run 只打印计划，不落盘
+ * - 删除文件后清理变空的目录，但不删除用户可能仍有内容的目录
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { isManagedBridgeFile } = require('./command-bridge');
+const { PROVIDERS, stripManagedHooks } = require('./settings-merge');
+const { DEFAULT_HOOK_MARKER } = require('./deploy-strategy');
+const { getToolProfile, listToolProfileIds, buildToolConfigs } = require('./tool-profiles');
+const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
+const workspaceLayout = require('./workspace-layout');
+// spec 候选枚举的唯一入口（含 tier 分级与排序）
+const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+
+/** 卸载模式 */
+const MODE = Object.freeze({
+  /** 只删工具内容，保留用户配置与运行时数据 */
+  TOOLS_ONLY: 'tools-only',
+  /** 全量删除，含用户配置与运行时数据 */
+  FULL: 'full',
+});
+
+/** 操作类型（用于计划与摘要） */
+const OP = Object.freeze({
+  DELETE_FILE: 'delete-file',
+  DELETE_DIR: 'delete-dir',
+  STRIP_HOOKS: 'strip-hooks',
+  STRIP_GITIGNORE: 'strip-gitignore',
+  UNLINK_GIT_CONFIG: 'unlink-git-config',
+  KEEP: 'keep',
+});
+
+/** .gitignore 中 SDD 块的起始标记 */
+const GITIGNORE_MARKER = 'KLD SDD';
+
+function createPlan(root = null) {
+  return { ops: [], warnings: [], root: root ? path.resolve(root) : null };
+}
+
+function addOp(plan, op, target, reason) {
+  plan.ops.push({ op, target, reason });
+}
+
+function warn(plan, message) {
+  plan.warnings.push(message);
+}
+
+/** 列出目录下所有文件（递归），目录不存在返回空 */
+function listFilesRecursive(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const p = path.join(dir, name);
+    let st;
+    try {
+      st = fs.lstatSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      out.push(...listFilesRecursive(p));
+    } else {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * 规划：编辑器专属产物（skills / commands / hooks / rules）
+ *
+ * 策略：
+ * - `skillsDir/opsx-*` 与 `openspec-sync-specs` 等 SDD skill 目录 → 整体删（工具产物）
+ * - `opsxCommandsDir/*.md` → 只删含 BRIDGE_MARKER 的
+ * - `configDir/hooks/sdd-*.cjs` + `hook-gate-core.cjs` → 删（工具产物）
+ * - `configDir/settings.json` → 摘除受管 hook（保留文件）
+ */
+function planProfileArtifacts(plan, toolKey, cwd) {
+  const profile = getToolProfile(toolKey);
+  const config = buildToolConfigs()[toolKey];
+  if (!config) return;
+
+  // 1) skills：SDD 部署的 skill 目录（opsx-* + openspec-sync-specs/update-change + tdd-*）
+  if (profile.skillsDir) {
+    const skillsDir = path.join(cwd, profile.skillsDir);
+    if (fs.existsSync(skillsDir)) {
+      for (const name of fs.readdirSync(skillsDir)) {
+        const target = path.join(skillsDir, name);
+        if (!fs.statSync(target).isDirectory()) continue;
+        if (!/^(opsx-|openspec-(sync-specs|update-change)$)|^tdd-/.test(name)) continue;
+        addOp(plan, OP.DELETE_DIR, target, `${config.name} SDD skill 目录`);
+      }
+    }
+  }
+
+  // 2) Kunlun command bridge：只删含受管标记的
+  if (profile.requiresCommandBridge && profile.opsxCommandsDir) {
+    const opsxDir = path.join(cwd, profile.opsxCommandsDir);
+    for (const file of listFilesRecursive(opsxDir)) {
+      if (!file.endsWith('.md')) continue;
+      const content = fs.readFileSync(file, 'utf8');
+      if (isManagedBridgeFile(content)) {
+        addOp(plan, OP.DELETE_FILE, file, 'SDD command bridge（受管标记）');
+      } else {
+        addOp(plan, OP.KEEP, file, '非 SDD 受管命令，保留');
+      }
+    }
+  }
+
+  // 3) Hook 脚本目录（claude / codebuddy）
+  if (profile.hookProvider && profile.hookProvider !== 'none') {
+    const hooksDir = path.join(cwd, profile.configDir, 'hooks');
+    for (const file of listFilesRecursive(hooksDir)) {
+      const base = path.basename(file);
+      if (/^sdd-[\w-]+\.cjs$/.test(base) || base === 'hook-gate-core.cjs') {
+        addOp(plan, OP.DELETE_FILE, file, `${config.name} SDD hook 脚本`);
+      }
+    }
+
+    // 4) settings.json：摘除受管 hook
+    const settingsPath = path.join(cwd, profile.configDir, 'settings.json');
+    if (fs.existsSync(settingsPath)) {
+      addOp(plan, OP.STRIP_HOOKS, settingsPath, `${config.name} settings.json 摘除 SDD 受管 hook`);
+    }
+  }
+
+  // 5) rules 目录（cursor .cursor/rules 等）中的 SDD 规则
+  if (profile.rulesDir) {
+    const rulesDir = path.join(cwd, profile.rulesDir);
+    for (const file of listFilesRecursive(rulesDir)) {
+      const base = path.basename(file);
+      if (/^(sdd|opsx)[\w.-]*\.(md|mdc)$/i.test(base)) {
+        addOp(plan, OP.DELETE_FILE, file, `${config.name} SDD rules`);
+      }
+    }
+  }
+}
+
+/**
+ * 规划：spec 仓 `skywalk-sdd/git-hooks/` 目录（混合归属）
+ *
+ * init 侧 `ensureSpecGitHooks` 对同一目录用了两套策略：
+ * - `*.cjs`      工具产物 → OVERWRITE
+ * - `hooks.config` 用户配置 → SKIP_IF_EXISTS
+ *
+ * 卸载侧必须按同一判据逐项处理，否则「装进去的删不掉」或
+ * 「用户配置被静默重置」二者必居其一。
+ */
+function planSpecGitHooks(plan, hooksDir) {
+  for (const name of fs.readdirSync(hooksDir)) {
+    const target = path.join(hooksDir, name);
+    let st;
+    try {
+      st = fs.statSync(target);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      addOp(plan, OP.DELETE_DIR, target, 'SDD 运行时（工具内容）');
+      continue;
+    }
+    if (name === 'hooks.config') {
+      addOp(plan, OP.KEEP, target, '项目级门禁配置（init 用 SKIP_IF_EXISTS 保护），保留');
+      continue;
+    }
+    addOp(plan, OP.DELETE_FILE, target, 'SDD Git hook 脚本（工具产物）');
+  }
+}
+
+/**
+ * 规划：spec 仓内容
+ *
+ * 工具产物：skywalk-sdd/（除下方保留项）、openspec-templates/、操作手册
+ * 用户配置：modules.yaml、sdd.config.yaml、kb-state.json（仅 FULL 删）
+ * 团队/项目配置：project-identity.json、git-hooks/hooks.config（两种模式都保留）
+ * 文档工作区：openspec/（仅 FULL 整目录删）
+ *
+ * 注意：spec 仓自身的 `.git/hooks`（init 用 deployQualityGateTemplates 装的
+ * commit-msg / pre-commit / pre-push）由 buildUninstallPlan 调用 planCodeRepo
+ * 统一处理，保证「装得进去的一定摘得掉」，且与代码仓用同一套受管标记判据。
+ */
+function planSpecPackage(plan, specRoot, options) {
+  if (!specRoot || !fs.existsSync(specRoot)) return;
+
+  const skywalkDir = path.join(specRoot, 'skywalk-sdd');
+  if (fs.existsSync(skywalkDir)) {
+    if (options.mode === MODE.FULL) {
+      // 透明性：project-identity.json 是团队共享的 KB 身份（已提交 spec 仓 Git），
+      // 全量卸载会一并清除，需重跑 /opsx-kb-config 并重新提交。先单独列出，
+      // 让用户在预览里明确看到「团队配置将被清除」——比静默随目录消失可审计。
+      // 顺序必须在 DELETE_DIR 之前，否则父目录先被删、该项会被跳过。
+      const identity = path.join(skywalkDir, 'project-identity.json');
+      if (fs.existsSync(identity)) {
+        addOp(plan, OP.DELETE_FILE, identity, 'KB 项目身份（团队共享，需重跑 /opsx-kb-config 并重新提交）');
+      }
+      addOp(plan, OP.DELETE_DIR, skywalkDir, 'SDD 运行时（含 events/state 数据）');
+    } else {
+      // 工具内容删除：删工具脚本，保留运行时数据与用户/团队配置。
+      //
+      // 保留项判据是「重跑 init 能不能恢复」：
+      // - events/、state/        运行时数据（用户历史度量），init 不重建内容
+      // - project-identity.json  团队共享的 KB 身份，由 /opsx-kb-config 写、
+      //                          需提交 spec 仓 Git，删掉等于毁掉团队配置
+      // - git-hooks/hooks.config 项目级门禁参数（business_code_exts/strict/
+      //                          warn_only），init 用 SKIP_IF_EXISTS 保护，
+      //                          随目录一起删会让重跑 init 静默重置用户设置
+      const keepItems = new Map([
+        ['events', '运行时数据（度量），保留'],
+        ['state', '运行时数据（状态），保留'],
+        ['project-identity.json', 'KB 项目身份（团队共享，保留）'],
+      ]);
+      for (const name of fs.readdirSync(skywalkDir)) {
+        const target = path.join(skywalkDir, name);
+        if (keepItems.has(name)) {
+          addOp(plan, OP.KEEP, target, keepItems.get(name));
+          continue;
+        }
+        // git-hooks/ 是混合目录：*.cjs 是工具产物（OVERWRITE），
+        // hooks.config 是用户配置（SKIP_IF_EXISTS）→ 逐项判定，不整目录删。
+        if (name === 'git-hooks' && fs.statSync(target).isDirectory()) {
+          planSpecGitHooks(plan, target);
+          continue;
+        }
+        const st = fs.statSync(target);
+        addOp(plan, st.isDirectory() ? OP.DELETE_DIR : OP.DELETE_FILE, target, 'SDD 运行时（工具内容）');
+      }
+    }
+  }
+
+  const templatesDir = path.join(specRoot, 'openspec-templates');
+  if (fs.existsSync(templatesDir)) {
+    addOp(plan, OP.DELETE_DIR, templatesDir, '只读文档模板');
+  }
+
+  const manual = path.join(specRoot, 'openspec', 'kld-sdd操作手册.html');
+  if (fs.existsSync(manual)) {
+    addOp(plan, OP.DELETE_FILE, manual, 'SDD 操作手册');
+  }
+
+  // 用户产物
+  for (const name of ['modules.yaml', 'sdd.config.yaml']) {
+    const target = path.join(specRoot, name);
+    if (!fs.existsSync(target)) continue;
+    if (options.mode === MODE.FULL) {
+      addOp(plan, OP.DELETE_FILE, target, 'SDD 用户配置');
+    } else {
+      addOp(plan, OP.KEEP, target, '用户配置，保留');
+    }
+  }
+
+  // KB 绑定状态（含 API Key 与 spaceId/kbId，由 opsx-kb-config 写入 spec 仓根）。
+  // 与 skywalk-sdd/project-identity.json 同属 KB 配置，全量模式下须一并清除，
+  // 否则会留下「身份文件已删、绑定状态还在」的不一致中间态。
+  const kbState = path.join(specRoot, 'kb-state.json');
+  if (fs.existsSync(kbState)) {
+    if (options.mode === MODE.FULL) {
+      addOp(plan, OP.DELETE_FILE, kbState, 'KB 绑定状态（含 API Key）');
+    } else {
+      addOp(plan, OP.KEEP, kbState, 'KB 绑定状态（含 API Key），保留');
+    }
+  }
+
+  // openspec/ 是 SDD 的文档工作区（changes/ 变更提案、specs/ 规格与全局契约 overview.md、
+  // config.yaml），全部由 SDD 工具链创建与消费。
+  // 工具内容模式：不纳入计划（用户配置与文档内容一律保留）。
+  // 全量模式：整目录删除 —— 全量的语义就是「清空 SDD 在该仓的全部痕迹」，
+  //           不对单个文件做内容判定，避免残留半套目录结构。
+  if (options.mode === MODE.FULL) {
+    const openspecDir = path.join(specRoot, 'openspec');
+    if (fs.existsSync(openspecDir)) {
+      addOp(plan, OP.DELETE_DIR, openspecDir, 'SDD 文档工作区（changes/specs/config.yaml）');
+      warn(plan, `即将删除 SDD 文档工作区（含 changes/ 与 specs/ 内的业务文档）: ${openspecDir}`);
+    }
+  }
+}
+
+/**
+ * 规划：代码仓 / 工作区根产物
+ *
+ * - `.sdd.yaml`、`.sdd-spec-root`、`.sdd-workspace.yaml` → 用户配置，仅 FULL 删
+ * - `.git/hooks/{commit-msg,pre-commit,pre-push}` → 只删含受管标记的
+ * - `.gitignore` → 摘除 SDD 块
+ * - `git config --local sdd.specPath` → 删除
+ */
+function planCodeRepo(plan, repoRoot, options) {
+  if (!repoRoot || !fs.existsSync(repoRoot)) return;
+
+  for (const name of ['.sdd.yaml', '.sdd-spec-root', '.sdd-workspace.yaml']) {
+    const target = path.join(repoRoot, name);
+    if (!fs.existsSync(target)) continue;
+    if (options.mode === MODE.FULL) {
+      addOp(plan, OP.DELETE_FILE, target, 'SDD 用户配置');
+    } else {
+      addOp(plan, OP.KEEP, target, '用户配置，保留');
+    }
+  }
+
+  // Git hooks：只删含受管标记的
+  const hooksDir = path.join(repoRoot, '.git', 'hooks');
+  for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
+    const target = path.join(hooksDir, name);
+    if (!fs.existsSync(target)) continue;
+    let content = '';
+    try {
+      content = fs.readFileSync(target, 'utf8');
+    } catch {
+      continue;
+    }
+    if (content.includes(DEFAULT_HOOK_MARKER)) {
+      addOp(plan, OP.DELETE_FILE, target, 'SDD shell hook（受管标记）');
+    } else {
+      addOp(plan, OP.KEEP, target, '非 SDD 受管 hook，保留');
+    }
+  }
+
+  const gitignore = path.join(repoRoot, '.gitignore');
+  if (fs.existsSync(gitignore) && fs.readFileSync(gitignore, 'utf8').includes(GITIGNORE_MARKER)) {
+    addOp(plan, OP.STRIP_GITIGNORE, gitignore, '摘除 SDD 忽略块');
+  }
+
+  if (workspaceLayout.isGitRepo(repoRoot)) {
+    const specPath = sddConfig.gitConfig(repoRoot, 'sdd.specPath');
+    if (specPath) {
+      addOp(plan, OP.UNLINK_GIT_CONFIG, repoRoot, `git config --local sdd.specPath = ${specPath}`);
+    }
+  }
+}
+
+/**
+ * 生成卸载计划（纯计算，不落盘）
+ *
+ * @param {object} options
+ * @param {string} options.cwd 工作目录（代码仓 / 工作区根）
+ * @param {string[]} [options.tools] 要卸载的编辑器，缺省=全部
+ * @param {string} [options.mode] MODE.TOOLS_ONLY（默认）| MODE.FULL
+ * @param {string} [options.specRoot] 已确认的 spec 包裹包目录（CLI 交互层选定后传入）；
+ *   缺省时仅按权威来源（.sdd-spec-root → git config）保守定位
+ * @returns {{ok: boolean, plan: object, specRoot: string|null, message?: string}}
+ */
+function buildUninstallPlan(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const mode = options.mode === MODE.FULL ? MODE.FULL : MODE.TOOLS_ONLY;
+  const tools = Array.isArray(options.tools) && options.tools.length
+    ? options.tools
+    : listToolProfileIds();
+
+  const plan = createPlan(cwd);
+
+  // 编辑器专属产物：工作区根 / 当前目录
+  for (const toolKey of tools) {
+    planProfileArtifacts(plan, toolKey, cwd);
+  }
+
+  // spec 仓：优先用调用方（CLI 交互层）已确认的目录；
+  // 未指定时才自行定位 —— 此时仅取「权威来源」，不做全目录扫描。
+  // 定位职责已上移到 bin 层（listSpecCandidates + 用户单选 + 确认），
+  // 见 listSpecCandidatesForUninstall。本函数只接收结果，不猜。
+  const specRoot = options.specRoot
+    ? path.resolve(options.specRoot)
+    : resolveSpecRootForUninstall(cwd);
+  if (specRoot) {
+    plan.specRoot = path.resolve(specRoot);
+    planSpecPackage(plan, specRoot, { mode });
+    // spec 仓自身的 .git/hooks（init 装的 commit-msg / pre-commit / pre-push）
+    // 是工具产物，须摘除 —— 与代码仓共用同一套受管标记判据，
+    // 非受管 hook 与 .git 其余内容一律保留。
+    planCodeRepo(plan, specRoot, { mode });
+  } else {
+    warn(plan, '未定位到 spec 包裹包：spec 侧产物（skywalk-sdd/、openspec/ 等）未纳入计划');
+  }
+
+  // 代码仓 / 工作区根
+  planCodeRepo(plan, cwd, { mode });
+
+  // 工作区模式：子代码仓也要摘 hook。
+  //
+  // 排除所有 spec 候选目录：detectWorkspaceLayout 只挑一个作为 specRepo，
+  // 其余候选（如用户复制的 `erp-sdd-specs copy`）会被误归入 codeRepos，
+  // 进而被 planCodeRepo 摘掉 .git/hooks/ —— 那不是代码仓，是 spec 仓库/备份。
+  const layout = workspaceLayout.detectWorkspaceLayout(cwd);
+  if (layout.isWorkspace) {
+    const specDirs = new Set(
+      listSpecCandidatesForUninstall(cwd).map((c) => path.resolve(c.abs)),
+    );
+    if (specRoot) specDirs.add(path.resolve(specRoot));
+    for (const repo of layout.codeRepos) {
+      if (specDirs.has(path.resolve(repo.abs))) continue;
+      planCodeRepo(plan, repo.abs, { mode });
+    }
+  }
+
+  return { ok: true, plan, specRoot: specRoot || null, mode };
+}
+
+/**
+ * 枚举待卸载的 spec 包裹包候选（供 CLI 交互层让用户单选）。
+ *
+ * 返回全部候选并标注来源，由用户裁决；`erp-sdd-specs copy` 这类用户备份
+ * 会作为 'scan' 候选被列出，而不是被静默删除。
+ *
+ * 委托 `spec-detect.detectSpecCandidatesWithGit` —— 与 init 侧共用唯一入口。
+ *
+ * @param {string} cwd 工作目录
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
+ */
+function listSpecCandidatesForUninstall(cwd) {
+  return specDetect.detectSpecCandidatesWithGit(cwd || process.cwd());
+}
+
+/**
+ * 保守定位 spec 包裹包：仅取**权威来源**（.sdd-spec-root → git config）。
+ *
+ * 不复用 `findNestedSpecPackage` 的扫描来源 —— 判据命中不等于「当前项目的
+ * spec 仓」（用户备份同样命中）。需要扫描裁决时，由 CLI 层走
+ * `listSpecCandidatesForUninstall` + 用户单选。
+ *
+ * 实现上复用 `listSpecCandidatesForUninstall` 并筛出权威来源，而不是另写一遍
+ * hint / git config 的读取逻辑 —— 历史上这里是第二份实现，导致「卸载比 init
+ * 少认来源」（如 init 认 `.sdd.yaml mono`，卸载不认）的漂移。
+ * 候选已按 tier → 来源优先级排序，故 hint 天然优先于 git。
+ *
+ * @param {string} cwd 工作目录
+ * @returns {string|null} 权威来源指向的 spec 根；无权威来源时 null
+ */
+function resolveSpecRootForUninstall(cwd) {
+  const authoritative = listSpecCandidatesForUninstall(cwd)
+    .find((c) => c.source === 'hint' || c.source === 'git');
+  return authoritative ? path.resolve(authoritative.abs) : null;
+}
+
+/** 从 .gitignore 摘除 SDD 块（保留其余行） */
+function stripGitignoreBlock(filePath) {
+  const original = fs.readFileSync(filePath, 'utf8');
+  const lines = original.split(/\r?\n/);
+  const kept = [];
+  let skipping = false;
+  let removed = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // SDD 块由注释标题开头，遇到下一个非 SDD 注释标题或空行段落结束
+    if (/^#\s*KLD SDD/.test(trimmed)) {
+      skipping = true;
+      removed += 1;
+      continue;
+    }
+    if (skipping) {
+      // 块内：注释、空行、SDD 相关忽略行
+      if (trimmed === '' || trimmed.startsWith('#')) {
+        if (trimmed.startsWith('#') && !/SDD|Telemetry|Apply|KB 绑定/.test(trimmed)) {
+          // 遇到无关注释 → 块结束
+          skipping = false;
+          kept.push(line);
+          continue;
+        }
+        removed += 1;
+        continue;
+      }
+      if (/^(\.?[\w.*/-]*)(sdd|skywalk|worktrees|kb-state)/i.test(trimmed)
+        || /sdd/i.test(trimmed) || /skywalk/i.test(trimmed)
+        || /^\.worktrees\//.test(trimmed) || /personal-\*$/.test(trimmed)) {
+        removed += 1;
+        continue;
+      }
+      skipping = false;
+      kept.push(line);
+      continue;
+    }
+    kept.push(line);
+  }
+
+  const next = kept.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
+  return { changed: removed > 0 && next !== original, next, removed };
+}
+
+/** 从 settings.json 摘除受管 hook */
+function stripSettingsHooks(filePath, provider) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch {
+    return { ok: false, error: '不是合法 JSON，已跳过（请手工处理）' };
+  }
+  const stripped = stripManagedHooks(settings, provider);
+  const next = JSON.stringify(stripped, null, 2) + '\n';
+  if (next === raw) return { ok: true, changed: false };
+  fs.writeFileSync(filePath, next, 'utf8');
+  return { ok: true, changed: true };
+}
+
+/** 判断目录是否为空 */
+function isEmptyDir(dir) {
+  try {
+    return fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** provider 判定：从 settings.json 路径反推 */
+function providerFromSettingsPath(settingsPath) {
+  return /\.claude[\\/]/.test(settingsPath) ? PROVIDERS.CLAUDE : PROVIDERS.CODEBUDDY;
+}
+
+/**
+ * 执行卸载计划
+ *
+ * @param {object} plan buildUninstallPlan 产出的 plan
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun] 只打印，不落盘
+ * @param {function} [options.log] 日志输出函数
+ * @returns {{ok: boolean, applied: number, skipped: number, errors: string[]}}
+ */
+function applyUninstallPlan(plan, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const log = typeof options.log === 'function' ? options.log : console.log;
+  const errors = [];
+  let applied = 0;
+  let skipped = 0;
+
+  for (const item of plan.ops) {
+    if (item.op === OP.KEEP) {
+      skipped += 1;
+      log(`   · 保留 ${path.basename(item.target)}（${item.reason}）`);
+      continue;
+    }
+
+    try {
+      switch (item.op) {
+        case OP.DELETE_FILE:
+          if (fs.existsSync(item.target)) {
+            if (!dryRun) fs.unlinkSync(item.target);
+            applied += 1;
+            log(`   ${dryRun ? '将删除' : '✓ 已删除'} 文件 ${item.target}`);
+          }
+          break;
+
+        case OP.DELETE_DIR:
+          if (fs.existsSync(item.target)) {
+            const count = listFilesRecursive(item.target).length;
+            if (!dryRun) fs.rmSync(item.target, { recursive: true, force: true });
+            applied += 1;
+            log(`   ${dryRun ? '将删除' : '✓ 已删除'} 目录 ${item.target}（${count} 文件）`);
+          }
+          break;
+
+        case OP.STRIP_HOOKS: {
+          if (!fs.existsSync(item.target)) break;
+          if (dryRun) {
+            applied += 1;
+            log(`   将摘除 ${item.target} 中的 SDD 受管 hook（保留其余配置）`);
+            break;
+          }
+          const res = stripSettingsHooks(item.target, providerFromSettingsPath(item.target));
+          if (!res.ok) {
+            errors.push(`${item.target}: ${res.error}`);
+            log(`   ⚠️  ${item.target}: ${res.error}`);
+          } else if (res.changed) {
+            applied += 1;
+            log(`   ✓ 已摘除 ${item.target} 中的 SDD 受管 hook`);
+          } else {
+            // 无受管 hook 可摘 → 计为保留，保证重复卸载 applied 归零（幂等）
+            skipped += 1;
+            log(`   · 保留 ${item.target}（无 SDD 受管 hook）`);
+          }
+          break;
+        }
+
+        case OP.STRIP_GITIGNORE: {
+          if (!fs.existsSync(item.target)) break;
+          if (dryRun) {
+            applied += 1;
+            log(`   将摘除 ${item.target} 中的 SDD 忽略块（保留其余行）`);
+            break;
+          }
+          const res = stripGitignoreBlock(item.target);
+          if (res.changed) {
+            fs.writeFileSync(item.target, res.next, 'utf8');
+            applied += 1;
+            log(`   ✓ 已摘除 ${item.target} 中的 SDD 忽略块（${res.removed} 行）`);
+          } else {
+            skipped += 1;
+            log(`   · 保留 ${item.target}（无 SDD 块可摘）`);
+          }
+          break;
+        }
+
+        case OP.UNLINK_GIT_CONFIG: {
+          if (dryRun) {
+            applied += 1;
+            log('   将删除 git config --local sdd.specPath');
+            break;
+          }
+          const res = sddConfig.unsetSpecPath(item.target);
+          if (!res.ok) {
+            errors.push(`${item.target}: ${res.message || '删除 sdd.specPath 失败'}`);
+            log('   ⚠️  删除 git config --local sdd.specPath 失败');
+          } else if (res.removed) {
+            applied += 1;
+            log('   ✓ 已删除 git config --local sdd.specPath');
+          } else {
+            // 配置项本就不存在 → 保留，保证幂等
+            skipped += 1;
+            log('   · 保留 git config（sdd.specPath 本就不存在）');
+          }
+          break;
+        }
+
+        default:
+          break;
+      }
+    } catch (error) {
+      errors.push(`${item.target}: ${error.message}`);
+      log(`   ⚠️  ${item.target}: ${error.message}`);
+    }
+  }
+
+  // 清理变空的目录：仅清理由本计划删除行为导致的空壳目录。
+  //
+  // 两条安全边界（缺一不可）：
+  // 1) 绝不清理 plan.root（工作目录）及其祖先 —— 候选父目录是逐级向上收集的，
+  //    没有这道闸门时，一个空的工作目录会被 rmdir 掉，甚至连带其父目录。
+  // 2) KEEP 项（如 skywalk-sdd/events、state）即使变空也必须保留，
+  //    否则会把用户明确要保留的运行时数据目录一并抹掉。
+  if (!dryRun) {
+    const rootAbs = plan.root ? path.resolve(plan.root) : null;
+    const protectedDirs = new Set(
+      plan.ops.filter(i => i.op === OP.KEEP).map(i => path.resolve(i.target)),
+    );
+
+    const isProtected = (dir) => {
+      const abs = path.resolve(dir);
+      // 工作目录本身及其祖先目录不可清理
+      if (rootAbs && (abs === rootAbs || rootAbs.startsWith(abs + path.sep))) return true;
+      if (protectedDirs.has(abs)) return true;
+      // 祖先目录被保护时，其子目录同样不可清理
+      for (const keep of protectedDirs) {
+        if (keep.startsWith(abs + path.sep)) return true;
+      }
+      return false;
+    };
+
+    const candidates = new Set();
+    for (const item of plan.ops) {
+      if (item.op !== OP.DELETE_FILE && item.op !== OP.DELETE_DIR) continue;
+      let dir = path.dirname(item.target);
+      // 逐级向上收集候选父目录（深度优先，先深后浅）
+      for (let i = 0; i < 4 && dir && dir !== path.dirname(dir); i += 1) {
+        candidates.add(dir);
+        dir = path.dirname(dir);
+      }
+    }
+
+    const ordered = [...candidates].sort((a, b) => b.length - a.length);
+    for (const dir of ordered) {
+      if (isProtected(dir)) continue;
+      if (!fs.existsSync(dir) || !isEmptyDir(dir)) continue;
+      try {
+        fs.rmdirSync(dir);
+      } catch { /* 目录非空或权限不足，忽略 */ }
+    }
+
+    // spec 仓目录本身：产物清空后若已无任何文件（含 .git 内），一并删除。
+    // 判据是「递归无文件」而非「无子项」——.git/ 即使只剩空目录结构也算残留。
+    // 有文件则保留：目录名由用户 --spec-path 指定，工具不擅自删非空目录。
+    const specAbs = plan.specRoot ? path.resolve(plan.specRoot) : null;
+    if (specAbs && fs.existsSync(specAbs) && isProtected(specAbs) === false) {
+      if (listFilesRecursive(specAbs).length === 0) {
+        try {
+          fs.rmSync(specAbs, { recursive: true, force: true });
+          applied += 1;
+          log(`   ✓ 已删除 spec 仓目录 ${specAbs}（无残留文件）`);
+        } catch { /* 权限不足等，忽略 */ }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, applied, skipped, errors };
+}
+
+/** 卸载方式的中文标签（供 CLI 层复用，避免文案漂移） */
+function modeLabel(mode) {
+  return mode === MODE.FULL
+    ? '全量卸载（含用户配置与运行时数据）'
+    : '工具内容卸载（保留用户配置）';
+}
+
+/**
+ * 卸载执行（纯业务，无交互）
+ *
+ * CLI 参数解析与全部交互（方式选择 / 预览 / 确认）都在 bin/ 层完成；
+ * 本函数只接收已解析的选项对象，不读取 process.argv，也不询问用户。
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]    工作目录（代码仓 / 工作区根），缺省 process.cwd()
+ * @param {string[]} [opts.tools] 要卸载的编辑器 id 列表，缺省=全部
+ * @param {string} [opts.mode]   MODE.TOOLS_ONLY（默认）| MODE.FULL
+ * @param {boolean} [opts.dryRun] 只打印计划，不落盘
+ * @param {object} [opts.plan]   复用调用方已算好的计划（避免重复计算）
+ * @param {boolean} [opts.showWarnings] 是否打印 plan.warnings，缺省 true
+ * @returns {{ok: boolean, applied: number, skipped: number, errors: string[]}}
+ */
+function main(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const mode = opts.mode === MODE.FULL ? MODE.FULL : MODE.TOOLS_ONLY;
+
+  const plan = opts.plan || buildUninstallPlan({ cwd, tools: opts.tools, mode }).plan;
+  const result = applyUninstallPlan(plan, { dryRun: Boolean(opts.dryRun) });
+
+  // 交互路径下 CLI 层已用 printPlanPreview 打过同一份 warnings，
+  // 由调用方传 showWarnings:false 避免重复刷屏；非交互路径缺省照常打印。
+  if (opts.showWarnings !== false && plan.warnings.length) {
+    console.log('');
+    for (const w of plan.warnings) console.log(`⚠️  ${w}`);
+  }
+
+  console.log('');
+  console.log(`✅ 完成：处理 ${result.applied} 项，保留 ${result.skipped} 项`);
+  if (result.errors.length) {
+    console.log(`⚠️  ${result.errors.length} 项失败：`);
+    for (const e of result.errors) console.log(`   - ${e}`);
+  }
+  if (opts.dryRun) {
+    console.log('');
+    console.log('ℹ️  这是预演结果，未修改任何文件。去掉 --dry-run 执行实际卸载。');
+  }
+  return result;
+}
+
+module.exports = {
+  MODE,
+  OP,
+  modeLabel,
+  main,
+  buildUninstallPlan,
+  applyUninstallPlan,
+  stripGitignoreBlock,
+  listSpecCandidatesForUninstall,
+};