Keep the lockfile version in step with releases

CLAUDE.md

@@ -11,4 +11,5 @@ Public JS SDK for embedding and controlling Felt maps. Two entry points: `client
 ## Key constraints
 
 - Every change needs a changeset (`npm run changeset`).
+- Never edit `version` in `package.json` by hand; the release flow (`changeset version`) owns it and syncs `package-lock.json`. If `npm run check:lockfile` fails, run `npm install --package-lock-only`.
 - See `DEVELOPING.md` for module structure and `RELEASING.md` for the branching/release model.

package.json

@@ -68,10 +68,11 @@
     "check:client-bundle": "npm run build:compile && node ./scripts/check-client-bundle-contents.js",
     "check:docs": "npm run build:docs && bash ./scripts/check-api-docs.sh",
     "check:format": "prettier --check .",
+    "check:lockfile": "node ./scripts/check-lockfile.mjs",
     "check:test": "vitest run",
     "check:types": "tsc",
     "check:unused": "knip",
-    "check": "npm run check:client-bundle && npm run check:format && npm run check:api && npm run check:unused && npm run check:types && npm run check:test && npm run check:docs",
+    "check": "npm run check:lockfile && npm run check:client-bundle && npm run check:format && npm run check:api && npm run check:unused && npm run check:types && npm run check:test && npm run check:docs",
     "format:write": "prettier --write .",
     "ci": "npm run build && npm run check",
     "enter-prerelease": "git checkout prerelease && git pull && changeset pre enter next",

scripts/check-lockfile.mjs

@@ -0,0 +1,20 @@
+// `changeset version` bumps package.json but not package-lock.json, which
+// carries its own copy of the root version. The release script syncs the two;
+// this check catches any other path that lets them drift.
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+const lock = JSON.parse(readFileSync("package-lock.json", "utf8"));
+
+const lockVersions = [lock.version, lock.packages?.[""]?.version];
+const mismatched = lockVersions.filter((v) => v !== pkg.version);
+
+if (mismatched.length) {
+  console.error(
+    `Error: package-lock.json is at ${mismatched[0]} but package.json is at ${pkg.version}.`,
+  );
+  console.error("Run: npm install --package-lock-only");
+  process.exit(1);
+}
+
+console.log(`package-lock.json matches package.json (${pkg.version}).`);

scripts/local-release.sh

@@ -34,17 +34,22 @@ fi
 echo "Running CI checks..."
 npm run ci
 
-# Version the changesets
+# Version the changesets (this commits the package.json bump itself)
 echo "Versioning changesets..."
 npx changeset version
 
+# Changesets does not touch package-lock.json, so bring its version into line
+echo "Syncing package-lock.json..."
+npm install --package-lock-only --ignore-scripts --no-audit --no-fund
+
 # Build docs again to include changelog
 echo "Building docs..."
 npm run build:docs
 
-# Check for changes in docs and pre.json
-ALLOWED_CHANGES=$(git diff --name-only | grep -E "^docs/|^\.changeset/pre\.json$" || true)
-DISALLOWED_CHANGES=$(git diff --name-only | grep -vE "^docs/|^\.changeset/pre\.json$" || true)
+# Check for changes in docs, pre.json and the lockfile
+ALLOWED_PATTERN="^docs/|^\.changeset/pre\.json$|^package-lock\.json$"
+ALLOWED_CHANGES=$(git diff --name-only | grep -E "$ALLOWED_PATTERN" || true)
+DISALLOWED_CHANGES=$(git diff --name-only | grep -vE "$ALLOWED_PATTERN" || true)
 
 if [ -n "$DISALLOWED_CHANGES" ]; then
     echo "Error: Unexpected changes detected in files:"
@@ -53,8 +58,8 @@ if [ -n "$DISALLOWED_CHANGES" ]; then
 fi
 
 if [ -n "$ALLOWED_CHANGES" ]; then
-    echo "Committing documentation and pre.json updates..."
-    git add docs/ .changeset/pre.json
+    echo "Committing documentation, lockfile and pre.json updates..."
+    git add docs/ .changeset/pre.json package-lock.json
     git commit -m "Update prerelease docs/meta"
 fi