@andyqiu/codeforge 0.5.28 → 0.6.0

package/install.mjs

@@ -0,0 +1,751 @@
+#!/usr/bin/env node
+// ADR:unify-install-to-node-mjs
+// ============================================================================
+// CodeForge install.mjs — 零侵入安装到 opencode（Node ESM 零依赖，跨平台）
+//
+// 合并自原 install.sh（bash）+ install.ps1（PowerShell），一份逻辑跨平台。
+//
+// 输出三档：
+//   - quiet（默认）：成功只打摘要块（≤5 行）：版本+路径行、warn 行（命中时）、生效提示行
+//   - verbose（--verbose）：打印每 Step / 每文件 / bytes / 自检每项 / 验证清单
+//   - error（永远）：任何非零退出始终打完整错误上下文，不受 verbose 影响
+//
+// 用法：
+//   node install.mjs                # 项目级（默认）
+//   node install.mjs --global       # 全局
+//   node install.mjs --uninstall    # 卸载
+//   node install.mjs --dry-run      # 仅打印操作，不执行
+//   node install.mjs --skip-build   # 跳过 npm run build
+//   node install.mjs --verbose      # 展开全部过程输出
+// ============================================================================
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+import * as os from "node:os"
+import { spawnSync } from "node:child_process"
+import { pathToFileURL, fileURLToPath } from "node:url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const SOURCE_ROOT = __dirname
+const IS_WIN = process.platform === "win32"
+
+// ────────────────────────────────────────────────────────────────────
+// A. 输出基础设施
+// ────────────────────────────────────────────────────────────────────
+const isTTY = process.stdout.isTTY
+const C = isTTY
+  ? { reset: "\x1b[0m", bold: "\x1b[1m", red: "\x1b[31m", green: "\x1b[32m", yellow: "\x1b[33m", blue: "\x1b[34m", cyan: "\x1b[36m" }
+  : { reset: "", bold: "", red: "", green: "", yellow: "", blue: "", cyan: "" }
+
+let VERBOSE = false
+const summaryWarns = []
+
+// verbose：即时打印（带 [codeforge] 前缀）；quiet：静默
+function vlog(...parts) {
+  if (VERBOSE) console.log(`${C.cyan}[codeforge]${C.reset} ${parts.join(" ")}`)
+}
+// verbose 即时 ok 行
+function vok(...parts) {
+  if (VERBOSE) console.log(`${C.green}✓${C.reset} ${parts.join(" ")}`)
+}
+// 永远打 stderr，不受 verbose 影响
+function err(...parts) {
+  console.error(`${C.red}✗${C.reset} ${parts.join(" ")}`)
+}
+// warn：verbose 时即时打；否则延迟到 printSummary
+function addWarn(msg) {
+  if (VERBOSE) {
+    console.log(`${C.yellow}⚠${C.reset}  ${msg}`)
+  } else {
+    summaryWarns.push(msg)
+  }
+}
+
+function shortenHome(p) {
+  const home = os.homedir()
+  if (home && p.startsWith(home)) return "~" + p.slice(home.length)
+  return p
+}
+
+// 打摘要块：版本+路径+✓ 行 → 遍历 warns → 末行生效提示
+function printSummary({ version, targetRoot, dryRun }) {
+  if (VERBOSE) {
+    // verbose 模式 warn 已即时打过，这里只打最终一行收尾
+    for (const w of summaryWarns) console.log(`${C.yellow}⚠${C.reset}  ${w}`)
+  }
+  const check = `${C.green}✓${C.reset}`
+  console.log(`CodeForge v${version} → ${shortenHome(targetRoot)}  ${check}`)
+  if (dryRun) console.log(`${C.blue}[dry-run]${C.reset} 不会写任何文件`)
+  if (!VERBOSE) {
+    for (const w of summaryWarns) console.log(`${C.yellow}⚠${C.reset}  ${w}`)
+  }
+  console.log(`重启 opencode 后生效`)
+}
+
+// dry-run 守卫：dry-run 时 vlog 描述不执行
+function run(desc, fn) {
+  if (DRY_RUN) {
+    vlog(`[dry-run] ${desc}`)
+    return
+  }
+  fn()
+}
+
+// ────────────────────────────────────────────────────────────────────
+// 参数解析
+// ────────────────────────────────────────────────────────────────────
+let DRY_RUN = false
+
+function parseArgs(argv) {
+  const out = {
+    mode: "project",
+    action: "install",
+    dryRun: false,
+    skipBuild: false,
+    enableLegacyTools: false,
+    verbose: false,
+    help: false,
+    global: false,
+    uninstall: false,
+  }
+  for (const a of argv) {
+    switch (a) {
+      case "--global": out.mode = "global"; break
+      case "--project": out.mode = "project"; break
+      case "--uninstall": out.action = "uninstall"; break
+      case "--dry-run": out.dryRun = true; break
+      case "--skip-build": out.skipBuild = true; break
+      case "--enable-legacy-tools": out.enableLegacyTools = true; break
+      case "--verbose": out.verbose = true; break
+      case "-h":
+      case "--help": out.help = true; break
+      default:
+        // 容忍 PS 风格 flag（来自旧 bin 调用），静默忽略未知，避免炸
+        if (a.startsWith("-")) {
+          // 兼容 -Global/-DryRun/-Uninstall/-SkipBuild/-EnableLegacyTools
+          const low = a.toLowerCase()
+          if (low === "-global") out.mode = "global"
+          else if (low === "-uninstall") out.action = "uninstall"
+          else if (low === "-dryrun") out.dryRun = true
+          else if (low === "-skipbuild") out.skipBuild = true
+          else if (low === "-enablelegacytools") out.enableLegacyTools = true
+          else if (low === "-verbose") out.verbose = true
+        }
+        break
+    }
+  }
+  // 扁平 boolean 别名（供测试 / 外部消费；main 内部仍用 mode/action）
+  out.global = out.mode === "global"
+  out.uninstall = out.action === "uninstall"
+  return out
+}
+
+// .md 文件是否应被 copy（排除 README/_*/.bak/隐藏文件）
+function shouldCopyMd(base) {
+  if (!base.endsWith(".md")) return false
+  if (base === "README.md") return false
+  if (base.startsWith("_")) return false
+  if (base.endsWith(".bak")) return false
+  if (base.startsWith(".")) return false
+  return true
+}
+
+// ────────────────────────────────────────────────────────────────────
+// B. 路径 / 常量（照搬两脚本并集）
+// ────────────────────────────────────────────────────────────────────
+function xdgConfigHome() {
+  return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
+}
+
+function resolvePaths({ mode }) {
+  const targetRoot = mode === "global"
+    ? path.join(xdgConfigHome(), "opencode")
+    : path.join(process.cwd(), ".opencode")
+  const codeforgeCfgDir = path.join(xdgConfigHome(), "codeforge")
+  return { targetRoot, codeforgeCfgDir }
+}
+
+// v0.1 之前装的目录（卸载时一并清掉）
+const LEGACY_DIRS = ["agent", "command", "tool", "tools", "plugin", "plugins", "lib"]
+// v0.1+ 才有的目录
+const MANAGED_DIRS = ["codeforge", "agents", "commands", "workflows", "context-templates", "review-profiles", "agent-templates"]
+// 细粒度卸载：只删 CodeForge 自己的 skill
+const OWNED_SKILLS = ["ambiguity-gate", "devils-advocate", "ears-zh", "example-mapping", "success-criteria", "weighted-dimensions"]
+
+// 文件级 copy（.md，排除 README/_*/.bak/隐藏）
+const MD_COPY_DIRS = [["agents", "agents"], ["commands", "commands"]]
+// 整目录拷贝
+const COPY_DIRS = [
+  ["workflows", "workflows"],
+  ["context-templates", "context-templates"],
+  ["review-profiles", "review-profiles"],
+  ["agent-templates", "agent-templates"],
+]
+
+const BUNDLE_SRC_REL = "dist/index.js"
+const BUNDLE_DST_REL = "codeforge/index.js"
+
+// ────────────────────────────────────────────────────────────────────
+// 通用文件工具
+// ────────────────────────────────────────────────────────────────────
+function ensureDir(p) {
+  run(`mkdir -p ${p}`, () => fs.mkdirSync(p, { recursive: true }))
+}
+
+function rmrf(p) {
+  run(`rm -rf ${p}`, () => fs.rmSync(p, { recursive: true, force: true }))
+}
+
+function commandExists(cmd) {
+  try {
+    const r = spawnSync(cmd, ["--version"], { stdio: "pipe", shell: IS_WIN })
+    return r.status === 0 || (r.error == null && r.status != null)
+  } catch {
+    return false
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// C. WSL guard（决策 2：warn + continue，不阻断）
+// ────────────────────────────────────────────────────────────────────
+//
+// 仅 Linux 生效。触发条件：存在 wslpath 命令，或 CODEFORGE_FORCE_WSL_CHECK=1。
+// $HOME 落在 /mnt/[cde]/ 时不再 exit，改 addWarn + continue（quiet 也进摘要）。
+// --uninstall 整段跳过（连 warn 都不打）。
+// CODEFORGE_ALLOW_WSL_WINDOWS_HOME 退化为纯 no-op：不打印任何消息、不抑制 warn。
+function checkWslGuard({ action }) {
+  if (process.platform !== "linux") return
+  if (action === "uninstall") return
+  if (process.env.CODEFORGE_ALLOW_WSL_WINDOWS_HOME === "1") {
+    // 退化为兼容 no-op：整段跳过（既不打 bypass 消息，也不再走 warn 逻辑）
+    return
+  }
+  const forced = process.env.CODEFORGE_FORCE_WSL_CHECK === "1"
+  if (!forced && !commandExists("wslpath")) return
+  const home = process.env.HOME || os.homedir()
+  if (/^\/mnt\/[cde]\//.test(home)) {
+    addWarn(`在 WSL 中 $HOME=${home} 落在 Windows 挂载路径，建议改用 WSL 原生 home（/home/<user>/）`)
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// D. opencode.json 读写（纯 Node JSON + 原子写）
+// ────────────────────────────────────────────────────────────────────
+function pluginUri(targetRoot) {
+  const abs = path.join(targetRoot, BUNDLE_DST_REL)
+  const norm = abs.replace(/\\/g, "/")
+  // Windows 盘符 → 三斜杠：file:///C:/Users/...
+  if (/^[A-Za-z]:\//.test(norm)) return `file:///${norm}`
+  return `file://${norm}`
+}
+
+function opencodeCfgPath(targetRoot) {
+  return path.join(targetRoot, "opencode.json")
+}
+
+// 原子写 JSON：tmp 与目标同目录 → 同分区 → rename 原子（跨平台安全）
+// 禁止使用 os.tmpdir()：Windows 上多在 C: 盘，若目标在 D: 盘则 rename 跨驱动器抛 EXDEV。
+function atomicWriteJson(p, data) {
+  const tmp = path.join(path.dirname(p), ".tmp-codeforge-" + process.pid)
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf8")
+  fs.renameSync(tmp, p) // 同目录，不跨驱动器
+}
+
+function writePluginEntry({ targetRoot }) {
+  const cfg = opencodeCfgPath(targetRoot)
+  const uri = pluginUri(targetRoot)
+  if (DRY_RUN) {
+    vlog(`[dry-run] write ${cfg} plugin entry: ${uri}`)
+    return
+  }
+  ensureDir(targetRoot)
+  let data = {}
+  if (fs.existsSync(cfg)) {
+    try {
+      data = JSON.parse(fs.readFileSync(cfg, "utf8"))
+    } catch {
+      fs.copyFileSync(cfg, cfg + ".bak." + Date.now())
+      data = {}
+    }
+  }
+  if (!data.$schema) data.$schema = "https://opencode.ai/config.json"
+  if (!Array.isArray(data.plugin)) data.plugin = []
+  const cleaned = []
+  for (const e of data.plugin) {
+    const s = String(e)
+    if (/\/codeforge\/index\.js$/.test(s)) continue
+    if (/\/plugins\/[^/]+\.ts$/.test(s) && /opencode/.test(s)) continue
+    if (/\/\.opencode\/plugins\//.test(s)) continue
+    cleaned.push(e)
+  }
+  cleaned.push(uri)
+  data.plugin = cleaned
+  atomicWriteJson(cfg, data)
+  vok(`opencode.json 已写入 plugin entry: ${uri}`)
+}
+
+function removePluginEntry({ targetRoot }) {
+  const cfg = opencodeCfgPath(targetRoot)
+  if (!fs.existsSync(cfg)) return
+  if (DRY_RUN) {
+    vlog(`[dry-run] rewrite ${cfg} without codeforge plugin entry`)
+    return
+  }
+  let data
+  try {
+    data = JSON.parse(fs.readFileSync(cfg, "utf8"))
+  } catch {
+    return
+  }
+  if (!Array.isArray(data.plugin)) return
+  data.plugin = data.plugin.filter((e) => {
+    const s = String(e)
+    if (/\/codeforge\/index\.js$/.test(s)) return false
+    if (/\/plugins\/[^/]+\.ts$/.test(s)) return false
+    if (/\/\.opencode\/plugins\//.test(s)) return false
+    return true
+  })
+  atomicWriteJson(cfg, data)
+  vok(`opencode.json 已移除 codeforge plugin entry`)
+}
+
+// 配置默认 agent → codeforge（仅 global）。三态幂等：SET/UNCHANGED vlog；SKIPPED→addWarn。
+function configureDefaultAgent({ mode }) {
+  if (mode !== "global") {
+    vok(`项目级安装，跳过用户级 default_agent 配置（要装请加 --global）`)
+    return
+  }
+  const opencodeJson = path.join(xdgConfigHome(), "opencode", "opencode.json")
+  const target = "codeforge"
+  if (!fs.existsSync(opencodeJson)) {
+    addWarn(`opencode.json 不存在，跳过 default_agent 配置（首次安装 opencode 后请重跑 install）`)
+    return
+  }
+  if (DRY_RUN) {
+    vlog(`[dry-run] configure default_agent=${target} in ${opencodeJson}`)
+    return
+  }
+  let cfg
+  try {
+    cfg = JSON.parse(fs.readFileSync(opencodeJson, "utf8"))
+  } catch (e) {
+    addWarn(`default_agent 配置失败（opencode.json 解析错误，不阻塞 install）`)
+    return
+  }
+  const current = cfg.default_agent
+  if (current === undefined) {
+    cfg.default_agent = target
+    atomicWriteJson(opencodeJson, cfg)
+    vok(`default_agent: SET default_agent=${target}`)
+  } else if (current === target) {
+    vok(`default_agent: UNCHANGED (already ${target})`)
+  } else {
+    addWarn(`default_agent 已被用户设为 "${current}"，跳过不动（不覆盖用户配置）`)
+  }
+}
+
+// 卸载时还原 default_agent（仅当当前值是 codeforge）
+function restoreDefaultAgent({ mode }) {
+  if (mode === "project") return
+  const opencodeJson = path.join(xdgConfigHome(), "opencode", "opencode.json")
+  if (!fs.existsSync(opencodeJson)) return
+  if (DRY_RUN) {
+    vlog(`[dry-run] restore default_agent in ${opencodeJson} (remove if codeforge)`)
+    return
+  }
+  let cfg
+  try {
+    cfg = JSON.parse(fs.readFileSync(opencodeJson, "utf8"))
+  } catch {
+    return
+  }
+  if (cfg.default_agent === "codeforge") {
+    delete cfg.default_agent
+    atomicWriteJson(opencodeJson, cfg)
+    vok(`default_agent: REMOVED (was codeforge)`)
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// E. 文件分发（全 vlog，不进 summary）
+// ────────────────────────────────────────────────────────────────────
+function detectOpencode() {
+  const r = spawnSync("opencode", ["--version"], { stdio: "pipe", encoding: "utf8", shell: IS_WIN })
+  if (r.status === 0) {
+    vok(`检测到 opencode: ${(r.stdout ?? "").trim()}`)
+  } else {
+    addWarn(`opencode 未检测到，请先安装：https://opencode.ai`)
+  }
+}
+
+function buildBundle({ skipBuild }) {
+  const bundleSrc = path.join(SOURCE_ROOT, BUNDLE_SRC_REL)
+  if (skipBuild) {
+    vlog(`已跳过 build（--skip-build），使用现有 dist/index.js`)
+  } else if (DRY_RUN) {
+    vlog(`[dry-run] npm run build`)
+  } else {
+    const r = spawnSync("npm", ["run", "build"], { cwd: SOURCE_ROOT, stdio: VERBOSE ? "inherit" : "pipe", shell: IS_WIN })
+    if (r.status !== 0) {
+      if (!VERBOSE) {
+        if (r.stdout) process.stderr.write(r.stdout)
+        if (r.stderr) process.stderr.write(r.stderr)
+      }
+      err(`npm run build 失败 (exit=${r.status ?? 1})`)
+      process.exit(1)
+    }
+  }
+  if (!DRY_RUN && !fs.existsSync(bundleSrc)) {
+    if (skipBuild) {
+      err(`找不到 ${bundleSrc}（npm 包可能损坏）`)
+      err(`  请尝试重装：npx @andyqiu/codeforge install [--global]`)
+    } else {
+      err(`找不到 ${bundleSrc}，请先成功执行 npm run build`)
+    }
+    process.exit(1)
+  }
+  if (fs.existsSync(bundleSrc)) {
+    const size = fs.statSync(bundleSrc).size
+    vok(`bundle 已就绪: ${bundleSrc} (${size} bytes)`)
+  }
+  return bundleSrc
+}
+
+function cleanLegacy({ targetRoot }) {
+  ensureDir(targetRoot)
+  for (const legacy of LEGACY_DIRS) {
+    const p = path.join(targetRoot, legacy)
+    if (fs.existsSync(p) || isSymlink(p)) {
+      rmrf(p)
+      vlog(`已清理 legacy 目录: ${p}`)
+    }
+  }
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+function installBundle({ targetRoot, bundleSrc }) {
+  const bundleDst = path.join(targetRoot, BUNDLE_DST_REL)
+  ensureDir(path.dirname(bundleDst))
+  run(`cp ${bundleSrc} ${bundleDst}`, () => fs.copyFileSync(bundleSrc, bundleDst))
+  vok(`bundle → ${bundleDst}`)
+  writePluginEntry({ targetRoot })
+  // 写 VERSION marker
+  let version = "unknown"
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(SOURCE_ROOT, "package.json"), "utf8")).version ?? "unknown"
+  } catch {}
+  const versionFile = path.join(targetRoot, "codeforge", "VERSION")
+  run(`write VERSION ${version}`, () => fs.writeFileSync(versionFile, version + "\n", "utf8"))
+  vok(`VERSION → ${versionFile} (${version})`)
+}
+
+function installMdDirs({ targetRoot }) {
+  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()) {
+      addWarn(`源目录不存在，跳过: ${srcPath}`)
+      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) {
+      if (!shouldCopyMd(base)) continue
+      const f = path.join(srcPath, base)
+      try {
+        if (!fs.statSync(f).isFile()) continue
+      } catch {
+        continue
+      }
+      run(`cp ${f} ${dstPath}/`, () => fs.copyFileSync(f, path.join(dstPath, base)))
+      count++
+    }
+    vok(`${srcName}/ → ${dstPath}  (${count} 个 .md)`)
+  }
+}
+
+function safeReaddir(p) {
+  try {
+    return fs.readdirSync(p)
+  } catch {
+    return []
+  }
+}
+
+function installCopyDirs({ targetRoot }) {
+  for (const [srcName, dstName] of COPY_DIRS) {
+    const srcPath = path.join(SOURCE_ROOT, srcName)
+    const dstPath = path.join(targetRoot, dstName)
+    if (!fs.existsSync(srcPath) || !fs.statSync(srcPath).isDirectory()) {
+      addWarn(`源目录不存在，跳过: ${srcPath}`)
+      continue
+    }
+    ensureDir(dstPath)
+    run(`cp -R ${srcPath}/. ${dstPath}/`, () => fs.cpSync(srcPath, dstPath, { recursive: true }))
+    vok(`${srcName}/ → ${dstPath} (整目录拷贝)`)
+  }
+}
+
+function installSkills({ targetRoot }) {
+  const skillsSrc = path.join(SOURCE_ROOT, "skills")
+  const skillsDst = path.join(targetRoot, "skills")
+  if (!fs.existsSync(skillsSrc) || !fs.statSync(skillsSrc).isDirectory()) {
+    addWarn(`skills/ 目录不存在，跳过（发布包未含 skills）`)
+    return
+  }
+  ensureDir(skillsDst)
+  let count = 0
+  const entries = DRY_RUN ? safeReaddir(skillsSrc) : fs.readdirSync(skillsSrc)
+  for (const name of entries) {
+    const skillDir = path.join(skillsSrc, name)
+    try {
+      if (!fs.statSync(skillDir).isDirectory()) continue
+    } catch {
+      continue
+    }
+    const dstSkill = path.join(skillsDst, name)
+    if (fs.existsSync(dstSkill) || isSymlink(dstSkill)) rmrf(dstSkill)
+    run(`cp -R ${skillDir} ${dstSkill}`, () => fs.cpSync(skillDir, dstSkill, { recursive: true }))
+    count++
+  }
+  vok(`skills/ → ${skillsDst}  (${count} 个 skill)`)
+}
+
+function installAssets({ targetRoot }) {
+  const assetsSrc = path.join(SOURCE_ROOT, "assets")
+  const assetsDst = path.join(targetRoot, "assets")
+  if (!fs.existsSync(assetsSrc) || !fs.statSync(assetsSrc).isDirectory()) {
+    addWarn(`assets/ 目录不存在，跳过（发布包未含 assets）`)
+    return
+  }
+  ensureDir(assetsDst)
+  run(`cp -R ${assetsSrc}/. ${assetsDst}/`, () => fs.cpSync(assetsSrc, assetsDst, { recursive: true }))
+  vok(`assets/ → ${assetsDst}`)
+}
+
+// 本仓库 dev 期：install 会清掉 .opencode/plugins/，需重生成 dev shim（ADR-0055）
+function regenerateDevShim() {
+  const marker = path.join(SOURCE_ROOT, ".codeforge", ".dev-marker")
+  const devSync = path.join(SOURCE_ROOT, "scripts", "dev-sync.mjs")
+  if (!fs.existsSync(marker) || !fs.existsSync(devSync)) return
+  if (DRY_RUN) {
+    vlog(`[dry-run] node scripts/dev-sync.mjs --no-build`)
+    return
+  }
+  spawnSync(process.execPath, [devSync, "--no-build"], { cwd: SOURCE_ROOT, stdio: "pipe" })
+  vlog(`dev shim regenerated (.opencode/plugins/codeforge-dev.js)`)
+}
+
+// 仅 global：写 ~/.config/codeforge/kh.json（已存在则跳过）
+function installKhConfig({ mode, codeforgeCfgDir }) {
+  if (mode !== "global") return
+  const khJson = path.join(codeforgeCfgDir, "kh.json")
+  if (fs.existsSync(khJson)) {
+    vlog(`kh.json 已存在，跳过: ${khJson}`)
+    return
+  }
+  if (DRY_RUN) {
+    vlog(`[dry-run] write ${khJson}`)
+    return
+  }
+  ensureDir(codeforgeCfgDir)
+  atomicWriteJson(khJson, {})
+  vok(`kh.json → ${khJson}`)
+}
+
+// ────────────────────────────────────────────────────────────────────
+// F. 自检（verifyInstall：通过静默，失败按定级表 addWarn——全部 warn，不改 exit）
+// ────────────────────────────────────────────────────────────────────
+function verifyInstall({ mode, targetRoot }) {
+  // 1. git 版本 >= 2.5
+  if (commandExists("git")) {
+    const r = spawnSync("git", ["--version"], { stdio: "pipe", encoding: "utf8", shell: IS_WIN })
+    const m = /(\d+)\.(\d+)/.exec(r.stdout ?? "")
+    const major = m ? parseInt(m[1], 10) : 0
+    const minor = m ? parseInt(m[2], 10) : 0
+    if (major > 2 || (major === 2 && minor >= 5)) {
+      vok(`git ${m ? m[0] : "?"}  (>= 2.5 ✓ worktree 支持)`)
+    } else {
+      addWarn(`git 版本太旧（worktree 需要 >= 2.5）；worktree 隔离将失效`)
+    }
+  } else {
+    addWarn(`git 未安装；worktree 隔离将失效（写操作会被 DENY）`)
+  }
+
+  // 1b. git rev-parse --git-dir
+  if (commandExists("git")) {
+    const r = spawnSync("git", ["rev-parse", "--git-dir"], { stdio: "pipe", shell: IS_WIN })
+    if (r.status === 0) {
+      vok(`当前目录是 git 仓库（git rev-parse --git-dir ✓）`)
+    } else if (mode === "project") {
+      addWarn(`当前目录不是 git 仓库；worktree 隔离将失效（git init && git add -A && git commit）`)
+    } else {
+      vlog(`当前目录非 git 仓库（全局安装无碍）`)
+    }
+  }
+
+  // 2. opencode 已安装
+  if (commandExists("opencode")) {
+    const r = spawnSync("opencode", ["--version"], { stdio: "pipe", encoding: "utf8", shell: IS_WIN })
+    vok(`opencode ${(r.stdout ?? "").trim() || "unknown"}`)
+  } else {
+    addWarn(`opencode 未在 PATH 中；CodeForge 无入口可用（请先安装 opencode）`)
+  }
+
+  // 3. plugin 注册检查
+  const cfg = opencodeCfgPath(targetRoot)
+  let registered = false
+  if (fs.existsSync(cfg)) {
+    try {
+      registered = /"codeforge"/.test(fs.readFileSync(cfg, "utf8"))
+    } catch {}
+  }
+  if (registered) {
+    vok(`plugin 已注册：${cfg}`)
+  } else if (mode === "global") {
+    addWarn(`plugin 未在 ${cfg} 中注册`)
+  } else {
+    vlog(`项目级配置 ${cfg} 未包含 codeforge entry（项目级可被全局兜底）`)
+  }
+
+  // 4. dev-marker 误用检测（仅 global）
+  if (mode === "global") {
+    const m1 = path.join(os.homedir(), ".codeforge", ".dev-marker")
+    const m2 = path.join(os.homedir(), ".dev-marker")
+    if (fs.existsSync(m1) || fs.existsSync(m2)) {
+      addWarn(`检测到 $HOME 附近有 .dev-marker —— 可能导致所有项目让位到本地 plugin（建议删除）`)
+    }
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// G. 卸载
+// ────────────────────────────────────────────────────────────────────
+function uninstall({ mode, targetRoot }) {
+  vlog(`卸载 CodeForge from: ${targetRoot}`)
+  removePluginEntry({ targetRoot })
+  if (mode !== "project") restoreDefaultAgent({ mode })
+  for (const name of [...LEGACY_DIRS, ...MANAGED_DIRS]) {
+    const p = path.join(targetRoot, name)
+    if (fs.existsSync(p) || isSymlink(p)) {
+      rmrf(p)
+      vok(`已删除 ${p}`)
+    }
+  }
+  for (const skillName of OWNED_SKILLS) {
+    const p = path.join(targetRoot, "skills", skillName)
+    if (fs.existsSync(p) || isSymlink(p)) {
+      rmrf(p)
+      vok(`已删除 skill: ${p}`)
+    }
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// main
+// ────────────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log(`CodeForge install.mjs — 零侵入安装到 opencode（Node ESM 零依赖）
+
+用法：
+  node install.mjs                # 项目级（默认）
+  node install.mjs --global       # 全局
+  node install.mjs --uninstall    # 卸载
+  node install.mjs --dry-run      # 仅打印操作，不执行
+  node install.mjs --skip-build   # 跳过 npm run build
+  node install.mjs --verbose      # 展开全部过程输出`)
+}
+
+function getVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(SOURCE_ROOT, "package.json"), "utf8")).version ?? "unknown"
+  } catch {
+    return "unknown"
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  VERBOSE = opts.verbose
+  DRY_RUN = opts.dryRun
+
+  if (opts.help) {
+    printHelp()
+    return 0
+  }
+
+  const { targetRoot, codeforgeCfgDir } = resolvePaths({ mode: opts.mode })
+  const version = getVersion()
+
+  // WSL guard（非 uninstall 时跑）
+  checkWslGuard({ action: opts.action })
+
+  if (VERBOSE) {
+    vlog(`CodeForge installer (mode=${opts.mode}, action=${opts.action}, dry-run=${DRY_RUN})`)
+    vlog(`Source : ${SOURCE_ROOT}`)
+    vlog(`Target : ${targetRoot}`)
+  }
+
+  if (opts.action === "uninstall") {
+    uninstall({ mode: opts.mode, targetRoot })
+    if (VERBOSE) {
+      for (const w of summaryWarns) console.log(`${C.yellow}⚠${C.reset}  ${w}`)
+    } else {
+      for (const w of summaryWarns) console.log(`${C.yellow}⚠${C.reset}  ${w}`)
+    }
+    console.log(`CodeForge 已卸载 ${C.green}✓${C.reset}`)
+    console.log(`opencode 自身和你的 AGENTS.md 不会被动`)
+    return 0
+  }
+
+  // 安装流程
+  detectOpencode()
+  const bundleSrc = buildBundle({ skipBuild: opts.skipBuild })
+  cleanLegacy({ targetRoot })
+  installBundle({ targetRoot, bundleSrc })
+  installMdDirs({ targetRoot })
+  installCopyDirs({ targetRoot })
+  installSkills({ targetRoot })
+  installAssets({ targetRoot })
+  configureDefaultAgent({ mode: opts.mode })
+  installKhConfig({ mode: opts.mode, codeforgeCfgDir })
+  regenerateDevShim()
+  verifyInstall({ mode: opts.mode, targetRoot })
+
+  printSummary({ version, targetRoot, dryRun: DRY_RUN })
+  return 0
+}
+
+// 纯函数 export 供 vitest 直调
+export {
+  parseArgs,
+  pluginUri,
+  shouldCopyMd,
+  atomicWriteJson,
+  resolvePaths,
+  checkWslGuard,
+  LEGACY_DIRS,
+  MANAGED_DIRS,
+  OWNED_SKILLS,
+}
+
+// main 守卫：仅作为脚本直接运行时执行
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const code = main()
+    process.exit(typeof code === "number" ? code : 0)
+  } catch (e) {
+    err(`安装失败：${e?.stack ?? e}`)
+    process.exit(1)
+  }
+}