@afokapu/atdd-bun 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"
@@ -23,7 +23,8 @@
     "bunfig.toml",
     "PLANNER_PORT.md",
     "HOOK_AUDIT.md",
-    "templates"
+    "templates",
+    "integrity.json"
   ],
   "scripts": {
     "test": "bun test",

package/src/cli.ts

@@ -3,6 +3,7 @@ import { enforce, profileNames, type Profile } from "./enforce";
 import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
 import { ciInit, ciStatus } from "./ci";
 import { agentInit, agentStatus } from "./agent";
+import { checkIntegrity, formatIntegrity, integrityInit, integrityStatus } from "./integrity";
 import { releaseCheck } from "./release";
 import { initializeRepository } from "./setup";
 
@@ -16,6 +17,7 @@ const usage = {
     "atdd-bun worktree <start|finish|status>",
     "atdd-bun ci <init|status> [--replace]",
     "atdd-bun agent <init|status> [--replace]",
+    "atdd-bun integrity [init|status] [--replace]",
     "atdd-bun release check",
   ],
   profiles: profileNames,
@@ -66,6 +68,13 @@ if (args[0] === "ci") {
   const result = args[1] === "init" ? await ciInit(process.cwd(), args.includes("--replace")) : args[1] === "status" ? await ciStatus() : fail("ci requires init or status");
   console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
 }
+if (args[0] === "integrity") {
+  if (args[1] === "init" || args[1] === "status") { const result = args[1] === "init" ? await integrityInit(process.cwd(), args.includes("--replace")) : await integrityStatus(); console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1); }
+  if (args[1] !== undefined) fail("integrity takes no argument, or init/status");
+  const findings = await checkIntegrity();
+  if (findings.length) { console.error(formatIntegrity(findings)); process.exit(1); }
+  console.log("atdd-bun integrity: canonical"); process.exit(0);
+}
 if (args[0] === "agent") {
   const result = args[1] === "init" ? await agentInit(process.cwd(), args.includes("--replace")) : args[1] === "status" ? await agentStatus() : fail("agent requires init or status");
   console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);

package/src/index.ts

@@ -10,4 +10,6 @@ export { defaultHookPolicy, hookEvents, hooksStatus, installHooks, runHook, unin
 export type { HookEvent, HookPolicy } from "./hooks";
 export { ciInit, ciStatus } from "./ci";
 export { initializeRepository } from "./setup";
+export { checkIntegrity, checkInstalledPackage, formatIntegrity, integrityInit, loosenedPolicy, writeManifest } from "./integrity";
+export type { IntegrityFinding, IntegrityOptions } from "./integrity";
 export { releaseCheck } from "./release";

package/src/integrity.ts

@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { defaultHookPolicy, type HookPolicy } from "./hooks";
+
+/**
+ * Integrity: the files an agent could change to weaken enforcement must stay canonical.
+ * The same check runs as a local test (a loud reminder the agent sees) and in CI on a
+ * clean install (the verdict the agent cannot fake).
+ */
+export type IntegrityFinding = { file: string; detail: string; restore: string };
+/** `push`: judge the newest commit against its parent (a push to the base branch). Defaults to GITHUB_EVENT_NAME === "push". */
+export type IntegrityOptions = { root?: string; packageRoot?: string; base?: string; push?: boolean };
+
+const PACKAGE = "@afokapu/atdd-bun";
+const ownRoot = resolve(import.meta.dir, "..");
+export const MANIFEST = "integrity.json";
+export const TEST_FILE = "atdd-bun.integrity.test.ts";
+const SKILLS = [".agents/skills/atdd/SKILL.md", ".claude/skills/atdd/SKILL.md"];
+const WORKFLOW = ".github/workflows/atdd-bun.yml";
+const BLOCK = /<!-- atdd-bun:start[\s\S]*?<!-- atdd-bun:end -->/;
+// Generated files carry the version that wrote them; an upgrade must not read as tampering.
+const unstamp = (text: string) => text.replace(/@afokapu\/atdd-bun (?:\d+\.\d+\.\d+(?:-[\w.]+)?|\{\{VERSION\}\})/g, "@afokapu/atdd-bun <version>").replace(/\r\n/g, "\n").trimEnd();
+const sha256 = (data: string | Uint8Array) => new Bun.CryptoHasher("sha256").update(data).digest("hex");
+/** Where `bun test` will find the generated test: the repository's `[test] root` from bunfig.toml, else the repo root. */
+export async function testFilePath(repo: string) {
+  const bunfig = join(repo, "bunfig.toml");
+  const text = existsSync(bunfig) ? await readFile(bunfig, "utf8") : "";
+  const root = text.split(/^\[/m).find(section => section.startsWith("test]"))?.match(/^\s*root\s*=\s*["']([^"']+)["']/m)?.[1];
+  return join(repo, root ?? ".", TEST_FILE);
+}
+const git = async (root: string, args: string[]) => { const child = Bun.spawn({ cmd: ["git", ...args], cwd: root, stdout: "pipe", stderr: "pipe" }); const out = (await new Response(child.stdout).text()).trim(); return { code: await child.exited, out }; };
+
+async function filesBelow(dir: string, base = dir): Promise<string[]> {
+  const out: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) { if (entry.name !== "node_modules") out.push(...await filesBelow(path, base)); }
+    else out.push(relative(base, path).split(sep).join("/"));
+  }
+  return out;
+}
+
+/** Hash every shipped file except the manifest itself and package.json, which npm normalizes on publish. */
+export async function writeManifest(packageRoot = ownRoot, files?: string[]) {
+  const pkg = await Bun.file(join(packageRoot, "package.json")).json() as { version: string };
+  const list = (files ?? await filesBelow(packageRoot)).filter(file => file !== MANIFEST && file !== "package.json").sort();
+  const hashes = Object.fromEntries(await Promise.all(list.map(async file => [file, sha256(await Bun.file(join(packageRoot, file)).bytes())])));
+  await writeFile(join(packageRoot, MANIFEST), JSON.stringify({ version: pkg.version, files: hashes }, null, 2) + "\n");
+  return list.length;
+}
+
+/** The installed package's files match the manifest published with it. Skipped when running from a source checkout. */
+export async function checkInstalledPackage(packageRoot = ownRoot): Promise<IntegrityFinding[]> {
+  if (!packageRoot.split(sep).includes("node_modules")) return [];
+  const where = (file: string) => `node_modules/${PACKAGE}/${file}`, restore = "bun install --force";
+  if (!existsSync(join(packageRoot, MANIFEST))) return [{ file: where(MANIFEST), detail: `the installed package has no ${MANIFEST}; it was not installed from the npm registry`, restore }];
+  const manifest = await Bun.file(join(packageRoot, MANIFEST)).json() as { version: string; files: Record<string, string> };
+  const findings: IntegrityFinding[] = [];
+  const version = (await Bun.file(join(packageRoot, "package.json")).json() as { version: string }).version;
+  if (version !== manifest.version) findings.push({ file: where("package.json"), detail: `installed version ${version} does not match the published manifest ${manifest.version}`, restore });
+  for (const [file, hash] of Object.entries(manifest.files)) {
+    const path = join(packageRoot, file);
+    if (!existsSync(path)) findings.push({ file: where(file), detail: "was deleted from the installed package", restore });
+    else if (sha256(await Bun.file(path).bytes()) !== hash) findings.push({ file: where(file), detail: `differs from the published ${manifest.version} package`, restore });
+  }
+  for (const file of await filesBelow(packageRoot)) if (file !== MANIFEST && file !== "package.json" && !(file in manifest.files)) findings.push({ file: where(file), detail: "was added to the installed package", restore });
+  return findings;
+}
+
+/** The repository installs the package from npm, pinned by a registry integrity hash. */
+async function checkDependency(root: string): Promise<IntegrityFinding[]> {
+  if (!existsSync(join(root, "package.json"))) return [];
+  const pkg = await Bun.file(join(root, "package.json")).json() as { name?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  if (pkg.name === PACKAGE) return [];
+  const spec = pkg.devDependencies?.[PACKAGE] ?? pkg.dependencies?.[PACKAGE];
+  if (spec === undefined) return [{ file: "package.json", detail: `${PACKAGE} is not a dependency`, restore: `bun add -d ${PACKAGE}` }];
+  const findings: IntegrityFinding[] = [];
+  if (!/^[~^]?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(spec)) findings.push({ file: "package.json", detail: `${PACKAGE} is "${spec}"; it must be an npm version range, not a git, file, or link source`, restore: `bun add -d ${PACKAGE}` });
+  const lock = existsSync(join(root, "bun.lock")) ? await readFile(join(root, "bun.lock"), "utf8") : "";
+  const entry = lock.split("\n").find(line => line.trimStart().startsWith(`"${PACKAGE}": [`));
+  if (!entry) findings.push({ file: "bun.lock", detail: `bun.lock does not pin ${PACKAGE}`, restore: "bun install" });
+  else if (!/"@afokapu\/atdd-bun@\d+\.\d+\.\d+[^"]*", ""/.test(entry) || !entry.includes('"sha512-')) findings.push({ file: "bun.lock", detail: `bun.lock does not resolve ${PACKAGE} from the npm registry with an integrity hash`, restore: `bun add -d ${PACKAGE}` });
+  return findings;
+}
+
+/** Generated files are byte-identical to what the installed version generates (ignoring its version stamp). */
+async function checkGenerated(root: string, packageRoot: string): Promise<IntegrityFinding[]> {
+  const findings: IntegrityFinding[] = [];
+  const same = async (file: string, template: string, restore: string) => {
+    const path = join(root, file);
+    if (!existsSync(path)) return findings.push({ file, detail: "is missing", restore });
+    if (unstamp(await readFile(path, "utf8")) !== unstamp(await readFile(join(packageRoot, template), "utf8"))) findings.push({ file, detail: "was edited; it must match what the package generates", restore });
+  };
+  await same(WORKFLOW, "templates/github/atdd-bun.yml", "bun run atdd-bun ci init --replace");
+  for (const skill of SKILLS) await same(skill, "templates/agents/atdd/SKILL.md", "bun run atdd-bun agent init --replace");
+  await same(relative(root, await testFilePath(root)), "templates/agents/atdd-bun.integrity.test.ts", "bun run atdd-bun integrity init --replace");
+  const agents = existsSync(join(root, "AGENTS.md")) ? await readFile(join(root, "AGENTS.md"), "utf8") : "";
+  const block = agents.match(BLOCK)?.[0], canonical = (await readFile(join(packageRoot, "templates/agents/AGENTS.block.md"), "utf8")).match(BLOCK)![0];
+  if (!block) findings.push({ file: "AGENTS.md", detail: "is missing the atdd-bun block", restore: "bun run atdd-bun agent init --replace" });
+  else if (unstamp(block) !== unstamp(canonical)) findings.push({ file: "AGENTS.md", detail: "atdd-bun block was edited", restore: "bun run atdd-bun agent init --replace" });
+  return findings;
+}
+
+/** Names of the policy fields in `current` that are looser than in `base`. */
+export function loosenedPolicy(base: Partial<HookPolicy>, current: Partial<HookPolicy>): string[] {
+  const b = { ...defaultHookPolicy, ...base, worktrees: { ...defaultHookPolicy.worktrees, ...base.worktrees } }, c = { ...defaultHookPolicy, ...current, worktrees: { ...defaultHookPolicy.worktrees, ...current.worktrees } };
+  const out: string[] = [];
+  for (const key of ["max_staged_files", "max_staged_changed_lines", "max_uncommitted_files", "max_commits_per_push", "max_registry_removed_lines"] as const) if (Number(c[key]) > Number(b[key])) out.push(`${key} ${b[key]} → ${c[key]}`);
+  for (const key of ["require_plan_reference", "require_traceability"] as const) if (b[key] && !c[key]) out.push(`${key} true → false`);
+  for (const key of ["enabled", "require_linked_worktree"] as const) if (b.worktrees[key] && !c.worktrees[key]) out.push(`worktrees.${key} true → false`);
+  const removed = b.protected_branches.filter(x => !c.protected_branches.includes(x)), added = c.registry_paths.filter(x => !b.registry_paths.includes(x));
+  if (removed.length) out.push(`protected_branches drops ${removed.join(", ")}`);
+  if (added.length) out.push(`registry_paths adds ${added.join(", ")}`);
+  return out;
+}
+
+/** atdd-bun.yaml is not looser than on the branch being merged into. */
+async function checkPolicy(root: string, base?: string, push = process.env.GITHUB_EVENT_NAME === "push"): Promise<IntegrityFinding[]> {
+  const ref = base ?? process.env.ATDD_BASE_REF ?? (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : "origin/HEAD");
+  if ((await git(root, ["rev-parse", "--verify", "--quiet", ref])).code) return [];
+  let against = (await git(root, ["merge-base", "HEAD", ref])).out;
+  // A CI push to the base branch has nothing to merge into: judge the pushed commit against its parent.
+  if (push && against === (await git(root, ["rev-parse", "HEAD"])).out) against = (await git(root, ["rev-parse", "--verify", "--quiet", "HEAD~1"])).out;
+  if (!against) return [];
+  const read = async (text: string | null) => (text ? Bun.YAML.parse(text) ?? {} : {}) as Partial<HookPolicy>;
+  const before = await git(root, ["show", `${against}:atdd-bun.yaml`]), path = join(root, "atdd-bun.yaml");
+  const loosened = loosenedPolicy(await read(before.code ? null : before.out), await read(existsSync(path) ? await readFile(path, "utf8") : null));
+  return loosened.length ? [{ file: "atdd-bun.yaml", detail: `loosens the policy of ${against.slice(0, 7)}: ${loosened.join("; ")}`, restore: `git checkout ${against.slice(0, 7)} -- atdd-bun.yaml` }] : [];
+}
+
+export async function checkIntegrity(options: IntegrityOptions = {}): Promise<IntegrityFinding[]> {
+  const root = resolve(options.root ?? process.cwd()), packageRoot = options.packageRoot ?? ownRoot;
+  return [...await checkInstalledPackage(packageRoot), ...await checkDependency(root), ...await checkGenerated(root, packageRoot), ...await checkPolicy(root, options.base, options.push)];
+}
+
+/** The message both the local test and CI print: addressed to the agent, with the way back for every file. */
+export function formatIntegrity(findings: IntegrityFinding[]): string {
+  return [
+    "",
+    "⛔ ATDD INTEGRITY VIOLATION: protected files were changed.",
+    "",
+    `These files are owned by ${PACKAGE}. You are not allowed to edit them, weaken them,`,
+    "or work around this check. Changing them means you are not following this repository's limits.",
+    "",
+    ...findings.flatMap(f => [`  ✗ ${f.file}: ${f.detail}`, `      restore: ${f.restore}`]),
+    "",
+    "Put every file above back to its canonical state before doing anything else.",
+    "If a change here is genuinely needed, stop and ask the human. It belongs in the",
+    `${PACKAGE} package or in a separate change the human approves, never in this one.`,
+    "CI runs this same check on a clean install, so reverting only locally will not pass.",
+    "",
+  ].join("\n");
+}
+
+/** Write the generated integrity test into a repository. */
+export async function integrityInit(repo = process.cwd(), replace = false) {
+  const output = await testFilePath(repo);
+  if (existsSync(output) && !replace) return { ok: false, message: `${output} exists; use --replace` };
+  const version = (await Bun.file(join(ownRoot, "package.json")).json() as { version: string }).version;
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, (await readFile(join(ownRoot, "templates/agents/atdd-bun.integrity.test.ts"), "utf8")).replace("{{VERSION}}", version));
+  return { ok: true, message: output };
+}
+export async function integrityStatus(repo = process.cwd()) { const output = await testFilePath(repo); return { ok: existsSync(output), message: output }; }

package/src/register.ts

@@ -1,8 +1,17 @@
 import { expect, test } from "bun:test";
 import { enforce, type EnforcementConfig } from "./enforce";
+import { checkIntegrity, formatIntegrity, type IntegrityOptions } from "./integrity";
 
 export function registerEnforcementTest(config: EnforcementConfig = {}): void {
   test("ATDD Bun enforcement", async () => {
     expect(await enforce(config)).toEqual([]);
   });
 }
+
+/** A test that fails loudly, with the way back, when protected atdd-bun files were changed. */
+export function registerIntegrityTest(options: IntegrityOptions = {}): void {
+  test("ATDD integrity: atdd-bun and its generated files are canonical", async () => {
+    const findings = await checkIntegrity(options);
+    if (findings.length) throw new Error(formatIntegrity(findings));
+  });
+}

package/src/setup.ts

@@ -1,8 +1,9 @@
 import { ciInit, ciStatus } from "./ci";
 import { hooksStatus, installHooks } from "./hooks";
 import { agentInit, agentStatus } from "./agent";
+import { integrityInit, integrityStatus } from "./integrity";
 
-/** Install the package's three opt-in local surfaces without touching unrelated
+/** Install the package's opt-in local surfaces without touching unrelated
  * workflows or hook paths. Dependency installation itself never calls this. */
 export async function initializeRepository(root = process.cwd(), replace = false) {
   const existingHooks = await hooksStatus(root);
@@ -16,5 +17,9 @@ export async function initializeRepository(root = process.cwd(), replace = false
   const existingAgent = await agentStatus(root);
   const agent = replace || !existingAgent.ok ? await agentInit(root, replace) : existingAgent;
   if (!agent.ok) return { ok: false, message: `agent skill: ${agent.message}` };
-  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent skill: ${agent.message}` };
+
+  const existingIntegrity = await integrityStatus(root);
+  const integrity = replace || !existingIntegrity.ok ? await integrityInit(root, replace) : existingIntegrity;
+  if (!integrity.ok) return { ok: false, message: `integrity test: ${integrity.message}` };
+  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent skill: ${agent.message}\nintegrity test: ${integrity.message}` };
 }

package/templates/agents/AGENTS.block.md

@@ -1,5 +1,5 @@
 <!-- atdd-bun:start — generated by @afokapu/atdd-bun {{VERSION}}; run `atdd-bun agent init --replace` to refresh -->
 ## ATDD lifecycle
 
-Before changing code, tests, or `plan/`, follow `.agents/skills/atdd/SKILL.md`: PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, passing each stage's `atdd-bun` gate before starting the next.
+Before changing code, tests, or `plan/`, follow `.agents/skills/atdd/SKILL.md`: PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, passing each stage's `atdd-bun` gate before starting the next. Never edit `node_modules/@afokapu/atdd-bun` or atdd-bun's generated files, and never loosen `atdd-bun.yaml`; the integrity test and CI fail if you do.
 <!-- atdd-bun:end -->

package/templates/agents/atdd/SKILL.md

@@ -14,3 +14,5 @@ Conventions live in `node_modules/@afokapu/atdd-bun/` (`planner-nodes/nodes/`, `
 6. TRACE — Every acceptance has a test, every test resolves to a declared acceptance, every source file resolves to its tests. Gate: `bun run atdd-bun traceability`, then `bun run atdd-bun all`.
 
 When a gate fails, open `<rule_id>.convention.yaml` for the reported rule ID and fix the artifact. Never skip, suppress, or edit a convention to get green.
+
+Never edit `node_modules/@afokapu/atdd-bun`, the files atdd-bun generates (this skill, `AGENTS.md` block, `.github/workflows/atdd-bun.yml`, `atdd-bun.integrity.test.ts`), or loosen `atdd-bun.yaml`. `atdd-bun.integrity.test.ts` fails if you do, and CI repeats the check on a clean install. If one of them needs to change, stop and ask the human.

package/templates/agents/atdd-bun.integrity.test.ts

@@ -0,0 +1,5 @@
+// Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun integrity init --replace`.
+// Fails loudly when the installed package, its generated files, or atdd-bun.yaml were changed.
+import { registerIntegrityTest } from "@afokapu/atdd-bun/register";
+
+registerIntegrityTest();

package/templates/github/atdd-bun.yml

@@ -14,6 +14,7 @@ jobs:
         with: { fetch-depth: 0 }
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
+      - run: bun run atdd-bun integrity
       - run: bun run atdd-bun all
       - run: bun test
       - run: bun run atdd-bun release check