packkit upgrade — keep a scaffolded project current

[DanMat]

The headline both reviews independently landed on, and the reason 2.9 shipped the packkit.json provenance file. A scaffolded project now has a durable relationship with Packkit: it can be pulled up to the current templates instead of drifting.

npx create-packkit upgrade          # dry run — what changed since you scaffolded
npx create-packkit upgrade --apply  # add new files, bump deps, keep your edits
npx create-packkit upgrade --force  # also overwrite files that differ

How it works

Reads packkit.json (preset + settings) and the name from package.json, regenerates the current recommended output in memory through the embedded API, and diffs it against disk. Reconstruction is faithful — verified byte-for-byte across every preset type (ts-lib, node-service, react-app, oss, fullstack).

It classifies each difference:

• new files Packkit now generates,
• added / bumped dependencies (tracked per section),
• new / changed scripts,
• files that differ — a template change or the user's own edit. Without a stored baseline it can't tell which, so these are surfaced for review and never auto-overwritten.

--apply brings in the safe changes and merges package.json so bumps and new deps/scripts land while the user's own deps, scripts, and field ordering survive. packkit.json is refreshed. Differing files are left untouched unless --force.

Layering

The decision logic — planUpgrade, buildUpgradeWrite, isUpgradeEmpty — is a pure, exported part of the embedded API and is unit-tested. The CLI just reads disk and formats the report. Consistent with the architecture: the engine is shared, the CLI is an adapter.

Verified end to end

Scaffolded a project, then simulated drift — deleted .editorconfig, removed vitest, downgraded tsup to ^7, added a custom script, edited the README:

Packkit 2.0.0 → 3.0.0
New files (1): .editorconfig
New dependencies (1): vitest@^4.0.0 (devDependencies)
Dependency updates (1): tsup: ^7.0.0 → ^8.0.0
Files that differ — review before overwriting (1): README.md

--apply: file restored, dep re-added, tsup bumped, the custom script preserved, the edited README left alone; packkit.json refreshed to 3.0.0. --force then overwrites the README.

94 tests pass (5 new). No core change, so the web bundle is untouched.

Follow-up (roadmap): per-file baseline hashes in packkit.json would let it distinguish "user edited" from "template changed" precisely, instead of surfacing all differing files for review.

🤖 Generated with Claude Code