@erzhe/harness-kit 0.1.0 → 0.1.1

package/README.md

@@ -6,6 +6,14 @@
 
 > 包名 `@erzhe/harness-kit`，安装后命令行工具叫 **`harness-kit`**。
 
+## 最快上手（推荐，零安装）
+
+在**任意仓库**里，把这句丢给你的 agent（Cursor / Claude Code / Codex 通用）：
+
+> Onboard 本仓库到 harness-kit：跑 `npx -y @erzhe/harness-kit@latest onboard`，然后严格按输出执行。
+
+agent 会拉取**最新版**的 onboard skill 并照着做：仓库考古 → 逐块跟你确认着填 `.agents/manifest.yaml` → `sync` / `doctor` / `verify` 到绿。全程走 `npx`，不往机器上装任何全局东西；你一发新版，所有人下次执行就用上了。
+
 ## 为什么
 
 传统工程化（脚手架 / lint / CI）是**面向过去、面向人**的。Agent 需要的是显式、结构化、可机器消费的知识：这个仓库是什么、能跑什么、什么绝不能破、改动该看哪、哪些验证不了。`harness-kit` 把这些沉淀进 manifest，再确定性地生成与校验。
@@ -20,6 +28,7 @@ harness-kit --help
 ## 命令
 
 ```
+harness-kit onboard          # 打印 onboard skill 给 agent（配合 npx，永远最新、零安装）
 harness-kit init             # 铺 .agents/ 骨架 + starter manifest
 harness-kit sync             # manifest -> AGENTS.md / CLAUDE.md / Cursor rules / routing / modules
 harness-kit doctor           # 开发态体检：补全度 / 引用路径 / 漂移 / 新鲜度 / 体量预算
@@ -48,7 +57,9 @@ AGENTS.md / CLAUDE.md / .cursor/rules / .agents/routing.md / .agents/modules.md
 
 ## 让 agent 来配置：onboard skill
 
-手写 manifest 门槛高，但对 agent 是绝配。随包附带的 [`skills/erzhe-harness-init`](skills/erzhe-harness-init/SKILL.md) 引导 agent 做仓库考古、逐块跟你确认着填 manifest、再跑 `sync/doctor/verify` 到绿。把它软链到 `~/.cursor/skills/` 或 `~/.claude/skills/` 即可被发现。
+手写 manifest 门槛高，但对 agent 是绝配。随包附带的 [`skills/erzhe-harness-init`](skills/erzhe-harness-init/SKILL.md) 引导 agent 做仓库考古、逐块跟你确认着填 manifest、再跑 `sync/doctor/verify` 到绿。
+
+最省事的用法就是上面的 [最快上手](#最快上手推荐零安装)——`npx ... onboard` 把 skill 打印给 agent，零安装、永远最新。若想让某个 agent **自动触发**（不用每次点名），可选地把 skill 软链进它的 skill 目录：`ln -sf "$(npm root -g)/@erzhe/harness-kit/skills/erzhe-harness-init" ~/.cursor/skills/`。
 
 ## 文档
 

package/SPEC-v0.md

@@ -165,7 +165,9 @@ generate:
 5. 新鲜度：`knowledge.binds` 的源文件 hash 变了 → 报 drift；`invariants` 里 `manual:true` 的计入"待补门禁"技术债并给出数量。
 6. **AGENTS.md 体量预算**：生成的 `AGENTS.md` 超过 ~150 行 / ~700 词告警。渐进式披露——入口只指路，细节放 `.agents/` 按需加载，绝不让 Agent 读不完。
 
-`harness verify`（CI 门禁，全确定性）= 所有 `invariants` 的 `enforcement`/`check` + `contracts.check` + `capabilities.verify` + "生成物无漂移"。任一失败即 fail。
+`harness-kit verify`（CI 门禁，全确定性）= 所有 `invariants` 的 `enforcement`/`check` + `contracts` 的 `check`/`snapshot` + "生成物无漂移"。任一失败即 fail。
+
+> **`verify` 不执行任何 `capabilities`**。`capabilities.verify` 只是给人 / agent 看的"如何验证本仓"指针；若真去执行会与自身无限递归。声明为 `mutating` / `background` 的 capability 一律进 GAPS（诚实标注"未在门禁里跑"），不实跑。所以放心声明 `setup: rush install`、`build: go build` 等——`verify` 不会在无网 / 无依赖环境里去跑它们。
 
 **契约校验（v0.2，协议无关）**：契约的破坏检测有两条互补路径，CLI **不理解任何协议语义**，只当调度器 + 基线框架：
 - `check`：仓库自带的破坏检测工具（HTTP → `oasdiff`；gRPC/protobuf → `buf breaking`；库 → `api-extractor`；CLI → 自写脚本），exit 0 = 兼容。CLI 只 `execSync` 看退出码。

package/dist/harness-kit.cjs

@@ -11214,11 +11214,11 @@ var require_out = __commonJS({
       async.read(path2, getSettings(optionsOrSettingsOrCallback), callback);
     }
     exports2.stat = stat;
-    function statSync(path2, optionsOrSettings) {
+    function statSync3(path2, optionsOrSettings) {
       const settings = getSettings(optionsOrSettings);
       return sync.read(path2, settings);
     }
-    exports2.statSync = statSync;
+    exports2.statSync = statSync3;
     function getSettings(settingsOrOptions = {}) {
       if (settingsOrOptions instanceof settings_1.default) {
         return settingsOrOptions;
@@ -16471,7 +16471,7 @@ function useColor() {
 var program = new Command();
 
 // src/cli.ts
-var import_node_path11 = require("node:path");
+var import_node_path12 = require("node:path");
 
 // src/commands/init.ts
 var import_node_fs3 = require("node:fs");
@@ -16485,8 +16485,12 @@ function sha256(input) {
   return (0, import_node_crypto.createHash)("sha256").update(input).digest("hex");
 }
 function hashFile(absPath) {
-  if (!(0, import_node_fs2.existsSync)(absPath)) return null;
-  return sha256((0, import_node_fs2.readFileSync)(absPath));
+  try {
+    if (!(0, import_node_fs2.statSync)(absPath).isFile()) return null;
+    return sha256((0, import_node_fs2.readFileSync)(absPath));
+  } catch {
+    return null;
+  }
 }
 function readText(absPath) {
   return (0, import_node_fs2.existsSync)(absPath) ? (0, import_node_fs2.readFileSync)(absPath, "utf8") : null;
@@ -16841,6 +16845,7 @@ function syncCmd(repo) {
 }
 
 // src/commands/doctor.ts
+var import_fast_glob = __toESM(require_out4(), 1);
 var import_node_fs5 = require("node:fs");
 var import_node_path7 = require("node:path");
 var AGENTS_MAX_LINES = 150;
@@ -16859,6 +16864,18 @@ function doctorCmd(repo) {
       warn(i.msg);
     }
   }
+  for (const inv of m.invariants ?? []) {
+    if (!inv.enforcement) continue;
+    const globs = inv.enforcement.path_glob?.length ? inv.enforcement.path_glob : ["**/*"];
+    const n = import_fast_glob.default.sync(globs, {
+      cwd: repo,
+      onlyFiles: true,
+      dot: false,
+      ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
+    }).length;
+    if (n === 0)
+      warn(`invariant ${inv.id}: enforcement path_glob matches 0 files \u2014 passes without checking anything (wrong path_glob for this repo layout?)`);
+  }
   info("\n2) Referenced paths");
   const checkPath = (rel, label) => {
     if ((0, import_node_fs5.existsSync)((0, import_node_path7.join)(repo, ".agents", rel))) ok(`${label}: ${rel}`);
@@ -16867,19 +16884,24 @@ function doctorCmd(repo) {
       problems++;
     }
   };
-  const checkRepoPath = (rel, label) => {
-    if ((0, import_node_fs5.existsSync)((0, import_node_path7.join)(repo, rel))) ok(`${label}: ${rel}`);
-    else {
-      warn(`${label} points at a missing path: ${rel}`);
+  const checkRepoPath = (rel, label, wantFile = false) => {
+    const abs = (0, import_node_path7.join)(repo, rel);
+    if (!(0, import_node_fs5.existsSync)(abs)) {
+      err(`${label} points at a missing path: ${rel}`);
       problems++;
-    }
+    } else if (wantFile && (0, import_node_fs5.statSync)(abs).isDirectory()) {
+      warn(`${label}: ${rel} is a directory \u2014 entry/binds should be a file (freshness hashes file content)`);
+    } else ok(`${label}: ${rel}`);
   };
-  for (const k of m.knowledge ?? []) checkPath(k.path, "knowledge");
+  for (const k of m.knowledge ?? []) {
+    checkPath(k.path, "knowledge");
+    for (const b of new Set(k.binds ?? [])) checkRepoPath(b, `knowledge "${k.path}" binds`, true);
+  }
   if (m.playbooks?.dir) checkPath(m.playbooks.dir, "playbooks");
   for (const r of m.routing ?? [])
     for (const p of /* @__PURE__ */ new Set([...r.read ?? [], ...r.entry ?? []])) checkRepoPath(p, `routing "${r.when}"`);
   for (const mod of m.modules ?? [])
-    for (const p of new Set(mod.entry ?? [])) checkRepoPath(p, `module ${mod.name}`);
+    for (const p of new Set(mod.entry ?? [])) checkRepoPath(p, `module ${mod.name}`, true);
   info("\n3) Generated files drift");
   for (const [rel, content] of renderTargets(m)) {
     const cur = readText((0, import_node_path7.join)(repo, rel));
@@ -16961,13 +16983,13 @@ function writeBaseline(repo, id, content) {
 }
 
 // src/enforce.ts
-var import_fast_glob = __toESM(require_out4(), 1);
+var import_fast_glob2 = __toESM(require_out4(), 1);
 var import_node_fs6 = require("node:fs");
 var import_node_path9 = require("node:path");
 var DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/.agents/map/**"];
 function runEnforcement(repo, invId, e) {
   const globs = e.path_glob?.length ? e.path_glob : ["**/*"];
-  const files = import_fast_glob.default.sync(globs, {
+  const files = import_fast_glob2.default.sync(globs, {
     cwd: repo,
     onlyFiles: true,
     dot: false,
@@ -17142,6 +17164,44 @@ function acceptContractCmd(repo, id) {
   return problems ? 1 : 0;
 }
 
+// src/commands/onboard.ts
+var import_node_fs7 = require("node:fs");
+var import_node_path11 = require("node:path");
+var import_node_url = require("node:url");
+var import_meta = {};
+function moduleDir() {
+  if (typeof __dirname !== "undefined" && __dirname) return __dirname;
+  return (0, import_node_path11.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+}
+var HERE = moduleDir();
+var SKILL_REL = "skills/erzhe-harness-init/SKILL.md";
+var META = `<!-- harness-kit onboard -->
+You are an AI agent onboarding the CURRENT repository to harness-kit.
+Follow the skill below verbatim. Run every harness-kit command through
+\`npx -y @erzhe/harness-kit@latest <cmd>\` \u2014 always the latest version, no global install.
+Do not fabricate: confirm uncertain fields with the user, and report honest GAPS.
+
+---
+
+`;
+function resolveSkill() {
+  for (const up of ["..", (0, import_node_path11.join)("..", "..")]) {
+    const p = (0, import_node_path11.join)(HERE, up, SKILL_REL);
+    if ((0, import_node_fs7.existsSync)(p)) return p;
+  }
+  return null;
+}
+function onboardCmd() {
+  const p = resolveSkill();
+  if (!p) {
+    err(`bundled skill not found (${SKILL_REL})`);
+    return 1;
+  }
+  process.stdout.write(META);
+  process.stdout.write((0, import_node_fs7.readFileSync)(p, "utf8"));
+  return 0;
+}
+
 // src/cli.ts
 function guard(fn) {
   try {
@@ -17153,13 +17213,14 @@ function guard(fn) {
   }
 }
 var program2 = new Command();
-program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.0");
-var repoOf = (o) => (0, import_node_path11.resolve)(o.repo);
+program2.name("harness-kit").description("AI-friendly repo harness").version("0.1.1");
+var repoOf = (o) => (0, import_node_path12.resolve)(o.repo);
 program2.command("init").description("scaffold .agents/ skeleton + starter manifest").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--name <name>", "project name", "my-project").option("--force", "overwrite existing manifest", false).action((o) => guard(() => initCmd(repoOf(o), o.name, o.force)));
 program2.command("sync").description("generate tool files (AGENTS.md, CLAUDE.md, .cursor rules) from manifest").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => syncCmd(repoOf(o))));
 program2.command("doctor").description("dev-time health check: completeness, drift, freshness, tech debt").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => doctorCmd(repoOf(o))));
 program2.command("verify").description("CI gate: run enforceable invariants + contracts + drift; nonzero on failure").option("-C, --repo <dir>", "target repo dir", process.cwd()).action((o) => guard(() => verifyCmd(repoOf(o))));
 program2.command("accept-contract").description("record current contract fingerprint(s) as the accepted baseline (after an intended change)").option("-C, --repo <dir>", "target repo dir", process.cwd()).option("--id <id>", "only this contract (default: all with a snapshot command)").action((o) => guard(() => acceptContractCmd(repoOf(o), o.id)));
+program2.command("onboard").description("print the erzhe-harness-init skill for an agent to follow (use via npx, always latest)").action(() => guard(() => onboardCmd()));
 program2.parseAsync();
 /*! Bundled license information:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erzhe/harness-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "AI-friendly repo harness: a manifest.yaml single source of truth that generates AGENTS.md / CLAUDE.md / Cursor rules and enforces invariants, contracts and drift via `harness-kit verify`.",
   "keywords": [
@@ -41,9 +41,10 @@
   },
   "scripts": {
     "harness": "tsx src/cli.ts",
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --target=node18 --outfile=dist/harness-kit.cjs && chmod +x dist/harness-kit.cjs",
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --target=node18 --log-override:empty-import-meta=silent --outfile=dist/harness-kit.cjs && chmod +x dist/harness-kit.cjs",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test test/*.test.ts",
+    "test:repos": "bash scripts/regression.sh",
     "prepare": "pnpm build"
   },
   "dependencies": {

package/skills/erzhe-harness-init/SKILL.md

@@ -13,11 +13,11 @@ CLI 只负责机械骨架 + 确定性门禁；**理解仓库、把隐性知识
 
 按可用性择一，后续统一用 `harness-kit` 指代（包名 `@erzhe/harness-kit`，bin 是 `harness-kit`）：
 
+- **推荐（零安装、永远最新）**：`npx -y @erzhe/harness-kit@latest`
 - 已全局安装：`harness-kit`
-- 未安装、临时用：`npx @erzhe/harness-kit`
 - 在 harness-kit 仓内开发：`pnpm exec tsx src/cli.ts`
 
-先跑 `harness-kit --help` 确认可用。
+先跑一次 `--help` 确认可用（如 `npx -y @erzhe/harness-kit@latest --help`）。全程用同一种方式，别混用版本。
 
 ## 1. 铺骨架（若还没有 .agents/）
 
@@ -40,9 +40,9 @@ harness-kit init --repo .
 1. **identity**：读 `README` / `package.json` / 顶层目录。填 `name`、一句话 `summary`、`scope_in` / `scope_out`（哪些该改、哪些别碰）、`upstream` / `downstream`。
 2. **capabilities**：从 `package.json` scripts、`Makefile`、`justfile`、CI 配置推断常用命令（setup / build / test / dev / lint / release）。给 `run`；长驻的标 `background: true`，有副作用的标 `mutating: true`。
 3. **environment**：从 `.env.example` / README 抓关键环境变量。危险的标 `secret: true`、必需的标 `required: true`。
-4. **contracts**：识别对外接口——HTTP 路由文件、CLI flags、导出的公共 API、proto/schema、事件。**尽量给 `snapshot` 命令**（打印当前接口指纹到 stdout，如 `grep -oE '"/api/[^"]*"' src/routes.ts | sort -u`），CLI 会存基线并 diff。给不出自动检查的填 `manual_verify` 说明。
+4. **contracts**：识别对外接口——HTTP 路由文件、CLI flags、导出的公共 API、proto/schema/IDL、事件。**尽量给 `snapshot` 命令**（打印当前接口指纹到 stdout，如 `grep -oE '"/api/[^"]*"' src/routes.ts | sort -u`），CLI 会存基线并 diff。给不出自动检查的填 `manual_verify` 说明（进 GAPS）。两条纪律：(a) **过滤注释/生成物噪音**——配置里被注释掉的示例条目会污染指纹、日后清注释误报 drift，必要时先 `sed 's://.*::'` 剥注释再抓；(b) **命令含引号/正则/管道就下沉到 `.agents/checks/<id>.sh`**（脚本里 `cd` 到仓库根 + `LC_ALL=C` 保跨机字节一致），manifest 里写 `snapshot: bash .agents/checks/<id>.sh`——比把转义地狱硬塞进 YAML 干净，过滤规则也可 review。
 5. **invariants**：从 `CONTRIBUTING` / 现有 `AGENTS.md` / 代码约定提炼"必须始终成立"的规则。**能写成正则的用 `enforcement`**（`forbid_pattern` / `require_pattern` + `path_glob` 限定作用域，glob 是 include-only）；否则标 `manual: true`。
-6. **modules**：主要子系统各写一张模块卡：`role`、`entry`（入口文件，也用于新鲜度绑定）、`upstream` / `downstream`、`must_know`、`pitfalls`（常见坑——最高价值的一栏）。
+6. **modules**：主要子系统各写一张模块卡：`role`、`entry`、`upstream` / `downstream`、`must_know`、`pitfalls`（常见坑——最高价值的一栏）。⚠️ `entry`（以及 knowledge 的 `binds`）必须指到**具体文件**（如 `src/index.ts`），**不能是目录**——它要 hash 文件内容做新鲜度绑定；`routing.read` 用目录则 OK。
 7. **routing**：把常见改动类型（修 bug / 加接口 / 改 UI / 动权限 / 发版…）各写一行：`read`（先读哪些文件）、`entry`、`dont_assume`（别瞎猜什么）、`verify`（最少验证步骤，引用 capability 动词或原始命令）。
 8. **knowledge**：把 agent 从代码推断不出来的东西写进 `.agents/knowledge/`；重要决策建一篇 journal ADR（`knowledge/journal/NNNN-*.md`）。用 `binds` 把知识条目绑定到源文件，源文件变了会触发新鲜度告警。**只沉淀非显然的知识，别记一次性噪音或代码里显而易见的东西。**