From 4bf5a6b14fd1d02d946bf79cdbe19c83411d86bd Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 7 Apr 2026 19:31:29 +0000 Subject: [PATCH 1/3] fix: build + ship dist/index.js so custom policies can import from 'failproofai' + bump to 0.0.1-beta.11 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `findDistIndex()` always returned null for global installs because `dist/index.js` was never built or included in the published package. This caused the ESM shim to be skipped, leaving `from 'failproofai'` unrewritten in user custom policy temp files → "Cannot find package 'failproofai'" at runtime. Fixes: prepend a `bun build` CJS step to the build script so `dist/index.js` is produced before publish, and add `dist/` to the `files` array so it ships in the npm tarball. Verified: Docker clean-install (oven/bun image) confirms dist/index.js present and `failproofai p -i -c` succeeds end-to-end. Co-Authored-By: Claude Sonnet 4.6 --- package.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 3e843ef5..8e08969f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "failproofai", - "version": "0.0.1-beta.10", + "version": "0.0.1-beta.11", "description": "Open-source hooks, policies, and project visualization for Claude Code & Agents SDK", "bin": { "failproofai": "./bin/failproofai.mjs" @@ -11,6 +11,7 @@ "scripts/", "lib/", ".next/standalone/", + "dist/", "README.md" ], "engines": { @@ -20,7 +21,7 @@ "scripts": { "predev": "bun link", "dev": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/dev.ts --port 8020", - "build": "bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\"", + "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\"", "prestart": "bun link", "start": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/start.ts", "test": "vitest", From b86dd35bdaeb3d73996193ae0d995744889f3d84 Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Tue, 7 Apr 2026 19:36:00 +0000 Subject: [PATCH 2/3] docs: add CLAUDE.md and AGENTS.md with Docker testing + CI/PR workflow rules Documents the full agent workflow: Docker clean-install test recipe, regression checklist, one-PR-per-branch rule, CI-must-be-green rule, and unit-test requirements for new behaviour. Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 73 +++++++++++++++++++++++++++++++++ CLAUDE.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..d6d728ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,73 @@ +# AGENTS.md — Codex / agent guidance for this repo + +This file is read by AI coding agents (Codex, Claude Code, etc.). It duplicates the most +critical rules from CLAUDE.md in a format optimised for agent consumption. + +## Non-negotiable rules + +1. **One PR per branch.** Check `gh pr list --head ` before creating a PR. + Push to the existing PR if one already exists. + +2. **CI must be green before you stop.** After every push, poll `gh run list --limit 3` + until all checks complete. Fix failures before proceeding or declaring done. + +3. **Never edit a test to make it pass.** Fix the code. Tests may only be changed when the + test itself is wrong or when the feature under test was intentionally changed. + +4. **Always add unit tests for new behaviour.** Place tests in `__tests__/`. Unit tests live + in `__tests__/hooks/`, e2e tests in `__tests__/e2e/hooks/`. + +5. **Docker is available.** Use `oven/bun:latest` with `--network=host` to do clean-install + end-to-end testing after every non-trivial implementation. See CLAUDE.md for the exact + Docker test recipe. + +## Test commands + +```bash +bun run test:run # unit tests (fast, run first) +bun run test:e2e # end-to-end hook tests (slower, run before push) +bun run lint # eslint +bunx tsc --noEmit # type check +``` + +## Docker smoke test (run after every change to src/hooks/ or package.json) + +```bash +npm pack --ignore-scripts +docker run --rm --network=host \ + -v $(pwd)/failproofai-*.tgz:/pkg.tgz \ + oven/bun:latest bash -c " + apt-get update -qq && apt-get install -y -qq nodejs npm 2>&1 | tail -2 + npm install -g /pkg.tgz --ignore-scripts 2>&1 | tail -3 + cat > /tmp/tp.mjs << 'EOF' +import { customPolicies, allow } from 'failproofai'; +customPolicies.add({ name: 't', description: 't', match: { events: ['PreToolUse'] }, fn: async () => allow() }); +EOF + failproofai p -i -c /tmp/tp.mjs + " +rm failproofai-*.tgz +``` + +Expected: `Validated 1 custom hook(s): t`, exit 0. + +## Regression checklist + +Run through this mentally after any change to `src/hooks/` or `dist/` build: + +- [ ] ESM import (`from 'failproofai'`) in custom policy resolves +- [ ] CJS require (`require('failproofai')`) in custom policy resolves +- [ ] Transitive local imports inside custom policy file work +- [ ] Builtin policies run when no custom file is configured +- [ ] `failproofai p -i -c ` fails gracefully (no crash) +- [ ] `bun run test:run` — all unit tests pass +- [ ] `bun run test:e2e` — all e2e tests pass +- [ ] CI is green + +## Key files + +| File | Purpose | +|------|---------| +| `src/hooks/loader-utils.ts` | `findDistIndex()`, ESM shim, import rewriting | +| `src/hooks/custom-hooks-loader.ts` | Top-level custom hook loading orchestrator | +| `src/index.ts` | Public API → `dist/index.js` bundle entry | +| `package.json` | `files` must include `dist/`; `build` must build `dist/index.js` | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..4e0701d9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,120 @@ +# CLAUDE.md — Agent guidance for this repo + +## Environment + +- **Runtime:** bun (≥1.3.0) and Node.js (≥20.9.0) are both present. +- **Docker CLI** is available. Use it to spin up clean containers that mimic real user + installs and validate every non-trivial change end-to-end before pushing. +- **Package manager:** bun (`bun install`, `bun run