agentic-flow-kit 1.8.7 → 2.1.0

package/src/add-gate.test.mjs

@@ -1,103 +0,0 @@
-#!/usr/bin/env node
-// add-gate.test.mjs — gate 防改锚（2026-10-11 P3-1）装户端到端测试。
-// 手法：真实 bin/flow-kit.mjs init 建临时装户（fresh-init.test.mjs 同款）→ CLI add-gate test-protect，
-// 断言 kit.json owned：逐字拷贝的 gate 脚本带 srcSha256＝安装时刻包源文件 LF 归一 sha；
-// local-pre-commit（合并接线件，非逐字拷贝）不写 srcSha256。再覆盖三条锚路径——
-//   ①幂等重跑（盘面＝包源）安静且锚不动；②盘面手改后重跑（未 --force）WARN 差异 + 原锚保留
-//   （doctor checkGateAnchors 端到端抓到手改）；③--force 重装重锚。
-// 用法：node src/add-gate.test.mjs
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const CLI = path.join(ROOT, 'bin', 'flow-kit.mjs');
-const GATE = 'test-protect';
-const GATE_REL = `.agents/hooks/check-test-protect.mjs`;
-const LP_REL = '.agents/hooks/local-pre-commit';
-const PKG_GATE_SRC = path.join(ROOT, 'modules', 'gates', GATE, 'check-test-protect.mjs');
-
-// checkGateAnchors 端到端联动：add-gate 写下的锚正是 doctor 锚校验读取的判据（耦合面单独断言）
-const { checkGateAnchors } = await import(pathToFileURL(path.join(ROOT, 'src', 'doctor.mjs')).href);
-
-let pass = 0;
-let fail = 0;
-const check = (name, cond, detail = '') => {
-  if (cond) { pass++; console.log(`PASS  ${name}`); }
-  else { fail++; console.log(`FAIL  ${name}${detail ? `\n      ${detail}` : ''}`); }
-};
-// LF 归一 sha（与 add-gate shaText / doctor checkGateAnchors 同口径，跨 checkout 字节稳定）
-const shaOf = (p) => createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-const R = (p) => fs.readFileSync(p, 'utf8');
-
-// ---- 建临时装户：git init + 真实 CLI init（fresh-init.test.mjs 同款）----
-const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-addgate-'));
-spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', ['init', '-q'], { cwd: dir });
-const init = spawnSync(process.execPath, [CLI, 'init', '--stack', 'none', '--hosts', 'claude', '--board-port', '8941', '--dir', dir], { encoding: 'utf8', timeout: 120000 });
-if (init.status !== 0) {
-  console.error(`add-gate.test.mjs：前置 init 失败无法继续\n${(init.stdout || '') + (init.stderr || '')}`);
-  process.exit(1);
-}
-const kitOf = () => JSON.parse(R(path.join(dir, '.agents', 'kit.json')));
-const gateEntry = () => kitOf().owned.find((f) => f.rel === GATE_REL);
-
-// ---- 场景 1：首装——逐字拷贝件写锚＝包源 sha；local-pre-commit 不写锚 ----
-{
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  check('S1 add-gate exit 0', r.status === 0, `exit=${r.status}\n${out.slice(-400)}`);
-  const gate = gateEntry();
-  check('S1 gate 脚本带 srcSha256＝包源文件 LF 归一 sha（安装时刻包源）', !!gate && gate.srcSha256 === shaOf(PKG_GATE_SRC), JSON.stringify(gate || null));
-  check('S1 gate 台账 sha256＝盘面（LF 归一记账）', !!gate && gate.sha256 === shaOf(path.join(dir, GATE_REL)), JSON.stringify(gate || null));
-  check('S1 门禁脚本落盘且与包源一致（逐字拷贝）', R(path.join(dir, GATE_REL)) === R(PKG_GATE_SRC));
-  const lp = kitOf().owned.find((f) => f.rel === LP_REL);
-  check('S1 local-pre-commit（合并接线件）不写 srcSha256', !!lp && lp.srcSha256 === undefined, JSON.stringify(lp || null));
-  check('S1 local-pre-commit 台账 sha256 刷为接线后盘面', !!lp && lp.sha256 === shaOf(path.join(dir, LP_REL)), JSON.stringify(lp || null));
-  check('S1 首装输出无盘面/包源差异 WARN', !out.includes('盘面与包源不一致'), out);
-}
-
-// ---- 场景 2：幂等重跑（未 --force、盘面＝包源）——安静，条目原样 ----
-{
-  const before = JSON.stringify(gateEntry());
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  check('S2 幂等重跑 exit 0 且无差异 WARN', r.status === 0 && !out.includes('盘面与包源不一致'), out);
-  check('S2 锚与台账条目原样', JSON.stringify(gateEntry()) === before, `${before} → ${JSON.stringify(gateEntry())}`);
-}
-
-// ---- 场景 3：盘面手改后重跑（未 --force）——WARN 差异可见，原锚保留（手改永久留痕）----
-{
-  fs.writeFileSync(path.join(dir, GATE_REL), `${R(PKG_GATE_SRC)}\n// 本地手改：放宽红线（测试标记）\n`);
-  const before = gateEntry();
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  const after = gateEntry();
-  check('S3 手改后重跑出 WARN（盘面与包源不一致，含文件名）', out.includes('盘面与包源不一致') && out.includes('check-test-protect.mjs'), out);
-  check('S3 已有台账条目 → WARN 指明原锚保留', out.includes('原锚保留'), out);
-  check('S3 原锚保留（未被盘面重锚——重锚会把手改吸收成无差异）', after.srcSha256 === before.srcSha256 && after.srcSha256 === shaOf(PKG_GATE_SRC), `${JSON.stringify(before)} → ${JSON.stringify(after)}`);
-  check('S3 台账 sha256 亦不被改写（未 --force 不动既有条目）', after.sha256 === before.sha256, `${JSON.stringify(before)} → ${JSON.stringify(after)}`);
-  check('S3 手改盘面幸存（未 --force 不覆盖）', R(path.join(dir, GATE_REL)).includes('本地手改'), R(path.join(dir, GATE_REL)).slice(-120));
-  const d = checkGateAnchors(dir);
-  check('S3 doctor 锚校验按 add-gate 写下的锚抓到手改（端到端）', d.skipped === false && d.mismatch.includes(GATE_REL), JSON.stringify(d));
-}
-
-// ---- 场景 4：--force 重装——盘面恢复包源 + 锚随新安装刷新（重锚路径）----
-{
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir, '--force'], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  const gate = gateEntry();
-  check('S4 --force 重装恢复包源内容', R(path.join(dir, GATE_REL)) === R(PKG_GATE_SRC));
-  check('S4 锚随新安装刷新（srcSha256＝包源 sha）', !!gate && gate.srcSha256 === shaOf(PKG_GATE_SRC), JSON.stringify(gate || null));
-  check('S4 台账 sha256 回到包面值', !!gate && gate.sha256 === shaOf(PKG_GATE_SRC), JSON.stringify(gate || null));
-  check('S4 输出含安装报告', out.includes('安装到'), out);
-  const d = checkGateAnchors(dir);
-  check('S4 重锚后 doctor 锚校验回到无失配', d.skipped === false && d.mismatch.length === 0 && d.gone.length === 0 && d.total >= 1, JSON.stringify(d));
-}
-
-fs.rmSync(dir, { recursive: true, force: true });
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);

package/src/add-host.mjs

@@ -1,68 +0,0 @@
-// flow-kit add-host <宿主>：init 后补装宿主适配层。
-// 渲染 modules/hosts/<h> → HOSTS[h].dir → managed 台账按 rel 去重补记 → options.hosts 补记
-// → localOnly 宿主（2026-10-05 起暂无命中，见 profiles.mjs#HOSTS.localOnly）.gitignore 追加 → doctor
-import fs from 'node:fs';
-import path from 'node:path';
-import { renderTree } from './render.mjs';
-import { HOSTS, pickStackVars } from './profiles.mjs';
-import { doctor } from './doctor.mjs';
-
-function fail(msg) {
-  console.error(`❌ ${msg}`);
-  process.exit(1);
-}
-
-export function addHost(args, pkgRoot) {
-  const host = args[0];
-  if (!host || host.startsWith('--')) fail(`缺少宿主参数（可选 ${Object.keys(HOSTS).join(' | ')}）`);
-  if (!HOSTS[host]) fail(`未知宿主：${host}（可选 ${Object.keys(HOSTS).join(' | ')}）`);
-
-  let target = process.cwd();
-  let force = false;
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--dir') target = path.resolve(args[++i] || fail('--dir 缺少值'));
-    else if (args[i] === '--force') force = true;
-    else fail(`未知选项：${args[i]}`);
-  }
-
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init`);
-  const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-  kit.options = kit.options || {};
-  const already = Array.isArray(kit.options.hosts) && kit.options.hosts.includes(host);
-  if (already && !force) fail(`${host} 已安装（options.hosts 在册）。覆盖更新用 --force`);
-
-  const vars = { BOARD_PORT: String(kit.options.boardPort || '8933'), ...pickStackVars(kit.options.stack) };
-  console.log(`▶ flow-kit add-host ${host} → ${target}${already ? '（--force 覆盖更新）' : ''}`);
-
-  // 宿主层渲染（已存在保守跳过；--force 覆盖）
-  const r = renderTree(path.join(pkgRoot, 'modules', 'hosts', host), path.join(target, HOSTS[host].dir), vars, { force });
-  if (!r.written.length && r.skipped.length) console.log('  跳过（已存在，未覆盖）：' + r.skipped.join('、'));
-  else console.log(`  安装 ${r.written.length} 份${r.skipped.length ? `，跳过已存在 ${r.skipped.length} 份` : ''}`);
-  if (r.skipped.length) {
-    // 跳过的文件不入 managed 台账（不接管既有内容）——后续 sync 只报「已存在未入台账」，永不升级；纳入包管理须 --force
-    console.log('  ⚠️ 跳过文件不入 managed 台账、后续 sync 不升级（每次仅报告）；纳入包管理用 --force 覆盖');
-  }
-
-  // managed 台账按 rel 去重补记
-  const ledger = new Map((kit.managed || []).map((f) => [f.rel, f]));
-  for (const f of r.written) ledger.set(`${HOSTS[host].dir}/${f.rel}`, { rel: `${HOSTS[host].dir}/${f.rel}`, sha256: f.sha256 });
-  kit.managed = [...ledger.values()].sort((a, b) => a.rel.localeCompare(b.rel));
-  if (!already) kit.options.hosts = [...(kit.options.hosts || []), host];
-  fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
-
-  // localOnly 宿主进 .gitignore（缺才补）。2026-10-05 起七个宿主一律 localOnly:false，该分支暂无宿主命中；
-  // 保留是为了未来重开「本机专属宿主」档位时不必改结构——判定单源在 profiles.mjs#HOSTS.localOnly。
-  if (HOSTS[host].localOnly) {
-    const giPath = path.join(target, '.gitignore');
-    const line = `${HOSTS[host].dir}/`;
-    const giText = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
-    if (!giText.split(/\r?\n/).some((x) => x.trim() === line)) {
-      fs.writeFileSync(giPath, (giText.endsWith('\n') || giText === '' ? giText : giText + '\n') + line + '\n');
-      console.log(`  .gitignore 追加：${line}`);
-    }
-  }
-
-  console.log('▶ flow-kit doctor');
-  doctor(['--dir', target], pkgRoot);
-}

package/src/cli.mjs

@@ -1,169 +0,0 @@
-#!/usr/bin/env node
-// flow-kit CLI 入口：init（安装）/ sync（升级）/ add-host（补宿主）/ add-gate（装门禁）/ doctor（体检）/ validate（只读校验）/ sync-hosts（跨宿主同步）/ help
-import { init } from './init.mjs';
-import { doctor } from './doctor.mjs';
-import { validate } from './validate.mjs';
-import { sync } from './sync.mjs';
-import { syncHosts } from './sync-hosts.mjs';
-import { addHost } from './add-host.mjs';
-import { addGate } from './add-gate.mjs';
-import { route, runPipeline, routeKindList } from './executor.mjs';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-
-const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-function gateNames(pkgRoot) {
-  const dir = path.join(pkgRoot, 'modules', 'gates');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name)
-    .sort();
-}
-
-const GATE_LIST = gateNames(PKG_ROOT).join(' | ') || '无';
-
-// route 的 kind 值域从权威面派生（同 GATE_LIST 纪律）：读包源 new-task.md 的 route-kinds 机器单源，
-//   不手写第二份——否则装户改 kind 时本帮助文本与 route 判定面会双源漂移（B5 同一问题）。
-const ROUTE_KIND_LIST = routeKindList(PKG_ROOT).join('|') || 'require|fix|verify|review|deploy';
-
-export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚手架（agentic-flow-kit）
-
-用法：
-  flow-kit init             安装到当前项目（裸跑无参数 → 交互确认环节；带参数直接执行；
-                            已存在的 AGENTS.md 无工作流骨架时文末追加补齐，其余已存在文件保守跳过）
-  flow-kit sync             升级 managed 文件（未改动→覆盖新版；本地已改→跳过并持续报告——台账不基线化，
-                            不会被下次升级静默覆盖；--force 才覆盖；INDEX/看板等生成器目标重跑锚点重写；
-                            owned 文件永不触碰）
-  flow-kit add-host <宿主>  后补宿主适配层：zcode | opencode | trae | omp | claude | cursor | codex
-                            （已存在文件跳过且不入台账，--force 接管）
-  flow-kit add-gate <门禁>  装门禁模块并接线 local-pre-commit（当前：${GATE_LIST}；装后归项目所有）
-  flow-kit sync-hosts       跨宿主适配层同步：templates/_agents/{commands,roles}/*.md 权威源 vs
-                            modules/hosts/<h>/{agents,commands}/*.md 薄适配——默认 --diff 输出报告；
-                            --apply 单向同步（权威→薄适配，不反向避免污染）；
-                            --strict 漂移判红（CI 机器门用；默认 --diff 恒 exit 0，报告器语义）；
-                            改一处权威源要同步 N 份薄适配，人工 grep 易漏
-  flow-kit doctor           体检：目录布局 / git 钩子 / managed 清单 / 索引漂移 / 跨宿主漂移 / check-loop
-  flow-kit validate         只读校验：包内置 check-loop 引擎对装户盘面跑闭环 20 项检查（不执行装户侧脚本，
-                            不改文档台账）；明细走 stderr，stdout 承载汇总——0/1 退出码可作 CI 独立一道门。
-                            与 doctor 的分工：doctor 查「装得健不健康」（含装户侧引擎校验后执行），
-                            validate 查「盘面内容合不合规」（判定引擎随包版本走）
-
-  ── 执行面（引擎执行器：手动路由 + 自动流水线）─────────────────────────
-                            md 指令与 md 子代理仍装在装户项目（.agents/commands、.agents/roles），
-                            宿主读它们；本 CLI 不复制、不改写它们的正文。执行代码亦留在装户
-                            .agents/scripts/，包只做薄壳转发与判定面。
-  flow-kit route            手动路由的机器面：定级（就高不就低 + 路径下限）+ 判据清单 + 泳道 + 下一阶段
-                            + 该读的 md 指令路径。判据单源 = .agents/scripts/level-criteria.mjs；
-                            路径下限清单 = .agents/level-hints.txt（装户自持、内容项目私有，默认空）。
-                            **诚实边界**：级别是意图面的语义判定（「一处定义、多处消费」），机器判不了语义；
-                            未配 hints 时按 L1 起步并提示补配置，绝不假装判得出。
-                            选项：--kind ${ROUTE_KIND_LIST} ｜ --level L1|L2|L3
-                                  --files "a,b"（改动文件，参与路径下限判定）｜ --dir <目录> ｜ --json
-  flow-kit run <子命令>     自动流水线：薄壳转发装户 pipeline-run 状态机
-                            （start / next / status / watch / abort），参数与退出码原样透传。
-                            驱动协议与停机点语义见 .agents/commands/pipeline-run.md（宿主面权威）。
-                            本命令绝不 spawn AI 会话 / 不伪造原话 / 不带 --no-verify。
-
-init 选项（全部可选，均有默认值）：
-  --stack <技术栈>     dotnet | node（ts/js） | python | go | none（默认 none；ts/js/typescript/javascript
-                       归一为 node）——门禁配置三处：commit-check
-                       条件编译检查（builds）与质量检测（checks：lint/类型/vet 等秒级确定性检查，
-                       有对应配置文件才启用）、settings.json 自检验命令权限（allow）、
-                       AGENTS.md「项目适配区」命令预填
-  --hosts <宿主列表>   逗号分隔：zcode,opencode,trae,omp,claude,cursor,codex（默认 zcode；七个宿主一律入库，不自动进 .gitignore）
-  --board-port <端口>  workflow 看板端口（默认 8933）
-  --dir <目录>         目标项目根（默认当前目录）
-  --force              覆盖已存在的同名文件（默认保守跳过）
-
-sync / add-host 选项：--dir <目录>、--force（覆盖本地已改 / 已装内容）；add-gate 选项：--dir <目录>、--force。
-validate 选项：--strict（advisory warning 也判红）/ --json（机器可读，stdout）/ --dir <目录>（目标项目根，默认当前目录）。
-sync-hosts 选项：--diff（默认，仅报告，不修改）/ --apply（单向同步到薄适配）/ --json（机器可读输出）/ --dir <目录>（目标项目根，默认当前目录）。
-sync-hosts 只在包源仓运行（需要 templates/_agents 与 modules/hosts）：比对 templates/_agents ↔ modules/hosts。
-装户的宿主文件由 init / add-host 写入；刷新用 add-host <宿主> --force。
-route 选项：--kind / --level / --files / --dir <目录>（目标项目根，默认当前目录）/ --json（机器可读）。
-run 参数：除 --dir 外原样透传给装户 pipeline-run（--hint / --triage / --delegated / --files / --run / --json / --adopt / --to / --interval）。
-
-示例：
-  npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 确认安装
-  npx agentic-flow-kit init --stack node --hosts zcode,opencode
-  npx agentic-flow-kit sync                        # 包出新版后升级（本地改过的 managed 文件会跳过并报告）
-  npx agentic-flow-kit add-host opencode           # 后补宿主
-  npx agentic-flow-kit add-gate dotnet-ca          # 装 Clean Architecture 门禁
-  npx agentic-flow-kit doctor                       # 体检
-  npx agentic-flow-kit validate --strict            # 只读结构校验（CI 可用，0/1 退出码）
-  npx agentic-flow-kit sync-hosts --diff           # 看权威源 vs 薄适配漂移
-  npx agentic-flow-kit sync-hosts --apply          # 单向同步到薄适配
-  npx agentic-flow-kit route --kind require --level L1 --files "src/a.ts,src/b.ts"
-  npx agentic-flow-kit run start "给导入功能加审计字段"
-  npx agentic-flow-kit run next --delegated "可以"
-
-装完本地可跑：日常闭环走项目内 .agents/scripts/（零 npm 运行时依赖）；升级 / 体检 / 装门禁用 npx agentic-flow-kit（sync / doctor / add-host / add-gate）；AGENTS.md 生成「AI工作流 + Wiki」骨架，项目细节在「项目适配区」自填。`;
-
-// errText：异步命令失败的统一输出。带 code 的错误把 code 一并打出来——
-//   例：flow-kit route 遇非法 level-hints 会抛 e.code = LEVEL_HINTS_INVALID，
-//   只打 message 等于把机器可判的错误类别在 CLI 边界扔掉（路径与行号仍在 message 里）。
-const errText = (e) => `❌ ${e?.code ? `[${e.code}] ` : ''}${e?.message || e}`;
-
-export function run(argv) {
-  const cmd = argv[0];
-  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    console.log(HELP);
-    return;
-  }
-  if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
-    const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
-    console.log(pkg.version);
-    return;
-  }
-  if (cmd === 'init') {
-    init(argv.slice(1), PKG_ROOT).catch((e) => {
-      console.error(errText(e));
-      process.exit(1);
-    });
-    return;
-  }
-  if (cmd === 'sync') {
-    sync(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'sync-hosts') {
-    const code = syncHosts(argv.slice(1), PKG_ROOT);
-    if (typeof code === 'number') process.exit(code);
-    return;
-  }
-  if (cmd === 'add-host') {
-    addHost(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'add-gate') {
-    addGate(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'doctor') {
-    doctor(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'validate') {
-    validate(argv.slice(1), PKG_ROOT).catch((e) => {
-      console.error(errText(e));
-      process.exit(1);
-    });
-    return;
-  }
-  if (cmd === 'route') {
-    route(argv.slice(1)).catch((e) => {
-      console.error(errText(e));
-      process.exit(1);
-    });
-    return;
-  }
-  if (cmd === 'run') {
-    runPipeline(argv.slice(1));
-    return;
-  }
-  console.error(`未知命令：${cmd}\n\n${HELP}`);
-  process.exit(1);
-}