(gen2-migration) implement `retain` command and add it to the E2E migration flow

[sai-ray]

Is this feature request related to a new or existing Amplify category?

No response

Is this related to another service?

No response

Describe the feature you'd like to request

Add a new retain subcommand to amplify gen2-migration and extend the E2E flow to cover it. Two concerns, one delivery:

1. Implement the retain subcommand

amplify gen2-migration retain applies DeletionPolicy: Retain and UpdateReplacePolicy: Retain to every resource in every Gen1 CloudFormation stack (root + all nested, recursively). The purpose is to protect the Gen2 environment from unintended impact caused by the Gen1 stacks after migration.

2. Add retain to the E2E flow

The E2E system currently runs deploy → assess → lock → generate → sandbox → refactor → test and stops after refactor. There's no automated coverage for retain.

Describe the solution you'd like

1. For behaviour of retain:

• Walks the Gen1 stack hierarchy via paginated ListStackResources calls (leaf-first).
• For each stack, fetches the template, sets DeletionPolicy: Retain / UpdateReplacePolicy: Retain on every resource entry, creates a changeset, and executes it.
• Strict per-stack whitelist validation: the changeset must only contain DeletionPolicy / UpdateReplacePolicy → Retain edits. Anything else fails validation with the rendered changeset as the report.
• Each operation's describe() surfaces the CloudFormation changeset console URL so the user can inspect exactly what will change before approving.
• Rollback throws descriptive one-way operation message.

2. For wiring it in e2e migration flow:

Extend App.migrate() to run retain after the final testSharedData() call, followed by another testGen2() to confirm the Gen2 app still behaves correctly once the Gen1 stacks are marked for retention.

In App.migrate(), after the final testSharedData() call, add:

await this.retain();
await this.testGen2();

Where retain() follows the same pattern as refactor():

public async retain(): Promise<void> {
  await this.runMigrationStep('retain');
}

This validates that after retention, the Gen2 app is fully self-contained and is still functional.

Describe alternatives you've considered

None

Additional context

No response

Is this something that you'd be interested in working on?

• 👋 I may be able to implement this feature request

Would this feature include a breaking change?

• ⚠️ This feature might incur a breaking change