@payfit/iac 1.0.3-ephemeral-migration-scripts-cleanup-pr.0 → 1.0.4-ephemeral-iac-migration-docs.0

package/dist/executors/stack-migration/README.md

@@ -1,125 +1,81 @@
 # Stack Migration Executor
 
-NX executor for migrating Spacelift stacks from centralized iac-deploy to repository-level metastacks.
-
-## Overview
-
-This tool automates the migration of Spacelift stacks to the new metastack architecture. It creates necessary PRs, generates import files, and manages state removal.
-
-## Commands
-
-### Complete Workflow
-
-```bash
-# Run the full migration (recommended for first-time users)
-nx run <project>:stack-migration --command=run
-
-# Run in dry-run mode to preview changes
-nx run <project>:stack-migration --command=run --dryRun
+Migrate Spacelift stacks from iac-deploy to repository-level metastacks.
+
+## Migration Flow
+
+```mermaid
+flowchart TD
+    subgraph Phase1["📦 1: Setup"]
+        A[init] --> B[Create PRs + Scripts]
+    end
+
+    subgraph Phase2["🔒 2: Safety & Enrollment"]
+        B --> C[Merge Safety Net PR]
+        C --> D[Merge Domain Enrollment PR]
+    end
+
+    subgraph Phase3["🧹 3: State Management"]
+        D --> E[Run State Removal]
+        E --> F[Merge iac-deploy Cleanup PR]
+        F --> G[Run migrate-spaces]
+    end
+
+    subgraph Phase4["✅ 4: Complete"]
+        G --> H[Merge Service Repo PR]
+        H --> I[Run Cleanup]
+        I --> J[Merge Post-Migration Cleanup PR]
+    end
 ```
 
-### Individual Steps
-
-You can also run each step independently. This is useful if you need to pause the migration or re-run specific steps.
+## Quick Start
 
 ```bash
-# 1. Initialize migration (clone repos, collect info)
-nx run <project>:stack-migration --command=init
-
-# 2. Check migration state
-nx run <project>:stack-migration --command=state
-
-# 3. Create domain enrollment PR
-nx run <project>:stack-migration --command=enroll
-
-# 4. Create service repository PR and generate state removal commands
-nx run <project>:stack-migration --command=generate-tf-migration
-
-# 5. Create cleanup PR (iac-deploy)
-nx run <project>:stack-migration --command=cleanup-pr
-
-# 6. Generate migration procedure documentation
-nx run <project>:stack-migration --command=generate-procedure
-
-# 7. Update stack spaces (move to domain space) - RUN MANUALLY ONLY
-nx run <project>:stack-migration --command=migrate-spaces
+# Full migration (recommended)
+nx run <project>:stack-migration --command=run
 
-# 8. Clean up migration files
-nx run <project>:stack-migration --command=migration-cleanup
+# Preview changes first
+nx run <project>:stack-migration --command=run --dry-run
 ```
 
-## Migration Flow and Dependencies
-
-The migration follows a specific sequence. Here's the required flow:
-
-### Phase 1: Setup and Configuration
-
-1. **init** - Clones required repos, validates auth, collects service info
-   - Creates `.migration-state.json` to track progress
-   - Clones: `domain-enrollment`, `iac-deploy`
-   - Loads stack configuration
-
-### Phase 2: Safety and Enrollment
-
-2. **enroll** - Creates domain enrollment PR
-   - Adds repository to domain's `spacelift.yaml`
-   - PR must be merged before continuing
-   - Deploys the metastack for your repository
-
-3. **generate-tf-migration** - Creates service repository PR and state removal script
-   - Copies `spacelift.yaml` from iac-deploy
-   - Generates `.metastack/import.tf` with import blocks
-   - Generates `METASTACK_STATE_REMOVAL_COMMANDS.sh`
-   - DO NOT MERGE THIS PR YET
-
-### Phase 3: Cleanup and State Management
-
-4. **cleanup-pr** - Creates cleanup PR
-   - iac-deploy: Removes stack configuration file
-   - DO NOT MERGE THIS PR YET
-
-5. **generate-procedure** - Generates migration documentation
-   - Creates `METASTACK_MIGRATION_PROCEDURE.md`
-   - Provides complete overview of migration steps
-
-6. **migrate-spaces** - Updates stack spaces (MANUAL STEP)
-   - Moves stacks from old space to `domain-{domain}` space
-   - **IMPORTANT**: Run MANUALLY after state removal commands
-   - Run AFTER state removal, BEFORE merging cleanup PRs
-   - NOT included in full `run` workflow for safety
-
-### Phase 4: Completion
-
-7. After all steps complete:
-   - Merge cleanup PR (iac-deploy)
-   - Merge service repository PR
-   - Run **migration-cleanup** to remove temporary files
-
-## Important Notes
-
-### State Management
-
-- Migration state is saved in `.migration-state.json`
-- You can resume migration from any step
-- Configuration (stacks) is preserved in state
-- You can run steps in any order after `init`, but follow the recommended flow
-
-### Order Requirements
-
-While steps can be run independently, they should generally follow this sequence:
-
-1. `init` must be run first (loads configuration)
-2. `enroll` should be merged before running `generate-tf-migration`
-3. `generate-tf-migration` creates the service repo PR and state removal script
-4. Run state removal commands from `METASTACK_STATE_REMOVAL_COMMANDS.sh` before merging cleanup PR
-5. Run `migrate-spaces` MANUALLY after state removal but before merging cleanup PR
-6. Merge cleanup PR before merging service repository PR
-7. The full `run` command skips `migrate-spaces` for safety - you must run it manually
-
-### Files Generated
+## Commands
 
-- `.migration-state.json` - Migration state and progress
-- `METASTACK_MIGRATION_PROCEDURE.md` - Complete migration procedure
-- `METASTACK_STATE_REMOVAL_COMMANDS.sh` - Commands to remove Terraform state
-- `.metastack/import.tf` - Terraform import blocks
-- `spacelift.yaml` - Stack configuration
+| Command                 | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| `init`                  | Clone repos, load config                      |
+| `state`                 | Show migration state                          |
+| `enroll`                | Create domain enrollment PR                   |
+| `generate-tf-migration` | Create service PR + state removal script      |
+| `iac-deploy-cleanup`    | Create iac-deploy cleanup PR                  |
+| `generate-procedure`    | Generate procedure doc                        |
+| `migrate-spaces`        | Move stacks to domain space (manual)          |
+| `cleanup`               | Create post-migration PR + remove local files |
+
+## Execution Order
+
+| Step | Action                              | Type      |
+| ---- | ----------------------------------- | --------- |
+| 1    | Merge **Safety Net** PR             | 🔀 PR     |
+| 2    | Merge **Domain Enrollment** PR      | 🔀 PR     |
+| 3    | Run state removal script            | 🔧 Manual |
+| 4    | Merge **iac-deploy Cleanup** PR     | 🔀 PR     |
+| 5    | Run migrate-spaces                  | 🔧 Manual |
+| 6    | Merge **Service Repo** PR           | 🔀 PR     |
+| 7    | Run cleanup                         | 🔧 Manual |
+| 8    | Merge **Post-Migration Cleanup** PR | 🔀 PR     |
+
+## Files Generated
+
+| File                                  | Purpose                          |
+| ------------------------------------- | -------------------------------- |
+| `.migration-state.json`               | Migration state (resume anytime) |
+| `METASTACK_MIGRATION_PROCEDURE.md`    | Checklist & instructions         |
+| `METASTACK_STATE_REMOVAL_COMMANDS.sh` | State removal commands           |
+| `.metastack/import.tf`                | Terraform import blocks          |
+| `spacelift.yaml`                      | Stack definitions                |
+
+## Notes
+
+- State saved in `.migration-state.json`, you can resume at any time
+- `migrate-spaces` must be run manually (not in `run` workflow)
+- Run state removal before merging iac-deploy cleanup PR to avoid actually deleting the stacks

package/dist/executors/stack-migration/lib/migration-tool.d.ts

@@ -66,13 +66,9 @@ export declare class MigrationTool extends MigrationHelper {
      */
     checkMigrationState(): Promise<void>;
     /**
-     * Clean up migration files
+     * Clean up migration (creates PR + removes local files)
      */
     cleanupMigration(): Promise<void>;
-    /**
-     * Create Final Cleanup PR (remove import.tf and spacelift provider from version.tf)
-     */
-    createFinalCleanupPR(): Promise<void>;
     /**
      * Full migration workflow
      */