opencode-skills-doctor 0.3.6 → 0.3.7

package/README.md

@@ -89,9 +89,11 @@ skills-doctor update --into .\team-skills
 ```
 
 - The output directory is a real OpenCode skill directory, so **`check` picks the update up immediately**;
+- Overwrites files in place and **deletes files that the new version no longer lists** (no stale leftovers from the old version);
 - Writes `.skills-doctor.lock.json` (schema v2: a sha1 for every file);
 - `check` reads that lock: shows managed versions, detects hand edits (`managed-drift`) and missing files (`managed-missing`);
-- Running `update` again re-downloads drifted files (self-healing).
+- Running `update` again re-downloads drifted files (self-healing);
+- Use `--prune` to delete skills that disappeared from the catalog (by default they are reported but kept).
 
 ## Configuration
 

package/README.zh-CN.md

@@ -89,9 +89,11 @@ skills-doctor update --into .\team-skills
 ```
 
 - 落盘位置就是 opencode 的 skill 目录 → **更新完 `check` 立刻能检测到**；
+- 原地覆盖文件，并**删除新版本里已不存在的文件**（不会残留旧版本文件）；
 - 写 `.skills-doctor.lock.json`（v2：记录每个文件的 sha1）；
 - `check` 会读这个 lock：显示托管版本、发现文件被手改（`managed-drift`）、文件被删（`managed-missing`）；
-- 再跑一次 `update` 会自动重下被改坏的文件（drift 自愈）。
+- 再跑一次 `update` 会自动重下被改坏的文件（drift 自愈）；
+- 用 `--prune` 删除 catalog 中已下架的 skill（默认只提示、不删）。
 
 ## 配置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Audit, fix and update agent skills: per-step context cost, shadowed duplicates, safe archive, catalog sync. CLI, OpenCode plugin and MCP server (Claude Code / Codex / any MCP client).",
   "type": "module",
   "exports": {

package/src/catalog.mjs

@@ -68,6 +68,20 @@ function lockEntryVersion(entry) {
   return null
 }
 
+function pruneEmptyDirs(dir, stopDir) {
+  const stop = path.resolve(stopDir)
+  let current = path.resolve(dir)
+  while (current !== stop && current.startsWith(stop + path.sep)) {
+    try {
+      if (fs.readdirSync(current).length > 0) return
+      fs.rmdirSync(current)
+    } catch {
+      return
+    }
+    current = path.dirname(current)
+  }
+}
+
 /** 本地文件是否仍与 lock 里的哈希一致（无哈希时视为一致）。 */
 function filesMatch(into, name, files, t) {
   if (!files || typeof files !== "object") return true
@@ -93,14 +107,27 @@ export async function fetchCatalogIndex(url, { fetchImpl = fetch, timeoutMs = 15
  * 更新器：对比 HTTP catalog 的 version，必要时下载到 into 目录并写 lock。
  * lock 里记录每个文件的 sha1，检测器据此判断「更新后是否被改过」。
  */
-export async function updateCatalogs(catalogs, { into = process.cwd(), checkOnly = false, fetchImpl = fetch, t = translator("en") } = {}) {
+export async function updateCatalogs(
+  catalogs,
+  { into = process.cwd(), checkOnly = false, fetchImpl = fetch, t = translator("en"), prune = false } = {},
+) {
   const lockPath = path.join(into, LOCK_NAME)
   const lock = readLockFile(into) ?? { version: LOCK_VERSION, catalogs: {} }
   const lockTooNew = Number(lock.version ?? 1) > LOCK_VERSION
   const results = []
 
   for (const catalog of catalogs) {
-    const result = { url: catalog.url, error: null, updated: [], unchanged: [], invalid: [], files: 0 }
+    const result = {
+      url: catalog.url,
+      error: null,
+      updated: [],
+      unchanged: [],
+      invalid: [],
+      orphaned: [],
+      pruned: [],
+      removedFiles: [],
+      files: 0,
+    }
     try {
       const { base, skills } = await fetchCatalogIndex(catalog.url, { fetchImpl, t })
       const baseUrl = new URL(base + "/")
@@ -144,10 +171,43 @@ export async function updateCatalogs(catalogs, { into = process.cwd(), checkOnly
           hashes[file] = sha1Buffer(buffer)
           result.files++
         }
+
+        // 新版本里已被删除的文件：从本地清掉，避免旧文件残留
+        if (prevHashes) {
+          for (const oldFile of Object.keys(prevHashes)) {
+            if (entry.files.includes(oldFile)) continue
+            const target = resolveInside(path.join(into, entry.name), oldFile, t)
+            if (!fs.existsSync(target)) continue
+            fs.rmSync(target, { force: true })
+            result.removedFiles.push({ name: entry.name, file: oldFile })
+            pruneEmptyDirs(path.dirname(target), path.join(into, entry.name))
+          }
+        }
+
         nextSkills[entry.name] = { version, files: hashes }
         result.updated.push({ name: entry.name, version, previous: previousVersion, reason: drifted ? "drift" : null })
       }
 
+      const validNames = new Set(
+        skills.filter((entry) => validateCatalogEntry(entry, t).length === 0).map((entry) => entry.name),
+      )
+      const orphaned = Object.keys(previousSkills).filter((name) => !validNames.has(name))
+      result.orphaned = orphaned
+
+      if (!checkOnly) {
+        if (prune) {
+          for (const name of orphaned) {
+            const dir = resolveInside(into, name, t)
+            if (!fs.existsSync(dir)) continue
+            fs.rmSync(dir, { recursive: true, force: true })
+            result.pruned.push(name)
+          }
+        } else {
+          // 不 prune 时保留 lock 记录，方便下次继续跟踪
+          for (const name of orphaned) nextSkills[name] = previousSkills[name]
+        }
+      }
+
       if (!checkOnly) lock.catalogs[catalog.url] = { skills: nextSkills }
     } catch (err) {
       result.error = String(err?.message ?? err)

package/src/cli.mjs

@@ -55,6 +55,7 @@ function parseArgs(argv) {
     hide: [],
     into: null,
     checkOnly: false,
+    prune: false,
     help: false,
     version: false,
   }
@@ -112,6 +113,9 @@ function parseArgs(argv) {
       case "--check-only":
         options.checkOnly = true
         break
+      case "--prune":
+        options.prune = true
+        break
       case "-h":
       case "--help":
         options.help = true
@@ -299,11 +303,12 @@ async function runUpdate(discovered, options, cwd, t) {
   const { lockPath, results, lockTooNew } = await updateCatalogs(discovered.catalogs, {
     into,
     checkOnly: options.checkOnly,
+    prune: options.prune,
     t,
   })
 
   if (options.json) {
-    console.log(JSON.stringify({ lockPath, checkOnly: options.checkOnly, results }, null, 2))
+    console.log(JSON.stringify({ lockPath, checkOnly: options.checkOnly, prune: options.prune, results }, null, 2))
     return results.some((r) => r.error) ? 1 : 0
   }
 
@@ -329,6 +334,12 @@ async function runUpdate(discovered, options, cwd, t) {
     }
     if (result.unchanged.length) console.log(dim(t("update.unchanged", { count: result.unchanged.length })))
     if (result.files) console.log(dim(t("update.files", { count: result.files })))
+    if (result.removedFiles.length) console.log(dim(t("update.removedFiles", { count: result.removedFiles.length })))
+    if (result.pruned.length) {
+      console.log(yellow(t("update.pruned", { count: result.pruned.length, names: result.pruned.join(", ") })))
+    } else if (result.orphaned.length) {
+      console.log(yellow(t("update.orphaned", { count: result.orphaned.length })))
+    }
     for (const invalid of result.invalid) {
       console.log(yellow(t("update.skipped", { name: invalid.name, problems: invalid.problems.join("; ") })))
     }

package/src/i18n.mjs

@@ -26,6 +26,7 @@ Options:
   --hide <ids>         fix: hide skills with metadata.opencode/autoinvoke: false (comma separated)
   --into <dir>         update: output directory (default: .opencode/skills)
   --check-only         update: only report available updates
+  --prune              update: delete skills that disappeared from the catalog
   -h, --help           show this help
   -v, --version        print version
 
@@ -69,6 +70,9 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.files": "  · files written {count}",
     "update.skipped": "  ! skipped {name}: {problems}",
     "update.empty": "  · catalog is empty",
+    "update.removedFiles": "  · removed {count} stale files",
+    "update.pruned": "  · pruned {count} skills no longer in the catalog: {names}",
+    "update.orphaned": "  ! {count} skills are no longer in the catalog (use --prune to delete them)",
     "update.lock": "  lock: {path} ({name})",
     "update.lockTooNew": "  ! lock is newer than this tool; parsed in compatibility mode (unknown fields ignored)",
     "update.detector": "  check now sees these skills ({dir} is where opencode reads)",
@@ -168,6 +172,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --hide <ids>        fix: 给指定 skill 加 metadata.opencode/autoinvoke: false（逗号分隔）
   --into <dir>        update 的落盘目录（默认 .opencode/skills）
   --check-only        update 只报告可用更新，不下载
+  --prune             update: 删除 catalog 中已移除的 skill
   -h, --help          帮助
   -v, --version       版本
 
@@ -211,6 +216,9 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.files": "  · 写入文件 {count}",
     "update.skipped": "  ! 跳过 {name}: {problems}",
     "update.empty": "  · catalog 为空",
+    "update.removedFiles": "  · 删除旧版本残留文件 {count} 个",
+    "update.pruned": "  · 清理 catalog 中已移除的 skill {count} 个: {names}",
+    "update.orphaned": "  ! {count} 个 skill 已不在 catalog 中（加 --prune 可删除本地残留）",
     "update.lock": "  lock: {path}（{name}）",
     "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",