Safely upgrade an existing FSD CLI project

Inspect before applying

Start inside the project root or any nested folder. The CLI locates a reliable root containing both fsd.config.json and package.json, then prints the migration path, file plan, conflicts, and validation steps.

# Read-only plan with file-level changes
npx create-fsd-architecture@latest upgrade --dry-run

# Read-only status for local checks or CI
npx create-fsd-architecture@latest upgrade --check

Both commands are non-mutating: they do not create a manifest, backup, log, lockfile, or temporary project file.

Understand the plan

Resolve every CONFLICT and MANUAL item before applying. --yes only skips confirmation; it never overrides a conflict. Upgrade intentionally has no --force, blind adoption, or downgrade mode.

Apply a safe plan

# Review and confirm interactively
npx create-fsd-architecture@latest upgrade

# Apply a conflict-free plan without a prompt
npx create-fsd-architecture@latest upgrade --yes

# Skip dependency installation when a migration changes dependencies
npx create-fsd-architecture@latest upgrade --yes --no-install

The CLI checks planned content again immediately before each write. If a file changed after you reviewed the plan, the operation stops rather than applying a stale update.

Ownership manifest

Projects created with 2.6.0 contain .fsd/manifest.json. It records deterministic SHA-256 hashes for CLI-owned files, precise marker regions, and dependency entries. It does not store secrets, environment values, application data, or node_modules.

Generated Redux reducer registration refreshes its managed hash only when the store still matches the recorded state. A user-modified managed file becomes a conflict instead of being silently accepted. Unclaimed dependency versions and unrelated package metadata stay user-owned.

Projects created before 2.6.0

A project without a manifest enters conservative legacy mode. The CLI adopts only content matching known released signatures. Customized, missing, or ambiguous managed files require manual resolution; business code outside CLI-owned surfaces remains untouched.

Planning has unit coverage across npm, pnpm, Yarn, and Bun. The normal framework CI continues to build freshly generated projects; it is not a claim that every customized historical project can be migrated automatically.

CI exit codes

npx create-fsd-architecture@latest upgrade --check

Git, backup, and recovery

Applying is refused in a dirty Git worktree by default. After reviewing the plan, --allow-dirty accepts that risk and uses the same internal affected-path backup. The CLI never resets, stashes, commits, switches branches, or treats Git as its only backup.

npx create-fsd-architecture@latest upgrade --allow-dirty

Before writing, affected regular files and lockfiles are snapshotted under .fsd/backups/. Writes are atomic and failures roll back in reverse order. Successful upgrades remove their temporary backup; failed rollback retains it and prints its exact location.

1. Read the complete error and any printed recovery-backup path.
2. Inspect the restored files before making another attempt.
3. If installation failed, run your package manager's install command to restore node_modules.
4. Run upgrade --dry-run again and resolve remaining conflicts.