CMS Regeneration

How generated CMS fixtures are produced, checked, and kept in sync with their source definitions.

Clean-break authority

This repository has no users or persisted production data. Keep one clear current schema and replace provisional storage or source layouts when they no longer describe the tool. Do not add migrations, legacy readers, redirects, aliases, compatibility shims, or old-schema fixtures to make a generated host look current.

That policy is limited to this repository's current state. It does not authorize destructive changes to a consumer repository, a user's files, hosting, credentials, or another project's infrastructure.

Authored source and generated output

For every source-bearing demo host, site-project.ts is authored source. The following are generated by the installed zudo-composer producer and are committed only so a fresh checkout has a ready workspace:

• site-project.json, the canonical aggregate generated from site-project.ts;

• the ready cms/ trees for Compositions, Content, Mappings, Sitemaps, and the workspace registry; and

• scripts/cms-fixtures.json, the generated directory-ownership metadata.

Do not edit those generated records, transaction pointers, file digests, or ownership entries by hand. Assets are a separate host-owned store and are not part of the five generated ready-workspace roots that the regeneration script replaces; public uploads, release state, package files, components, styles, and other host data are protected as well.

Regenerate all hosts

From the repository root, with authoring servers stopped:

corepack pnpm cms:regenerate
corepack pnpm cms:check

cms:regenerate discovers source-bearing hosts on disk under packages/ and fixtures/, including new demo hosts. It evaluates each host's authored source, runs the installed generate, then runs seed --ready-workspace into fresh staging with the host's own config, component pack, and Assets. It prepares every host before publishing any replacement, writes the generated directories and files, and updates scripts/cms-fixtures.json only when its ownership has changed. Commit the generated output and ownership with the authored source in the same change.

The script replaces only known generated trees that match Git HEAD or the fresh producer bytes. It refuses edited, untracked, symlinked, overlapping, or otherwise unknown destinations and refuses an edited site-project.json. Preserve local CMS edits separately before running it. An interrupted publication can leave a partial generated tree; inspect it, restore the generated baseline while retaining authored changes elsewhere, and retry with a fresh output.

cms:check is read-only. It runs generate --check, stages a fresh ready workspace for every discovered host, validates the current readers against the staged records, and compares exact directory inventories, filenames, and SHA-256 file digests with the committed trees. It also checks that the ownership file covers the same five roots for every host. Differences name the host and tell you to run cms:regenerate.

When regeneration is required

Regenerate every host atomically whenever any producer input can alter a generated byte or its identity:

• a storage format, workspace layout, or reader/compiler change;

• an authored site-project.ts or generated aggregate change;

• a component-pack/provider change, including its source or protocol identity;

• a change to the ready-workspace producer, seed behavior, or generated path ownership; or

• a build-identity/toolchain change, even when site-project.json itself is byte-for-byte unchanged.

Old records need not pass the new readers before this explicit regeneration; there is still no migration path. The clean-break procedure in the SiteProject operator guide has the full staging, preservation, and recovery details.