@andyqiu/codeforge 0.6.4 → 0.6.6

package/install.mjs

@@ -176,8 +176,15 @@ const MANAGED_DIRS = ["codeforge", "agents", "commands", "workflows", "context-t
 // 细粒度卸载：只删 CodeForge 自己的 skill
 const OWNED_SKILLS = ["ambiguity-gate", "devils-advocate", "ears-zh", "example-mapping", "success-criteria", "weighted-dimensions"]
 
-// 文件级 copy（.md，排除 README/_*/.bak/隐藏）
+// 文件级 copy（.md，排除 README/_*/.bak/隐藏）— per-file upsert + manifest 差集清理，不 rmrf 整目录
+// ADR:install-whitelist-md-files
 const MD_COPY_DIRS = [["agents", "agents"], ["commands", "commands"]]
+
+// codeforge 自维护的 .md 安装清单：记录"上一版 codeforge 在各目标目录装了哪些 .md"。
+// 用途：install 时算差集（manifest − 本次源）精准清理本版已删除的旧 codeforge 文件，
+//       第三方 .md（如 teamkit-git.md）从不写入 manifest → 永不被清理（零副作用）。
+// 位置在 codeforge/ 子目录下，uninstall 的 rmrf(codeforge/) 会自然清掉，无需额外卸载逻辑。
+const MD_MANIFEST_REL = "codeforge/installed-md-manifest.json"
 // 整目录拷贝
 const COPY_DIRS = [
   ["workflows", "workflows"],
@@ -450,31 +457,75 @@ function installBundle({ targetRoot, bundleSrc }) {
   vok(`VERSION → ${versionFile} (${version})`)
 }
 
+// ADR:install-whitelist-md-files —— manifest 自维护：不再 rmrf 整目录，
+// 读 manifest 算差集精准清理旧 codeforge .md，第三方 .md 零副作用。
 function installMdDirs({ targetRoot }) {
+  // 步骤 1：读上一版 manifest（不存在 → 各目录空列表 = 首次安装）
+  const prevManifest = readMdManifest(targetRoot)
+  const nextManifest = {}
+
   for (const [srcName, dstName] of MD_COPY_DIRS) {
     const srcPath = path.join(SOURCE_ROOT, srcName)
     const dstPath = path.join(targetRoot, dstName)
     if (!fs.existsSync(srcPath) || !fs.statSync(srcPath).isDirectory()) {
       vlog(`源目录不存在，跳过: ${srcPath}`)
+      // 源目录缺失：本版该目录装 0 个文件，manifest 记空（差集会清掉上一版全部该目录文件）
+      nextManifest[dstName] = []
+      const prevList = prevManifest[dstName] ?? []
+      pruneStale({ dstPath, prevList, sourceSet: new Set() })
       continue
     }
-    if (fs.existsSync(dstPath) || isSymlink(dstPath)) rmrf(dstPath)
-    ensureDir(dstPath)
-    let count = 0
-    const entries = DRY_RUN ? safeReaddir(srcPath) : fs.readdirSync(srcPath)
-    for (const base of entries) {
+    ensureDir(dstPath) // 不再 rmrf；幂等建目录
+
+    // 步骤 2：扫源目录 → sourceSet（本版要装的文件名集合）
+    const sourceFiles = []
+    const srcEntries = fs.readdirSync(srcPath)
+    for (const base of srcEntries) {
       if (!shouldCopyMd(base)) continue
-      const f = path.join(srcPath, base)
-      try {
-        if (!fs.statSync(f).isFile()) continue
-      } catch {
-        continue
+      try { if (!fs.statSync(path.join(srcPath, base)).isFile()) continue } catch { continue }
+      sourceFiles.push(base)
+    }
+    const sourceSet = new Set(sourceFiles)
+
+    // 步骤 3：差集清理 prevManifest[dir] − sourceSet（仅删确实存在的）
+    const prevList = prevManifest[dstName] ?? []
+    const pruned = pruneStale({ dstPath, prevList, sourceSet })
+
+    // 步骤 4：upsert —— 把 sourceSet 文件复制到目标（覆盖同名，不动其他文件）
+    // ADR:install-manifest-actual-copied-consistency —— manifest 记录实际落盘（事实），非源扫描意图
+    let count = 0
+    const copiedOk = []  // 仅含 post-copy existsSync 复核通过的文件名
+    if (!DRY_RUN) {
+      // 真实 copy：收集 copiedOk，逐文件复核，复核失败 fail-loud
+      for (const base of sourceFiles) {
+        const src = path.join(srcPath, base)
+        const dst = path.join(dstPath, base)
+        fs.copyFileSync(src, dst)
+        if (!fs.existsSync(dst)) {
+          // copy 后文件仍不存在：可能是 FS 异常（NFS/虚拟 FS 等），fail-loud
+          throw new Error(`copy 后文件不存在（existsSync 复核失败）：${dst}`)
+        }
+        copiedOk.push(base)
+        count++
+      }
+    } else {
+      // DRY_RUN：run() 已 vlog，不执行 copy，copiedOk 保持空（dry-run 不落盘）
+      for (const base of sourceFiles) {
+        vlog(`[dry-run] cp ${path.join(srcPath, base)} ${dstPath}/`)
+        count++
       }
-      run(`cp ${f} ${dstPath}/`, () => fs.copyFileSync(f, path.join(dstPath, base)))
-      count++
     }
-    vok(`${srcName}/ → ${dstPath}  (${count} 个 .md)`)
+
+    // 步骤 5：新 manifest = copiedOk（实际落盘文件，非 sourceFiles 意图）
+    // DRY_RUN 下 copiedOk 为空，由 run() 包裹的 writeMdManifest 负责 vlog 不落盘
+    nextManifest[dstName] = DRY_RUN ? [...sourceFiles] : copiedOk
+
+    vok(`${srcName}/ → ${dstPath}  (${count} 个 .md upsert, ${pruned} 个过期清理, 第三方文件保留)`)
   }
+
+  // 步骤 5（落盘）：写新 manifest
+  ensureDir(path.join(targetRoot, "codeforge")) // 幂等，保证父目录存在
+  run(`write md manifest → ${MD_MANIFEST_REL}`, () => writeMdManifest(targetRoot, nextManifest))
 }
 
 function safeReaddir(p) {
@@ -485,6 +536,125 @@ function safeReaddir(p) {
   }
 }
 
+// 读 manifest：不存在 / 解析失败 → 返回各目录空列表（首次安装走此分支）。
+// 返回结构：{ [dstName]: string[] }，含 MD_COPY_DIRS 的所有 dstName 键。
+// 损坏 JSON 保守降级为"首次安装"（差集空 → 不误删）。
+function readMdManifest(targetRoot) {
+  const empty = {}
+  for (const [, dstName] of MD_COPY_DIRS) empty[dstName] = []
+  const p = path.join(targetRoot, MD_MANIFEST_REL)
+  let raw
+  try {
+    raw = fs.readFileSync(p, "utf8")
+  } catch {
+    return empty // 文件不存在 → 首次安装
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    const out = {}
+    for (const [, dstName] of MD_COPY_DIRS) {
+      const v = parsed?.[dstName]
+      out[dstName] = Array.isArray(v) ? v.filter((x) => typeof x === "string") : []
+    }
+    return out
+  } catch {
+    return empty // 损坏的 manifest → 视为首次安装（保守：差集为空，不误删）
+  }
+}
+
+// 写 manifest：atomicWriteJson（同目录 tmp + rename）。data 形如 { agents: [...], commands: [...] }。
+// 调用方需保证 codeforge/ 目录已存在（installBundle 先于 installMdDirs 跑，已建 codeforge/）。
+function writeMdManifest(targetRoot, data) {
+  const p = path.join(targetRoot, MD_MANIFEST_REL)
+  atomicWriteJson(p, data)
+}
+
+// compareManifestVsDisk：三方比对（manifest / disk / source）
+// ADR:codeforge-doctor-command — doctor 与 install 共享的纯函数
+// 返回：
+//   missing[]   = manifest 登记但 disk 无（来源2：外部腐蚀）
+//   unmanaged[] = source 有（经 shouldCopyMd 过滤）但 disk 无（来源1/2：未安装 / 被删）
+//   stale[]     = disk 有 & source 有 但 manifest 无（manifest 失配，可能未更新）
+// 第三方文件（disk 有但不在 manifest 也不在 source）→ 不纳入任何桶（静默跳过）
+function compareManifestVsDisk({ targetRoot, sourceRoot }) {
+  const manifest = readMdManifest(targetRoot)
+  const missing = []
+  const unmanaged = []
+  const stale = []
+
+  for (const [srcName, dstName] of MD_COPY_DIRS) {
+    const srcPath = path.join(sourceRoot, srcName)
+    const dstPath = path.join(targetRoot, dstName)
+
+    // source 扫描（经 shouldCopyMd 过滤）
+    const sourceFiles = new Set()
+    try {
+      const entries = fs.readdirSync(srcPath)
+      for (const base of entries) {
+        if (!shouldCopyMd(base)) continue
+        try { if (!fs.statSync(path.join(srcPath, base)).isFile()) continue } catch { continue }
+        sourceFiles.add(base)
+      }
+    } catch {
+      // 源目录不存在（发布包未含该目录）→ sourceFiles 为空，正常走后续逻辑
+    }
+
+    // manifest 登记列表
+    const manifestList = manifest[dstName] ?? []
+    const manifestSet = new Set(manifestList)
+
+    // disk 实际文件（目录不存在时视为空）
+    const diskSet = new Set()
+    try {
+      const diskEntries = fs.readdirSync(dstPath)
+      for (const base of diskEntries) {
+        try { if (!fs.statSync(path.join(dstPath, base)).isFile()) continue } catch { continue }
+        diskSet.add(base)
+      }
+    } catch {
+      // 目录不存在 → diskSet 为空
+    }
+
+    // D1：manifest 登记但 disk 无
+    for (const base of manifestList) {
+      if (!diskSet.has(base)) {
+        missing.push({ dir: dstName, file: base })
+      }
+    }
+
+    // D2：source 有但 disk 无（未安装或被删）
+    for (const base of sourceFiles) {
+      if (!diskSet.has(base)) {
+        unmanaged.push({ dir: dstName, file: base })
+      }
+    }
+
+    // D3：disk 有 & source 有 但 manifest 无（manifest 失配）
+    for (const base of diskSet) {
+      if (sourceFiles.has(base) && !manifestSet.has(base)) {
+        stale.push({ dir: dstName, file: base })
+      }
+    }
+  }
+
+  return { missing, unmanaged, stale }
+}
+
+// 差集清理：prevList − sourceSet，仅删目标目录里确实存在的文件。返回清理计数。
+// 第三方文件（如 teamkit-git.md）从不写入 manifest → 不在 prevList → 永不被删。
+function pruneStale({ dstPath, prevList, sourceSet }) {
+  let pruned = 0
+  const actual = new Set(safeReaddir(dstPath))
+  for (const base of prevList) {
+    if (sourceSet.has(base)) continue // 本版仍发布 → 保留
+    if (!actual.has(base)) continue   // 目标里已不存在 → 无需删
+    const stale = path.join(dstPath, base)
+    run(`rm ${stale}（过期 codeforge .md）`, () => fs.rmSync(stale, { force: true }))
+    pruned++
+  }
+  return pruned
+}
+
 function installCopyDirs({ targetRoot }) {
   for (const [srcName, dstName] of COPY_DIRS) {
     const srcPath = path.join(SOURCE_ROOT, srcName)
@@ -742,6 +912,11 @@ export {
   LEGACY_DIRS,
   MANAGED_DIRS,
   OWNED_SKILLS,
+  readMdManifest,
+  writeMdManifest,
+  MD_MANIFEST_REL,
+  compareManifestVsDisk,
+  MD_COPY_DIRS,
 }
 
 // main 守卫：仅作为脚本直接运行时执行

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andyqiu/codeforge",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "CodeForge — opencode 的零侵入扩展包",
   "type": "module",
   "private": false,