@andyqiu/codeforge 0.3.11 → 0.3.13

package/bin/codeforge.mjs

@@ -14,6 +14,8 @@
  *   rollback   [--target=<path>] [--dry-run]
  *                                     恢复到上一次 backup（auto_install 失败时手动救场）
  *   runtime where [<path>]            打印当前项目对应的全局运行时目录
+ *   adr-init   [--force] [--dry-run] [--write-prepare] [--no-pre-push]
+ *                                     把 ADR 体系（hooks + scripts + 模板）下发到当前 git 项目
  *   help [<cmd>]                      打印帮助
  *
  * 默认 --project（项目级，最安全）。
@@ -299,6 +301,79 @@ function cmdRuntime(args) {
   return r.status ?? 1
 }
 
+// ────────────────────────────────────────────────────────────────────
+// 子命令：adr-init —— 把 ADR 体系下发到当前 git 项目 (ADR:adr-distribution-init)
+// ────────────────────────────────────────────────────────────────────
+//
+// 实现走 dist/adr-init.js 这个**确定路径**（由 scripts/build-with-version.mjs 第二
+// bun build entry 产出）。既适用 npm 包安装（pkgRoot/dist/adr-init.js），也适用本
+// 仓库 dev 期（repoRoot/dist/adr-init.js）。没有 fallback —— 缺 dist 文件就明确报错
+// 提示跑 npm run build，比 ts-node / 源码动态 import 简单可靠。
+async function cmdAdrInit(args) {
+  const cwd = process.cwd()
+  const opts = {
+    cwd,
+    force: !!args.flags.force,
+    dryRun: !!args.flags["dry-run"] || !!args.flags.dryRun,
+    writePrepare: !!args.flags["write-prepare"] || !!args.flags.writePrepare,
+    installPrePush: args.flags["no-pre-push"] ? false : true,
+  }
+
+  const adrInitPath = path.join(REPO_ROOT, "dist", "adr-init.js")
+  if (!existsSync(adrInitPath)) {
+    err(`找不到 ${adrInitPath}`)
+    err(`如果是从源码运行：请先跑 npm run build`)
+    err(`如果是 npm 安装：可能是发布缺文件，请重装或反馈给 @andyqiu/codeforge`)
+    return 1
+  }
+
+  log(`CodeForge adr-init —— 下发 ADR 体系到 ${cwd}`)
+  log(`  force          : ${opts.force}`)
+  log(`  dry-run        : ${opts.dryRun}`)
+  log(`  write-prepare  : ${opts.writePrepare}`)
+  log(`  install pre-push: ${opts.installPrePush}`)
+  hr()
+
+  // ESM dynamic import 必须用 file:// URL，Win 路径才能正确解析
+  let mod
+  try {
+    mod = await import(url.pathToFileURL(adrInitPath).href)
+  } catch (e) {
+    err(`加载 ${adrInitPath} 失败：${e?.message ?? e}`)
+    return 1
+  }
+  if (typeof mod.runAdrInit !== "function") {
+    err(`${adrInitPath} 缺少 runAdrInit 导出（bundle 可能损坏，请重建 dist/）`)
+    return 1
+  }
+
+  let result
+  try {
+    result = await mod.runAdrInit(opts)
+  } catch (e) {
+    err(`adr-init 执行抛错：${e?.stack ?? e}`)
+    return 1
+  }
+
+  if (result.wrote?.length) {
+    ok(`已写入 ${result.wrote.length} 个文件：`)
+    for (const f of result.wrote) console.log(`  + ${f}`)
+  }
+  if (result.skipped?.length) {
+    warn(`已跳过 ${result.skipped.length} 个已存在文件（用 --force 覆盖）：`)
+    for (const f of result.skipped) console.log(`  · ${f}`)
+  }
+  if (result.backedUp?.length) {
+    ok(`已备份 ${result.backedUp.length} 个原文件：`)
+    for (const f of result.backedUp) console.log(`  ↳ ${f}`)
+  }
+  for (const s of result.suggestions ?? []) log(s)
+  for (const w of result.warnings ?? []) warn(w)
+  if (opts.dryRun) log("dry-run 模式：以上未实际写盘")
+  hr()
+  return result.ok === false ? 1 : 0
+}
+
 // ────────────────────────────────────────────────────────────────────
 
 // 子命令：help
@@ -313,6 +388,8 @@ function cmdHelp() {
   codeforge version
   codeforge rollback   [--target=<path>] [--dry-run]   # 恢复最近 backup（auto_install 失败救场）
   codeforge runtime where [<path>]   # 打印当前项目的全局运行时目录
+  codeforge adr-init   [--force] [--dry-run] [--write-prepare] [--no-pre-push]
+                                     # 把 ADR 校验体系（hooks + scripts + 模板）下发到当前 git 项目
 
 一行命令（远程安装）：
   npx @andyqiu/codeforge install
@@ -326,6 +403,12 @@ function cmdHelp() {
   --enable-legacy-tools  启用旧版 file-based tools（默认禁用，避免 zod 跨实例 bug）
   --target               rollback 子命令：指定 index.js 路径（默认自动探测）
 
+参数（adr-init 专用）：
+  --force                覆盖已存在文件（覆盖前自动 .bak.<ts> 备份）
+  --dry-run              只打印将要执行的写入计划，不实际写盘
+  --write-prepare        合并 git config core.hooksPath 到 package.json scripts.prepare（写前 backup package.json；默认只建议不写）
+  --no-pre-push          跳过 .githooks/pre-push 生成（只装 pre-commit）
+
 CodeForge 是 opencode 1.14+ 的单 bundle plugin（持续跟主线，src/index.ts → dist/index.js），
 通过往 opencode.json 写一行 plugin entry 来装载。
 不支持 Cursor / Claude Code / Codex —— 它们的扩展机制不同，强行映射只会变成
@@ -336,9 +419,12 @@ CodeForge 是 opencode 1.14+ 的单 bundle plugin（持续跟主线，src/index.
 }
 
 // ────────────────────────────────────────────────────────────────────
-// main
+// main —— async (ADR:adr-distribution-init: adr-init 需 dynamic import)
 // ────────────────────────────────────────────────────────────────────
-function main() {
+//
+// 改成 async 后所有同步 case `return <number>` 自动被包成 Promise<number>，外层 .then
+// 拿到数字调 process.exit 即可；现有 case 的 exit code 行为不变。
+async function main() {
   const argv = process.argv.slice(2)
   if (argv.length === 0 || ["-h", "--help"].includes(argv[0])) {
     return cmdHelp()
@@ -366,6 +452,8 @@ function main() {
       return cmdRollback(args)
     case "runtime":
       return cmdRuntime(args)
+    case "adr-init":
+      return cmdAdrInit(args)
 
     case "help":
       return cmdHelp()
@@ -376,4 +464,9 @@ function main() {
   }
 }
 
-process.exit(main())
+main()
+  .then((code) => process.exit(typeof code === "number" ? code : 0))
+  .catch((e) => {
+    err(`未捕获错误：${e?.stack ?? e}`)
+    process.exit(1)
+  })

package/codeforge.json

@@ -65,6 +65,30 @@
           "anthropic/claude-sonnet-4-6",
           "google/gemini-3-pro"
         ]
+      },
+      "discover": {
+        "_doc": "需求澄清者（采访人设）：长程对话 + 强 thinking，复用 planner 同档（Opus deep）。",
+        "model": "anthropic/claude-opus-4-7",
+        "category": "deep",
+        "tier": "deep",
+        "thinking": { "type": "enabled", "budget_tokens": 6000 },
+        "fallback_models": [
+          "openai/gpt-5.5",
+          "anthropic/claude-sonnet-4-6",
+          "google/gemini-3-pro"
+        ]
+      },
+      "discover-challenger": {
+        "_doc": "强对抗子 agent：跨家族避免同源偏见（参考 reviewer 选型），结论由离散触发组合锁死。",
+        "model": "openai/gpt-5.5",
+        "category": "ultrabrain",
+        "tier": "deep",
+        "thinking": { "type": "enabled", "budget_tokens": 3000 },
+        "fallback_models": [
+          "anthropic/claude-opus-4-7",
+          "anthropic/claude-sonnet-4-6",
+          "google/gemini-3-pro"
+        ]
       }
     },
 

package/commands/adr-init.md

@@ -0,0 +1,67 @@
+---
+description: 一键把 ADR 体系（adr-check + git hooks + 模板）下发到当前 git 项目
+---
+
+<!-- ADR:adr-distribution-init -->
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: adr-init
+  version: 1.0.0
+  trigger_workflow: null
+  allowed_tools: adr-init
+  说明：单 tool 命令，把 CodeForge 的 ADR 体系一键下发到当前 git 项目
+-->
+
+
+# /adr-init — 一键下发 ADR 体系
+
+把 CodeForge 维护的 ADR 体系（决策先行 + 三向引用 + 触发式补全 + README 索引同步）下发到**当前 git 项目**：
+
+- `scripts/adr-check.mjs`、`scripts/adr-index-sync.mjs`（泛化版，支持 `ADR_ROOT` / `ADR_DIR` 环境变量）
+- `.githooks/pre-commit`（staged 模式校验）、`.githooks/pre-push`（last-commit 模式校验）
+- `docs/adr/README.md`（索引骨架，含 HTML 注释 marker）、`docs/adr/template.md`
+- `.github/pull_request_template.md`（ADR checklist）
+
+零 npm 依赖：用 `git config core.hooksPath .githooks`（自动启用，无需 husky）。
+
+## 输入
+
+可选参数：$ARGUMENTS
+
+支持的 flag（在用户对话里说，由 LLM 解析后传给 `adr-init` tool）：
+
+- `--force`：覆盖已存在文件（覆盖前自动 `.bak.<时间戳>` 备份）
+- `--dry-run`：只打印将要执行的写入计划，不实际写盘
+- `--write-prepare`：（npm 项目）自动合并 `git config core.hooksPath .githooks` 到 `package.json scripts.prepare`；写前自动 backup package.json
+- `--no-pre-push`：只装 pre-commit，不装 pre-push
+
+## 用法
+
+```
+/adr-init
+/adr-init --dry-run
+/adr-init --force
+/adr-init --write-prepare
+```
+
+也可在 shell 跑等价命令：
+
+```
+npx @andyqiu/codeforge adr-init [--force] [--dry-run] [--write-prepare] [--no-pre-push]
+```
+
+## 行为
+
+1. 检查当前目录是否 git 仓库（否则报错并停止）
+2. 解析 `assets/adr-init/` 资产根（兼容 npm 全局 / npx / 本仓库 dev 三种安装形态）
+3. 按清单复制文件：
+   - 默认 `exists → skip`；`--force` 覆盖前自动 `.bak.<ts>` 备份
+   - hook 文件自动 `chmod 0o755`（Windows 上吞错）
+4. 运行 `git config core.hooksPath .githooks` 启用 hooks
+5. 报告写入 / 跳过 / 备份 / 建议 / 警告
+
+## 失败回退
+
+- 当前目录非 git 仓库 → 返回 `reason: "not_git_repo"`，建议用户先 `git init`
+- 资产路径找不到（npm 包 `files` 未含 `assets/`）→ 返回 `reason: "assets_not_found"`，提示重装
+- `git config` 失败 → 仍返回 ok=true，但 warnings 含具体错误，请用户手动执行

package/dist/adr-init.js

@@ -0,0 +1,207 @@
+// lib/adr-init.ts
+import { spawnSync } from "node:child_process";
+import { existsSync, promises as fsp } from "node:fs";
+import * as path from "node:path";
+import * as url from "node:url";
+function resolveAssetsRoot() {
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  let dir = here;
+  for (let i = 0;i < 6; i++) {
+    if (existsSync(path.join(dir, "package.json")) && existsSync(path.join(dir, "assets", "adr-init"))) {
+      return path.join(dir, "assets", "adr-init");
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  throw new Error(`assets/adr-init/ 未找到（从 ${here} 上溯 6 层）；` + `如果是 npm 安装请检查 package.json "files" 字段是否包含 "assets/"`);
+}
+function isGitRepo(cwd) {
+  try {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+function runGitConfigHooksPath(cwd) {
+  try {
+    const r = spawnSync("git", ["config", "core.hooksPath", ".githooks"], {
+      cwd,
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+    if (r.status === 0)
+      return { ok: true };
+    return { ok: false, error: (r.stderr ?? "").trim() || `exit=${r.status}` };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+async function runAdrInit(opts = {}) {
+  const cwd = path.resolve(opts.cwd ?? process.cwd());
+  const force = !!opts.force;
+  const dryRun = !!opts.dryRun;
+  const writePrepare = !!opts.writePrepare;
+  const installPrePush = opts.installPrePush !== false;
+  const result = {
+    ok: true,
+    wrote: [],
+    skipped: [],
+    backedUp: [],
+    suggestions: [],
+    warnings: [],
+    dryRun
+  };
+  if (!isGitRepo(cwd)) {
+    result.ok = false;
+    result.reason = "not_git_repo";
+    result.warnings.push(`${cwd} 不是 git 仓库；adr-init 需要 git 才能下发 hooks`);
+    return result;
+  }
+  let assetsRoot;
+  try {
+    assetsRoot = resolveAssetsRoot();
+  } catch (e) {
+    result.ok = false;
+    result.reason = "assets_not_found";
+    result.warnings.push(e instanceof Error ? e.message : String(e));
+    return result;
+  }
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const plan = [
+    { src: "scripts/adr-check.mjs", dst: "scripts/adr-check.mjs" },
+    { src: "scripts/adr-index-sync.mjs", dst: "scripts/adr-index-sync.mjs" },
+    { src: "docs/adr/README.md", dst: "docs/adr/README.md" },
+    { src: "docs/adr/template.md", dst: "docs/adr/template.md" },
+    {
+      src: ".github/pull_request_template.md",
+      dst: ".github/pull_request_template.md"
+    },
+    { src: "githooks/pre-commit.sh", dst: ".githooks/pre-commit", chmod: 493 }
+  ];
+  if (installPrePush) {
+    plan.push({
+      src: "githooks/pre-push.sh",
+      dst: ".githooks/pre-push",
+      chmod: 493
+    });
+  }
+  for (const item of plan) {
+    const srcAbs = path.join(assetsRoot, item.src);
+    const dstAbs = path.join(cwd, item.dst);
+    if (!existsSync(srcAbs)) {
+      result.warnings.push(`资产缺失：${item.src}（跳过 ${item.dst}）`);
+      continue;
+    }
+    if (existsSync(dstAbs)) {
+      if (!force) {
+        result.skipped.push(item.dst);
+        continue;
+      }
+      const bakRel = `${item.dst}.bak.${ts}`;
+      if (!dryRun) {
+        try {
+          await fsp.copyFile(dstAbs, path.join(cwd, bakRel));
+        } catch (e) {
+          result.ok = false;
+          result.reason = "io_error";
+          result.warnings.push(`备份 ${item.dst} 失败：${e instanceof Error ? e.message : String(e)}`);
+          return result;
+        }
+      }
+      result.backedUp.push(bakRel);
+    }
+    if (!dryRun) {
+      try {
+        await fsp.mkdir(path.dirname(dstAbs), { recursive: true });
+        await fsp.copyFile(srcAbs, dstAbs);
+        if (item.chmod !== undefined) {
+          try {
+            await fsp.chmod(dstAbs, item.chmod);
+          } catch (e) {
+            if (process.platform !== "win32") {
+              result.warnings.push(`chmod ${item.dst} 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+          }
+        }
+      } catch (e) {
+        result.ok = false;
+        result.reason = "io_error";
+        result.warnings.push(`写入 ${item.dst} 失败：${e instanceof Error ? e.message : String(e)}`);
+        return result;
+      }
+    }
+    result.wrote.push(item.dst);
+  }
+  if (!dryRun) {
+    const r = runGitConfigHooksPath(cwd);
+    if (r.ok) {
+      result.suggestions.push("已运行：git config core.hooksPath .githooks（hooks 已启用）");
+    } else {
+      result.warnings.push(`自动启用 hooks 失败：${r.error ?? "未知错误"}；请手动执行 git config core.hooksPath .githooks`);
+    }
+  } else {
+    result.suggestions.push("[dry-run] 将运行：git config core.hooksPath .githooks");
+  }
+  const pkgPath = path.join(cwd, "package.json");
+  const isNpm = existsSync(pkgPath);
+  if (isNpm) {
+    if (writePrepare) {
+      try {
+        const raw = await fsp.readFile(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        const existing = (pkg.scripts && typeof pkg.scripts.prepare === "string" ? pkg.scripts.prepare : "") ?? "";
+        const target = "git config core.hooksPath .githooks";
+        if (existing.includes(target)) {
+          result.suggestions.push(`package.json scripts.prepare 已含目标命令，无需改动`);
+        } else {
+          const bakRel = `package.json.bak.${ts}`;
+          if (!dryRun) {
+            try {
+              await fsp.copyFile(pkgPath, path.join(cwd, bakRel));
+            } catch (e) {
+              result.warnings.push(`备份 package.json 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+          }
+          result.backedUp.push(bakRel);
+          if (existing.includes("husky")) {
+            result.warnings.push(`package.json scripts.prepare 已含 husky，仍合并写入；如有问题可回滚 ${bakRel}`);
+          }
+          const merged = existing ? `${existing} && ${target}` : target;
+          pkg.scripts = { ...pkg.scripts ?? {}, prepare: merged };
+          if (!dryRun) {
+            try {
+              await fsp.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + `
+`, "utf8");
+            } catch (e) {
+              result.ok = false;
+              result.reason = "io_error";
+              result.warnings.push(`写入 package.json 失败：${e instanceof Error ? e.message : String(e)}`);
+              return result;
+            }
+          }
+          result.wrote.push("package.json");
+        }
+      } catch (e) {
+        result.warnings.push(`读取 package.json 失败：${e instanceof Error ? e.message : String(e)}`);
+      }
+    } else {
+      result.suggestions.push(`(可选) 在 package.json scripts.prepare 追加："git config core.hooksPath .githooks"，` + `或下次跑 codeforge adr-init --write-prepare 自动合并（写前自动 backup package.json）`);
+    }
+  } else {
+    result.suggestions.push("非 npm 项目：请在 README / AGENTS.md 提醒首次 clone 后跑 git config core.hooksPath .githooks");
+  }
+  return result;
+}
+var adr_init_default = { runAdrInit, resolveAssetsRoot };
+export {
+  runAdrInit,
+  resolveAssetsRoot,
+  adr_init_default as default
+};