bump-npm-deps
Skill32 starsChanged 29 days agoMITView on GitHub
Bump npm dependencies across this repo's five package.json files (root, backend, frontend, services/monitoring, services/supermemory): apply SAFE (minor/patch) updates first, then take each MAJOR one at a time by reading its changelog and migration guide and grepping our usage, and end with a four-section report. Use when the user says "bump deps", "update npm dependencies", "run the dependency bump", or "/bump-npm-deps" — not for Docker image pins.
- Installs packages
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- create-github-issueSkill
- create-gitlab-taskSkill
- debug-production-runSkill
- sync-architectureSkill
- update-changelogSkill
- update-server-depsSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Follow the steps in order.
- Very specific: line 25
Commit subjects: subject only, no body, no AI-attribution footer, at most 50 characters.
- Distinctive: line 51
Write out both lists before doing anything else.
- Very specific: line 84
If a build fails, STOP: git checkout -- <file> that package.json/lockfile and report which SAFE package broke it.
- Very specific: line 87
If everything passes, commit now (chore: bump SAFE dependencies) so later reverts can't undo it.
- Distinctive: line 96
Never just rename the patch file to the new version.
- Very specific: line 100
If it needs changes, apply the old patch to a pristine copy of the new version, fix it, and regenerate with npx patch-package …
- Very specific: line 102
Run an abort-path check from backend/ — a misscoped patch throws ReferenceError here and nothing else catches it:
- Very specific: line 124
Update just that package, in the package.json it lives in: npx npm-check-updates -u -f <package-name> then npm install.
- Distinctive: line 126
Read what changed. All of it:
- Very specific: line 133
No changelog or no such link: npm view <package-name> repository.url and look up the releases page for the versions in between (the tag may …
- Distinctive: line 192
Don't push or open a PR unless asked.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Follow the steps in order; don't batch packages where a step says one at a time. A passing build is NOT evidence an upgrade is safe: deprecated APIs still compile, and changed defaults or rejected options only fail at runtime.
0. Before you start
- Branch off
mainaschore/bump-dependencies(branch rules in.claude/CLAUDE.md). - Never
git add -A— a working tree can hold untracked files that must not be committed. Stage by name: thepackage.jsonandpackage-lock.jsonfiles,backend/patches/, and any code you fixed. - Versions are exact pins (
save-exact=true), soWantedequalsCurrentinnpm outdated; classify byLatest. - Commit subjects: subject only, no body, no AI-attribution footer, at most 50
characters. Count it — long package names don't fit
chore: bump <pkg> to <ver>, so drop the version or shorten.
1. List outdated packages
npm outdated
npm --prefix backend outdated
npm --prefix frontend outdated
npm --prefix services/monitoring outdated
npm --prefix services/supermemory outdatedClassify every row:
- SAFE —
WantedandLatestmatch, or only the minor/patch number changes. - MAJOR — the first number changes. Any
0.xbump is MAJOR (pre-1.0 doesn't follow semver).
Exception: @types/node stays on the Node major in that location's Dockerfile
(node:22-slim today). A jump past it is MAJOR with nothing to read — it's types
only and has no changelog — so put it under "Needs manual action". The supermemory
server is pinned in services/supermemory/Dockerfile, not package.json, so it
never appears here; don't bump it.
Write out both lists before doing anything else.
2. Apply all SAFE updates
For each location, with only that location's SAFE names after -f (never run it
without -f; -t minor would also bump 0.x packages from the MAJOR bucket):
npx npm-check-updates -u -t minor -f "<comma-separated SAFE names>"
npm installFor services/monitoring and services/supermemory use
npx npm-check-updates --cwd <dir> ... and npm --prefix <dir> install — root's
postinstall only installs backend and frontend.
Then check nothing was left behind: re-run npx npm-check-updates -t minor
(no -u) in every location. Anything it still lists that isn't in your MAJOR bucket
was missed — apply it.
Builds:
npm --prefix backend run build
npm --prefix frontend run build
npm --prefix services/monitoring run build
./services/monitoring/node_modules/.bin/tsc --noEmit -p services/supermemoryservices/supermemory has no build script or TypeScript of its own; the last
command uses services/monitoring's. Skip a location's ncu/install if nothing
is SAFE there, but still build it.
If a build fails, STOP: git checkout -- <file> that package.json/lockfile and
report which SAFE package broke it. Don't debug further.
If everything passes, commit now (chore: bump SAFE dependencies) so later
reverts can't undo it.
Patched packages
backend/patches/*.patch (patch-package, applied by backend's postinstall)
carries local edits to @langchain/core. Whenever a bump touches a patched
package:
- Never just rename the patch file to the new version. Check it applies cleanly to the new source and that its hunks still make sense there. One carried-over patch passed builds across three bumps while three of its four call sites referenced a variable that was never in scope.
- If it needs changes, apply the old patch to a pristine copy of the new version,
fix it, and regenerate with
npx patch-package @langchain/core. - Run an abort-path check from
backend/— a misscoped patch throwsReferenceErrorhere and nothing else catches it:
node --input-type=module -e '
import { RunnableLambda } from "@langchain/core/runnables";
import { getEventListeners } from "node:events";
const r = RunnableLambda.from(async (x) => x);
const ac = new AbortController();
for (let i = 0; i < 20; i++) {
for await (const _ of r.streamEvents("a", { version: "v2", signal: ac.signal }));
for await (const _ of r.streamLog("a", { signal: ac.signal }));
}
console.log("abort listeners left:", getEventListeners(ac.signal, "abort").length);'It must finish without an error and print 0.
3. Handle MAJOR updates one package at a time
Repeat for each package in the MAJOR bucket:
- Update just that package, in the
package.jsonit lives in:npx npm-check-updates -u -f <package-name>thennpm install. - Read what changed. All of it:
node_modules/<package-name>/CHANGELOG.md(alsoCHANGES.md,HISTORY.md): read the entry for EVERY version after the old one up to the new one, in full.- Open every http(s) link in those entries and in the README's upgrade/migration
section with whatever web tool you have (a URL fetcher, or web search if that's
all you have) — links containing
migrat,upgrad,breaking,release,guideordocsfirst, but follow whatever the entry points to. - No changelog or no such link:
npm view <package-name> repository.urland look up the releases page for the versions in between (the tag may bev<ver>,<ver>, or<package-name>@<ver>). - A page or search that returns little or no useful text is NO evidence.
- List every API, option, default, import or behavior the entries say was removed,
renamed, deprecated, newly rejected or changed. For each, search the whole repo,
so config files (vite, eslint, tsconfig), scripts and Dockerfiles are covered:
grep -rn "<name>" . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=build --exclude-dir=dist --exclude=package-lock.json. Also grep every option our code passes into the package (options once accepted may now be rejected at runtime). For a changed default with no name to grep, read every call site. Compare the new version'senginesandpeerDependencies(npm view <package-name>@<new> engines peerDependencies) with the Node version in the workspace's Dockerfile and the other installed packages. Write each item and its result down. - Decide, on evidence only:
- No breaking change found — only if you read the full entries, followed their links, and the grep found no hits. Move on.
- Breaking, code-level (renamed import, changed signature, changed default, removed API) — fix every call site from the grep, then re-run it to confirm none remain.
- Breaking, needs something outside the code (DB migration, new required env var, infra/CI change, data backfill) — don't attempt it. Revert that package's bump and lockfile and list it under "Needs manual action" with the exact package, versions and manual step.
- Unsure, or no evidence either way (including an unreadable entry or guide) — revert the same way and list it under "Uncertain". Never pick "no breaking change" just because you found nothing.
- Build that workspace again (
services/supermemory: thetsc --noEmit -p services/supermemorycommand from step 2; a patched package: also the abort-path check). If it fails and the error alone doesn't tell you the fix, revert and list it under "Uncertain". If it passes, commit that package alone.
Finish one package, build check included, before starting the next. Never move on while the current one is broken.
4. Final report
Exactly these four sections, headings verbatim; every row from Step 1 appears in exactly one section:
### Updated successfully
- <package>: <old> → <new> (SAFE / MAJOR, code changes: yes/no) — for MAJOR: files read and URLs fetched, with one quoted line
### Needs manual action (not applied)
- <package>: <old> → <new> — <what manual step is required>
### Uncertain — needs human review (not applied)
- <package>: <old> → <new> — <why you couldn't confirm safety>
### Build/test status
- backend build: pass/fail
- frontend build: pass/fail
- monitoring build: pass/fail
- supermemory typecheck: pass/fail
- abort-path check (if a patched package changed): pass/fail
- any other test suites run and their resultDon't push or open a PR unless asked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

