| name | pre-commit |
| description | Run the mandatory pre-commit checks for the poku repository before staging a commit. Use this whenever the user asks to commit, prepare a commit, push, open a PR, or verify a change is ready. Runs typecheck, lint:fix, build, and the local test suite in order, plus runtime-sensitive suites when the change touches runtime detection, isolation, child-process spawning, environment-variable plumbing, or any Bun or Deno specific code path. |
| user-invocable | true |
Pre-commit
Guarantee that every commit lands with passing type checks, formatted code, a successful build, and a green local test suite, so no regression in correctness, style, or distributable output reaches the upstream history.
Preconditions
- On a fork, read CONTRIBUTING.md first.
- Working tree reflects the change under review (no unrelated edits staged).
Recommended steps
Run in this exact order. Any non-zero exit blocks the commit.
npm run typecheck: TypeScript type check across the project.npm run lint:fix: auto-fixes Biome and Prettier. May modify files, which must be restaged.npm run build: produces lib/ from src/.npm test: full local Node.js suite.
Runtime-sensitive checks (conditional)
Run additionally when the change touches runtime detection, isolation, child-process spawning, environment-variable plumbing, or any Bun or Deno specific code path.
bun run test:bun: full local Bun suite.deno task test:deno: full local Deno suite.
Running a subset
Direct execution of a single test file:
npx tsx <path> or npx tsx src/bin/index.ts <path>bun --bun <path> or bun --bun src/bin/index.ts <path>deno run -A <path> or deno run -A src/bin/index.ts --denoAllow=all <path>
Filter the suite by path:
npm test -- --filter=<path>bun run test:bun -- --filter=<path>deno task test:deno -- --filter=<path>
Acceptance criteria
- All four mandatory steps exit with code 0.
- Runtime-sensitive suites exit 0 when applicable.
- Any files rewritten by
lint:fix are restaged before commit, so no unstaged formatting deltas remain.
Failure modes
typecheck fails: fix the type error at its source. Do not relax tsconfig or add any to silence it.lint:fix rewrites files: restage them and re-run from step 1. If a rule needs to be disabled, justify it in code review, not by skipping the step.build fails: fix the underlying TypeScript or bundler error. The build catches issues npm test does not.npm test fails: fix the test or the code under test. Never bypass with --no-verify or by skipping the test. Treat a modified existing test as a possible regression and prefer adding new tests.- Runtime-sensitive suite fails: reproduce locally with the failing runtime before pushing. A Node-only green run does not clear a runtime-sensitive change.
