opencode-skills-doctor 0.0.0-stage → 0.3.2

package/src/discover.mjs

@@ -0,0 +1,308 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+import { parseFrontmatter, estimateTokens, sha1 } from "./parse.mjs"
+
+const CONFIG_FILES = ["opencode.jsonc", "opencode.json"]
+const SKIP_DIRS = new Set(["node_modules", ".git", ".hg", ".svn", "dist", "build", ".venv", "__pycache__"])
+
+export function expandHome(p, home = os.homedir()) {
+  if (p === "~") return home
+  if (p.startsWith("~/") || p.startsWith("~\\")) return path.join(home, p.slice(2))
+  return p
+}
+
+/** 去掉 JSONC 的注释和尾逗号，字符串内的内容不动。 */
+export function stripJsonc(text) {
+  let out = ""
+  let inString = false
+  let escaped = false
+  let inLine = false
+  let inBlock = false
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    const next = text[i + 1]
+
+    if (inLine) {
+      if (ch === "\n") {
+        inLine = false
+        out += ch
+      }
+      continue
+    }
+    if (inBlock) {
+      if (ch === "*" && next === "/") {
+        inBlock = false
+        i++
+      }
+      continue
+    }
+    if (inString) {
+      out += ch
+      if (escaped) escaped = false
+      else if (ch === "\\") escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+      continue
+    }
+    if (ch === "/" && next === "/") {
+      inLine = true
+      i++
+      continue
+    }
+    if (ch === "/" && next === "*") {
+      inBlock = true
+      i++
+      continue
+    }
+    out += ch
+  }
+
+  return out.replace(/,(\s*[}\]])/g, "$1")
+}
+
+export function readJsoncFile(file) {
+  const text = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")
+  return JSON.parse(stripJsonc(text))
+}
+
+export function findProjectRoot(start) {
+  let dir = path.resolve(start)
+  for (;;) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** root 到 cwd 的路径链（远端在前，cwd 在最后）。 */
+export function pathChain(root, cwd) {
+  const stop = path.resolve(root)
+  const start = path.resolve(cwd)
+  const rel = path.relative(stop, start)
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return [start]
+
+  const chain = []
+  let dir = start
+  for (;;) {
+    chain.push(dir)
+    if (dir === stop) break
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return chain.reverse()
+}
+
+function configCandidates(dir) {
+  return CONFIG_FILES.map((name) => path.join(dir, name))
+}
+
+function isUnder(parent, child) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child))
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))
+}
+
+/**
+ * 按官方文档的注册顺序返回 skill 来源（顺序即优先级，越后越高）：
+ *  1. ~/.claude/skills
+ *  2. 项目 .claude/skills（远端 → cwd）
+ *  3. ~/.agents/skills
+ *  4. 项目 .agents/skills（远端 → cwd）
+ *  5. ~/.config/opencode/skills
+ *  6. 项目 .opencode/skills（项目根 → cwd）
+ *  7. opencode.json(c) 里的 skills 数组
+ */
+export function discoverSources({ cwd = process.cwd(), home = os.homedir(), includeGlobal = true } = {}) {
+  const projectRoot = findProjectRoot(cwd) ?? path.resolve(cwd)
+  const projectChain = pathChain(projectRoot, cwd)
+  const sources = []
+  const catalogs = []
+  const missing = []
+  const seen = new Set()
+
+  const addSource = (kind, scope, dir) => {
+    const abs = path.resolve(dir)
+    if (seen.has(abs)) return
+    seen.add(abs)
+    sources.push({ kind, scope, dir: abs, order: sources.length })
+  }
+
+  if (includeGlobal) addSource("claude-global", "global", path.join(home, ".claude", "skills"))
+  for (const dir of projectChain) addSource("claude-project", "project", path.join(dir, ".claude", "skills"))
+
+  if (includeGlobal) addSource("agents-global", "global", path.join(home, ".agents", "skills"))
+  for (const dir of projectChain) addSource("agents-project", "project", path.join(dir, ".agents", "skills"))
+
+  if (includeGlobal) addSource("opencode-global", "global", path.join(home, ".config", "opencode", "skills"))
+  for (const dir of projectChain) addSource("opencode-project", "project", path.join(dir, ".opencode", "skills"))
+
+  const configFiles = []
+  if (includeGlobal) {
+    for (const file of configCandidates(path.join(home, ".config", "opencode"))) {
+      if (fs.existsSync(file)) configFiles.push(file)
+    }
+  }
+  for (const dir of projectChain) {
+    for (const file of configCandidates(dir)) {
+      if (fs.existsSync(file)) configFiles.push(file)
+    }
+  }
+
+  for (const file of configFiles) {
+    let config
+    try {
+      config = readJsoncFile(file)
+    } catch (err) {
+      missing.push({ kind: "config-error", path: file, error: err.message })
+      continue
+    }
+    // 2.x: skills: [...]；1.x: skills: { paths: [...] }
+    const entries = Array.isArray(config?.skills)
+      ? config.skills
+      : Array.isArray(config?.skills?.paths)
+        ? config.skills.paths
+        : []
+    for (const entry of entries) {
+      if (typeof entry !== "string" || !entry.trim()) continue
+      const value = entry.trim()
+      if (/^https?:\/\//i.test(value)) {
+        catalogs.push({ url: value, config: file })
+        continue
+      }
+      const expanded = expandHome(value, home)
+      const abs = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded)
+      if (fs.existsSync(abs)) {
+        addSource("config-path", isUnder(projectRoot, file) ? "project" : "global", abs)
+      } else missing.push({ kind: "missing-path", path: abs, entry: value, config: file })
+    }
+  }
+
+  return { sources, catalogs, missing, configs: configFiles, projectRoot }
+}
+
+function safeReaddir(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+function isSkippable(name) {
+  return name.startsWith(".") || SKIP_DIRS.has(name)
+}
+
+/** 跟随符号链接判断实际类型；坏链接返回 "broken"。 */
+function direntKind(fullPath, entry) {
+  if (entry.isSymbolicLink()) {
+    try {
+      const stat = fs.statSync(fullPath)
+      if (stat.isDirectory()) return "dir"
+      if (stat.isFile()) return "file"
+      return "other"
+    } catch {
+      return "broken"
+    }
+  }
+  if (entry.isDirectory()) return "dir"
+  if (entry.isFile()) return "file"
+  return "other"
+}
+
+function walkForSkillMd(dir, source, out, depth, seen) {
+  if (depth > 8) return
+  let real
+  try {
+    real = fs.realpathSync(dir)
+  } catch {
+    return
+  }
+  if (seen.has(real)) return
+  seen.add(real)
+
+  for (const entry of safeReaddir(dir)) {
+    if (isSkippable(entry.name)) continue
+    const full = path.join(dir, entry.name)
+    const kind = direntKind(full, entry)
+    if (kind === "dir") {
+      walkForSkillMd(full, source, out, depth + 1, seen)
+    } else if (kind === "file" && entry.name === "SKILL.md") {
+      out.push(buildSkill({ id: path.basename(dir), file: full, source, form: "dir" }))
+    }
+  }
+}
+
+function buildSkill({ id, file, source, form }) {
+  let text = ""
+  try {
+    text = fs.readFileSync(file, "utf8")
+  } catch {
+    text = ""
+  }
+  const { data, body } = parseFrontmatter(text)
+  const autoinvoke = data?.metadata?.["opencode/autoinvoke"]
+  const disabled = data?.["disable-model-invocation"]
+  const description = typeof data.description === "string" ? data.description.trim() : ""
+  const displayName = typeof data.name === "string" && data.name.trim() ? data.name.trim() : id
+  const hidden = autoinvoke === false || disabled === true
+  let mtime = 0
+  try {
+    mtime = fs.statSync(file).mtimeMs
+  } catch {}
+
+  return {
+    id,
+    form,
+    file,
+    source,
+    order: source.order,
+    displayName,
+    description,
+    autoinvoke,
+    disabled,
+    hidden,
+    advertised: Boolean(description) && !hidden,
+    body,
+    bodyTokens: estimateTokens(body),
+    bytes: Buffer.byteLength(text),
+    descriptionTokens: estimateTokens(description),
+    hash: sha1(body.replace(/\s+/g, " ").trim()),
+    mtime,
+  }
+}
+
+export function scanSource(source) {
+  if (!fs.existsSync(source.dir)) return { source, skills: [], exists: false }
+  const stat = fs.statSync(source.dir)
+  if (!stat.isDirectory()) return { source, skills: [], exists: false }
+
+  const skills = []
+  for (const entry of safeReaddir(source.dir)) {
+    if (isSkippable(entry.name)) continue
+    const full = path.join(source.dir, entry.name)
+    const kind = direntKind(full, entry)
+    if (kind === "file" && /\.md$/i.test(entry.name)) {
+      const id = entry.name.replace(/\.md$/i, "")
+      skills.push(buildSkill({ id, file: full, source, form: "flat" }))
+    } else if (kind === "dir") {
+      walkForSkillMd(full, source, skills, 1, new Set())
+    }
+  }
+  return { source, skills, exists: true }
+}
+
+export function scanAll(discovered) {
+  const scans = discovered.sources.map(scanSource)
+  return {
+    ...discovered,
+    scans,
+    skills: scans.flatMap((s) => s.skills),
+  }
+}

package/src/fix.mjs

@@ -0,0 +1,166 @@
+import fs from "node:fs"
+import path from "node:path"
+import { resolveWinners } from "./lint.mjs"
+
+export const ARCHIVE_DIR = ".skills-doctor-archive"
+
+function collectSkillMds(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue
+    const full = path.join(dir, entry.name)
+    let kind = entry.isDirectory() ? "dir" : entry.isFile() ? "file" : "other"
+    if (entry.isSymbolicLink()) {
+      try {
+        kind = fs.statSync(full).isDirectory() ? "dir" : "file"
+      } catch {
+        continue
+      }
+    }
+    if (kind === "dir") collectSkillMds(full, out)
+    else if (entry.name === "SKILL.md") out.push(full)
+  }
+  return out
+}
+
+function archiveTarget(skill, stamp) {
+  const sourceDir = skill.source.dir
+  const inner = skill.form === "dir" ? path.dirname(skill.file) : skill.file
+  const rel = path.relative(sourceDir, inner)
+  return path.join(sourceDir, ARCHIVE_DIR, stamp, rel)
+}
+
+/**
+ * 规划安全的结构性修复：只归档「被遮蔽、永远不会加载」的定义。
+ * 由更新器管理的文件不碰（应通过 update 恢复）。
+ */
+export function planFixes(skills, managed = new Map(), { now = new Date(), includeGlobal = false } = {}) {
+  const winners = resolveWinners(skills)
+  const byId = new Map()
+  for (const skill of skills) {
+    if (!byId.has(skill.id)) byId.set(skill.id, [])
+    byId.get(skill.id).push(skill)
+  }
+
+  const stamp = now.toISOString().replace(/[:.]/g, "-")
+  const plan = []
+  const skipped = []
+  const skippedGlobal = []
+
+  for (const [id, defs] of byId) {
+    if (defs.length <= 1) continue
+    const winner = winners.get(id)
+    for (const loser of defs) {
+      if (loser === winner) continue
+      if (!includeGlobal && loser.source.scope === "global") {
+        skippedGlobal.push(loser)
+        continue
+      }
+      if (managed.has(loser.file)) {
+        skipped.push(loser)
+        continue
+      }
+      let from = loser.file
+      if (loser.form === "dir") {
+        const dir = path.dirname(loser.file)
+        // 目录里若还有别的 SKILL.md，只挪这一个文件，避免误伤其他 skill
+        from = collectSkillMds(dir).length > 1 ? loser.file : dir
+      }
+      plan.push({ id, from, file: loser.file, winner: winner.file, target: archiveTarget(loser, stamp) })
+    }
+  }
+
+  return { plan, skipped, skippedGlobal }
+}
+
+export function applyFixes(plan, { dryRun = false } = {}) {
+  const moved = []
+  const errors = []
+
+  for (const fix of plan) {
+    if (dryRun) {
+      moved.push(fix)
+      continue
+    }
+    try {
+      let target = fix.target
+      let n = 1
+      while (fs.existsSync(target)) target = `${fix.target}-${n++}`
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.renameSync(fix.from, target)
+      moved.push({ ...fix, target })
+    } catch (err) {
+      errors.push({ ...fix, error: String(err?.message ?? err) })
+    }
+  }
+
+  return { moved, errors }
+}
+
+/** 在 frontmatter 里把 metadata.opencode/autoinvoke 设为 false。 */
+export function setAutoinvokeFalse(text) {
+  const lines = text.split(/\r?\n/)
+  const snippet = ["metadata:", "  opencode/autoinvoke: false"]
+  if (lines[0]?.trim() !== "---") return ["---", ...snippet, "---", ...lines].join("\n")
+
+  let end = -1
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      end = i
+      break
+    }
+  }
+  if (end === -1) return ["---", ...snippet, "---", ...lines].join("\n")
+
+  const fm = lines.slice(1, end)
+  const metaIdx = fm.findIndex((line) => /^metadata\s*:/.test(line.trim()))
+  if (metaIdx === -1) {
+    return [lines[0], ...fm, ...snippet, ...lines.slice(end)].join("\n")
+  }
+
+  const metaIndent = fm[metaIdx].length - fm[metaIdx].trimStart().length
+  let j = metaIdx + 1
+  while (j < fm.length && (fm[j].trim() === "" || fm[j].length - fm[j].trimStart().length > metaIndent)) j++
+
+  const block = fm.slice(metaIdx + 1, j)
+  let replaced = false
+  for (let k = 0; k < block.length; k++) {
+    if (/^\s*opencode\/autoinvoke\s*:/.test(block[k])) {
+      block[k] = " ".repeat(metaIndent + 2) + "opencode/autoinvoke: false"
+      replaced = true
+    }
+  }
+  if (!replaced) block.unshift(" ".repeat(metaIndent + 2) + "opencode/autoinvoke: false")
+
+  return [lines[0], ...fm.slice(0, metaIdx + 1), ...block, ...fm.slice(j), ...lines.slice(end)].join("\n")
+}
+
+/**
+ * 隐藏指定 ID 的 skill（给生效版本加 autoinvoke: false）。
+ * 用于给上下文预算减压：skill 仍可用 @id 手动加载。
+ */
+export function hideSkills(skills, ids, { dryRun = false } = {}) {
+  const winners = resolveWinners(skills)
+  const wanted = [...new Set(ids)]
+  const changed = []
+  const errors = []
+  const missing = []
+
+  for (const id of wanted) {
+    const skill = winners.get(id)
+    if (!skill) {
+      missing.push(id)
+      continue
+    }
+    try {
+      if (!dryRun) {
+        const text = fs.readFileSync(skill.file, "utf8")
+        fs.writeFileSync(skill.file, setAutoinvokeFalse(text), "utf8")
+      }
+      changed.push({ id, file: skill.file })
+    } catch (err) {
+      errors.push({ id, file: skill.file, error: String(err?.message ?? err) })
+    }
+  }
+
+  return { changed, errors, missing }
+}