Sidequest: The Lockfile That Only One npm Would Accept

Cold open

The bug was a lockfile that one version of npm accepted and another refused. Nothing was broken in what the dashboard runs. The trouble was the lockfile's description of the dependency tree: one package was sitting on the wrong shelf for a stricter reader.

How it came up

You asked the session to do two things: put a batch of Codex work in the burn file, and fix item 3, the lockfile. The second report said "only picomatch moved, the same two versions, re-arranged in the tree, nothing upgraded". It also said the fix now passes on your Mac's npm and on the npm used by the image build, and that it is waiting on a branch for your go.

The todo item behind it dates from the 17th of October. On your Mac, a strict install refused the lockfile and complained that "picomatch 2.3.2 does not satisfy picomatch 4.0.7". On the server, the image build used a newer npm that installed the same file without complaint. So deploys worked and local installs failed. That is the kind of bug that sits in a todo list for a week, because nothing is on fire.

The mental model

Start with what picomatch is. It is a tiny library that answers one question: does this file path match this pattern, something like "every test file in this folder". You never chose it. It is a dependency of your dependencies. Vite, Vitest and a few file-watching tools each pull it in.

They do not agree on which version they want. The older tools want picomatch 2. The newer ones want picomatch 4. npm handles that fine, because two versions can live side by side.

Think of node_modules as a library with one main shelf and lots of private shelves. Each package name gets one copy on the main shelf, and everyone who does not need something special takes that copy. A package that needs a different version gets its own copy on a private shelf next to it. In your lockfile, picomatch 2.3.2 was on the main shelf, and Vite, Vitest and a helper called tinyglobby each had their own copy of version 4 on private shelves.

The trouble was a fourth package called fdir, which walks directories quickly. fdir says: "I do not strictly need picomatch, but if one is around, it must be version 3 or 4." In npm's terms that is an optional peer dependency. fdir sits on the main shelf, so the picomatch it sees is the one on the main shelf, and that was version 2.

The two npm versions disagree about how much that matters. The 11.16 used in the image build treats an optional peer that does not match as something to let slide. The 11.6.1 on your Mac reads it as a broken promise in the lockfile, and it refuses.

The refusal is the whole point of the command involved. There are two ways to install. Plain npm install is the helpful one. It reads your wishes, looks at the lockfile, quietly repairs anything that does not fit, and rewrites the lockfile. npm ci, "clean install", is the strict one. It treats the lockfile as a contract, installs exactly what is written, and if the contract is inconsistent it stops instead of improvising. Builds and servers use the strict one on purpose: you want the image built from exactly what you tested, not from whatever npm felt like that afternoon.

So the fix was to let the helpful install reorganise the shelves once, write the result down, and confirm the strict install now accepts it on both npm versions. I have not seen the new tree, so the exact arrangement is my guess. Most likely the main shelf now gives fdir a version 4 to see, and the version 2 users get their copy on a private shelf. The library has the same two books on different shelves. Nothing was upgraded, and no new code arrived. That is why the session stressed "same two versions": a lockfile change that silently bumps forty packages is a much bigger review than one that moves furniture.

Why it waits for you, and why it does not need a deploy

This is a vital repo, and a dependency file counts as code even when it changes nothing at runtime. So the fix sits on a branch until you say "push the lockfile".

No deploy is needed because picomatch only matters while building and testing. It is a dev dependency and never reaches a visitor's browser. The live site was built with the npm that already accepted the old file. The next ordinary deploy will pick up the tidier version without anyone noticing, which is exactly what you want from a lockfile.

The comedy here is that the newer npm is the more relaxed one. Usually software gets stricter with age. This time the old version at home was the one checking ID at the door, while the server's newer version waved everyone through.

Where else this lives

The same contract idea sits behind your Python projects. The uv lock file, committed next to every pyproject, is the Python version of the same thing: the exact list, written down, so a fresh machine rebuilds the same world. The Containerfile in this repo leans on that strictness too. When the image's frontend stage installs, it uses npm ci, so a lockfile the build npm rejects would stop a deploy cold. This one just happened to pass the npm that mattered.

Close

If you remember one thing: a lockfile is a contract, npm ci enforces it to the letter, and this fix rearranged the contract so even the pickier npm reads it as valid, without changing a single version.