AGENTS.md

1# scripts/ - Root Node Helpers
2 
3## OVERVIEW
4 
5Small Node ESM helpers that are intentionally separate from the primary Bun/TypeScript automation in singular `script/`.
6 
7## WHERE TO LOOK
8 
9| File | Purpose |
10|------|---------|
11| `check-third-party-notices.mjs` | Validate third-party notice coverage for source and shipped payloads; `parseNpmPackJson` normalizes npm 11 (array) and npm 12 (keyed object) `npm pack --dry-run --json` manifests |
12| `third-party-notice-requirements.mjs` | Declarative notice requirements and path/package matching |
13| `check-third-party-notices.test.mjs` | Node test coverage for spawn invocation resolution (Windows/non-Windows) and `parseNpmPackJson` (npm 11 array, npm 12 keyed, malformed and ambiguous rejection) |
14 
15## COMMANDS
16 
17```bash
18node --test scripts/check-third-party-notices.test.mjs
19node scripts/check-third-party-notices.mjs
20node scripts/check-third-party-notices.mjs --ship
21```
22 
23`bun run test:codex` invokes the `--ship` check after building the Codex payload. Release workflows also rely on this surface before publication.
24 
25The checker test covers spawn invocation resolution (Windows/non-Windows) and `parseNpmPackJson` manifest parsing (npm 11/12 formats, malformed and ambiguous payloads); it does not cover notice discovery or failure cases. The default checker command is not a claim that the checker currently passes.
26 
27## CONVENTIONS
28 
29- Keep these files plain Node ESM; they run in packaging and compatibility flows that should not depend on Bun APIs.
30- Put general build, release, QA, and repository-invariant automation in `script/`, not here.
31- Add notice requirements declaratively in `third-party-notice-requirements.mjs`; keep traversal and reporting in the checker.
32- Error output must identify the missing requirement or unexpected shipped path without exposing credentials or environment dumps.
33 
34## ANTI-PATTERNS
35 
36- Do not move these helpers into `script/` without updating package scripts, CI, and published-path assumptions.
37- Do not skip the `--ship` mode when changing the Codex or npm payload.
38- Do not duplicate third-party package rules inside tests; test the exported requirement table.
39