feat(cli): add retain command for gen2-migration

[sai-ray]

Fixes #14790

Description of changes

Adds a new amplify gen2-migration retain step and removes dead code left behind by the upstream decommission removal.

retain subcommand

After migration, Gen1 CloudFormation stacks are defunct but still contain custom resources that may reference resources now owned by Gen2. Changes to those stacks can cause unintended impact on the Gen2 environment.

retain walks every Gen1 stack below the root top-down and applies DeletionPolicy: Retain and UpdateReplacePolicy: Retain to every resource except AWS::CloudFormation::Stack references. Once applied, the user can manually delete the Gen1 root stack and every underlying AWS resource survives as an orphan.

Key design choices

Skip root

Updating the root post-refactor risks cascading TemplateURL reconciliation through the entire tree. The user manually deletes the root after retain completes; CloudFormation cascades through the already-retained children and every resource below root gets DELETE_SKIPPED.

Skip AWS::CloudFormation::Stack references

Adding retain to a nested-stack reference would be a no-op for child protection — the child's own retain state is what matters when the cascade delete hits it. Leaving the reference entry untouched keeps the parent changeset strictly additive on non-stack attributes.

Per-operation changeset flow

Each stack's fetchTemplate → createChangeSet → executeChangeSet round-trip happens inside the operation's execute() rather than at plan time. Creating all changesets up front would produce OBSOLETE changesets on every parent execute.

Strict whitelist

Every changeset is validated against a two-shape whitelist: direct DeletionPolicy / UpdateReplacePolicy edits targeting Retain, or CloudFormation's own Automatic/Dynamic re-evaluations on AWS::CloudFormation::Stack references emitted on every parent update. Anything else (property edits, Add, Remove, Replacement: True) throws MigrationError.

One-way operation

--rollback is rejected at the dispatcher and step.rollback() throws NotImplementedFault. To undo, the user edits the CloudFormation templates directly.

Dead code removal

The upstream decommission removal left validateStatefulResources and its private helper getStatefulResources in _common/validations.ts with no remaining callers, plus 619 lines of tests, a bottleneck dependency used only by those methods, and three unimplemented logger.warn('Not implemented') stubs (validateDeploymentVersion, validateIsolatedEnvironment, validateIngressTraffic). All removed.

Issue #, if available

#14790

Description of how you validated changes

• Added 13 unit tests covering the walker, the per-stack operation lifecycle, and the changeset whitelist.
• End-to-end validated against both mood-board and project-boards in amplify-migration-apps/. After running the full migration workflow and invoking retain, the user-triggered manual root-stack delete completed successfully — all nested stack resources transitioned to DELETE_SKIPPED and every underlying AWS resource (DynamoDB, Lambda, S3, Cognito, AppSync, Kinesis) survived as an orphan.
• Post-delete test:gen1 verified the retained resources are still reachable and the app continues to function.

Checklist

• PR description included
• yarn test passes (for the changed packages)
• Tests are added
• Relevant documentation is changed or added
• New AWS SDK calls or CloudFormation actions have been added to relevant test and service IAM policies
• Pull request labels are added

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.