Chapter 1: The machine

package.json says what you would accept. Something else has to say what you actually got.

Lockfile

Also called package-lock.json, bun.lock

A file the package manager writes, recording the exact version of every dependency it installed and a fingerprint of its contents. It means everyone, and every automated run, installs the same code. Don't write it by hand, but do keep it in the project.

Without one, an unchanged project can install different code next week and break for no visible reason. Agents change it in passing, so look at what changed: a one-package request shouldn't rewrite most of the file. And make automated runs refuse a mismatch.

Say it to your agent

“Only bun.lock should change for this, and only for that one package. Show me the lockfile diff, commit it, and make CI run bun install --frozen-lockfile so a mismatch fails the build.”

The workshop

Name a word, or describe what you mean in everyday language.