Skip to content

docs(agents): require top-level dependency bumps over npm overrides - #1376

Open
anupamme wants to merge 1 commit into
cuttle-cards:mainfrom
anupamme:docs/dependency-fix-policy
Open

docs(agents): require top-level dependency bumps over npm overrides#1376
anupamme wants to merge 1 commit into
cuttle-cards:mainfrom
anupamme:docs/dependency-fix-policy

Conversation

@anupamme

Copy link
Copy Markdown

Follows up on the review discussion in #1367, where an automated CVE fix used a global overrides entry plus a hand-edited lockfile. The maintainer asked that future automated PRs against this repo prefer bumping the top-level dependency that owns the transitive package, and that lockfiles be produced by npm install. This writes that guidance into the Dependencies policy so agents pick it up from AGENTS.md instead of rediscovering it in review.

Three additions:

  • Transitive vulnerabilities — fix at the owning top-level dependency, not via overrides. In fix: upgrade minimist to 1.2.6, 0.2.4 (CVE-2021-44906) #1367 a global minimist pin patched the one vulnerable consumer (knex@0.12.7) and downgraded five that were already patched, including cypress, which declares ^1.2.8.
  • Lockfile — never hand-edit it. Worth stating explicitly because npm ci installs a hand-edited lockfile verbatim rather than rejecting it, so CI does not catch this class of mistake.
  • Verificationnpm ls <package> and npm audit after any dependency change, plus a note that neither npm run test:unit nor the Cypress e2e suite exercises Postgres (both run on sails-disk), so adapter changes need npm run docker:start to be validated.

Docs only; no code or dependency changes.

Validation: npm run lint passes. npm run test:unit fails locally, but for an unrelated environmental reason — all 14 failures trace to util.isDate is not a function in @sailshq/nedb, which Node removed in v23. This machine has Node v25.9.0 while .nvmrc pins 22.21, and the failures reproduce on unmodified main (this branch's only diff is the three AGENTS.md lines).

🤖 Generated with Claude Code

Adds three rules to the Dependencies policy, prompted by the discussion
on cuttle-cards#1367:

- Fix vulnerable transitive packages by bumping the dependency that owns
  them. A global `overrides` entry applies to every consumer in the tree,
  so it can downgrade packages already on a patched version.
- Never hand-edit `package-lock.json`. `npm ci` installs an edited
  lockfile verbatim instead of rejecting it, so CI won't catch it.
- Verify with `npm ls`/`npm audit`, and note that no CI job exercises
  Postgres, so adapter changes need the docker compose stack.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant