Scaffold upgrades
scaffoldVersion
src/magicms.project.json:
{ "scaffoldVersion": "1.3.0", "canUpgradeScaffold": true }MagiCMS reads this on every commit. If the project's version is behind the current scaffold, an "Upgrade available" badge appears in the sidebar.
Migration manifests
A migration is a JSON file at packages/ui/src/scaffold/migrations/<version>.json. Each manifest describes:
- Which files to add (source scaffold → destination project).
- Which files to delete (when a schema is removed).
- Which files to mark as dirty (existing user content that may need attention).
The first migration is 1.2.0 → 1.3.0. The destination is a project pinned at 1.2.0.
CLI tool
node packages/ui/scripts/upgrade-scaffold.mjs /path/to/project # dry-run stepwise
node packages/ui/scripts/upgrade-scaffold.mjs /path/to/project --apply
node packages/ui/scripts/upgrade-scaffold.mjs /path/to/project --hard-update --apply # full technical syncDefault dry-run. Flags: --apply, --force, --hard-update.
Auto-upgrade flow
When MagiCMS detects an outdated scaffold, the user sees a "Scaffold 1.3.0 is available" badge. Clicking it opens the upgrade panel with a diff and a one-click "Apply".