|
| 1 | +--- |
| 2 | +name: playwright-audit-deps |
| 3 | +description: Roll the runtime dependencies that npm audit flags with a moderate or higher advisory to safe versions that are at least 8 days old, and commit them with a table of every package the lock file change touched (old and new version, publish date, weekly downloads). Use when asked to fix audit findings, bump vulnerable or outdated runtime dependencies, or update package-lock.json for an advisory. |
| 4 | +user_invocable: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Roll runtime dependencies flagged by npm audit |
| 8 | + |
| 9 | +`/playwright-audit-deps [issue url]` |
| 10 | + |
| 11 | +A runtime dependency is a package whose code ends up in a published Playwright package: it is |
| 12 | +inlined into a bundle (listed in a `packages/*/lib/**/*.js.txt` sidecar) or named in the |
| 13 | +`dependencies` of a `packages/*/package.json`. Advisories on dev-only packages, such as eslint |
| 14 | +plugins or chromium-bidi, are reported as skipped and left alone. |
| 15 | + |
| 16 | +A version is eligible when it is outside every advisory range, was published at least 8 days |
| 17 | +ago, and is accepted by every runtime dependent in `package-lock.json`. The newest eligible |
| 18 | +version wins. Packages that `npm install` pulls in beyond that age are pinned back the same way. |
| 19 | + |
| 20 | +## Steps |
| 21 | + |
| 22 | +1. Start from a clean checkout of `main` with `npm run build` done, so the bundle sidecars |
| 23 | + exist. Create the branch: `fix-<issue number>` when an issue is given, else `bump-runtime-deps`. |
| 24 | + |
| 25 | +2. Plan: `node .claude/skills/playwright-audit-deps/audit-deps.mjs`. It prints, per runtime |
| 26 | + advisory, the version it would roll to, or why it cannot (no fixed version, fixed version too |
| 27 | + new, a runtime dependent rejects it, or a major bump of a package pinned in `package.json`). |
| 28 | + |
| 29 | +3. Apply: `node .claude/skills/playwright-audit-deps/audit-deps.mjs --apply --report=<scratchpad>/deps-report.md`. |
| 30 | + Pass `--allow-major` only when the user asked for a major bump; otherwise leave those |
| 31 | + packages in the "Not rolled" list and tell the user. Options: `--max-age-days=N` (default 8), |
| 32 | + `--severity=low|moderate|high|critical` (default moderate), `--base=<ref>` for the report diff. |
| 33 | + |
| 34 | +4. Verify: `npm run build`, then `npm run itest tests/installation/bundle-licenses.spec.ts tests/installation/bundle-size.spec.ts`. |
| 35 | + A new dependency without a `repository` field, or a bigger bundle, fails here. Fix the cause |
| 36 | + or drop that roll, then rerun the report. |
| 37 | + |
| 38 | +5. Commit `package.json` and `package-lock.json` as one commit: |
| 39 | + |
| 40 | + ``` |
| 41 | + chore(deps): bump runtime deps |
| 42 | +
|
| 43 | + <the markdown table and the "Not rolled" list from the report> |
| 44 | +
|
| 45 | + Fixes: <issue url, when given> |
| 46 | + ``` |
| 47 | + |
| 48 | +6. Report the table and the not-rolled packages to the user. **Never push.** When told to open |
| 49 | + the PR, use the same title and a body of one bullet naming the packages rolled for an |
| 50 | + advisory, the table, and the `Fixes` line. |
| 51 | + |
| 52 | +## Notes |
| 53 | + |
| 54 | +- `npm audit` lists a package that only depends on a vulnerable one (chromium-bidi via zod) |
| 55 | + as its own finding; the script follows the actual advisory, so such entries are not acted on. |
| 56 | +- A root-pinned package is bumped with `npm install <name>@<version> --save-exact`. Any other |
| 57 | + package is rewritten in place in `package-lock.json` and reconciled with `npm install`. The |
| 58 | + script fails if `npm ls` reports a problem afterwards. |
| 59 | +- Run the apply step once from the clean base; a second run labels the already rolled packages |
| 60 | + as plain dependencies in the "Reason" column, because the audit no longer flags them. |
0 commit comments