@planningcenter/tapestry-migration-cli 2.5.0-rc.4 → 2.5.0-rc.5

package/README.md

@@ -2,37 +2,118 @@
 
 A CLI tool to migrate Tapestry React components to Planning Center's Tapestry format.
 
-## Installation
-
-```bash
-yarn add --dev @planningcenter/tapestry-migration-cli
-```
-
 ## Usage
 
 ### Recommended Migration Order
 
 For optimal results, migrate components in this order:
 
-1. **Button components first**: `npx @planningcenter/tapestry-migration-cli run button -p ./src/components`
+1. **Button components first**: `npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js`
 2. **Link components second**: `npx @planningcenter/tapestry-migration-cli run link -p ./src/components`
 
 This order ensures that Button components with navigation props are properly handled before Link components are migrated.
 
+### Recommended Process
+
+Consider these steps to safely migrate your components:
+
+1. **Prepare your workspace** (recommended)
+   - Commit your current changes or create a new branch
+   - This allows you to easily review or revert changes if needed
+
+2. **Create a theme file** (important for button migrations)
+   - Create a CommonJS file called `theme.js` at the root of your project
+   - Populate the file with your project's custom theme values using one of these methods:
+     - **Option 1**: Copy/paste your project's custom theme values directly into the file (computed values should be ignored or set)
+     - **Option 2**: Use `console.log()` to output the raw theme values in your application, then copy/paste the output from the browser console
+   - See the [How It Works > Theme File](#theme-file) section to learn more about the purpose of this file
+   - Example structure:
+     ```javascript
+     // theme.js
+     exports.theme = {
+       button: {
+         themes: {
+            primary: {
+               outline: {
+                  color: 'var(--t-text-color-default-primary)',
+                  hover: {
+                     backgroundColor:
+                     'var(--t-fill-color-button-neutral-outline-dim-hover)',
+                  },
+                  stroke: 'var(--t-border-color-button-neutral)',
+               },
+               ...
+            },
+            ...
+         }
+         ...
+     }
+     ```
+
+3. **Consider your scope**
+
+   ```bash
+   # Run the migration on a directory (button migrations require --js-theme)
+   npx @planningcenter/tapestry-migration-cli run button -p ./src/javascript/components --js-theme ./theme.js
+
+   # Or run the migration on a specific feature
+   npx @planningcenter/tapestry-migration-cli run button -p ./src/features/checkout --js-theme ./theme.js
+
+   # Or run migration on a specific page, view, or single file
+   npx @planningcenter/tapestry-migration-cli run button -p ./src/components/ButtonExample.tsx --js-theme ./theme.js
+   ```
+
+   - Start with a manageable scope to understand the migration changes
+   - For button migrations, include `--js-theme ./theme.js` to reference the theme file created in step 2
+   - Use `--report-path` to generate a migration report for review (will default to MIGRATION_REPORT.md if not specified)
+
+4. **Review the migration report and changed files**
+   - Check the generated migration report (default: `MIGRATION_REPORT.md`)
+   - Review the actual file changes using `git diff` or your editor
+   - Understand what transformations were applied
+     - Use `--verbose` to see `CHANGED` comments in your code indicating what was automatically migrated
+   - **Alternative approach**: Run with `--verbose` and `--report-path` to generate a detailed migration report, save the report for planning purposes, then revert the changes (`git stash` or your editor's revert feature). You can re-run the migration later when ready to proceed:
+     ```bash
+     npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --verbose --report-path ./migration-plan.md
+     ```
+
+5. **Discard or revert changes if needed**
+   - If you're not ready to keep the changes, revert to discard the changes
+   - You can always re-run the migration later when ready
+
+6. **Review TODO comments**
+   - Search for `TODO: tapestry-migration ([scope])` comments in your codebase
+
+   ```bash
+   # Example
+   TODO: tapestry-migration (href)
+   ```
+
+   - These indicate props that need manual migration
+   - Each TODO includes guidance on how to handle the unsupported prop
+
+7. **Test your application**
+   - Run your test suite
+   - Manually verify migrated components work as expected
+   - Pay special attention to any components with TODO comments
+
+8. **Commit your changes**
+   - Commit the automated migrations
+   - Handle unsupported props in separate commits if needed
+   - Once comfortable, migrate larger scopes incrementally
+
 ### Basic Commands
 
 ```bash
 # Apply the migration changes (default behavior)
-npx @planningcenter/tapestry-migration-cli run button -p ./src/components
-
-# Preview changes without writing (dry run)
-npx @planningcenter/tapestry-migration-cli run button -p ./src/components --dry-run
+# Button migrations require --js-theme flag
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js
 
 # Run with verbose output
-npx @planningcenter/tapestry-migration-cli run button -p ./src/components --verbose
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --verbose
 
 # Generate a migration report
-npx @planningcenter/tapestry-migration-cli run button -p ./src/components --report-path ./migration-report.md
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --report-path ./migration-report.md
 ```
 
 ## Available Components
@@ -47,7 +128,7 @@ npx @planningcenter/tapestry-migration-cli run button -p ./src/components --repo
 ## Optional Arguments
 
 - `-d, --dry-run` - Preview changes without writing to files (default: writes changes)
-- `-v, --verbose` - Show detailed output
+- `-v, --verbose` - Show detailed output including automated changes
 - `-j, --js-theme <path>` - Path to JavaScript theme file
 - `-r, --report-path <path>` - Path for migration report (default: MIGRATION_REPORT.md)
 
@@ -59,6 +140,16 @@ The migration tool automatically transforms your components to match Planning Ce
 - Updating import statements and component references
 - Adjusting prop names and values to match current API
 
+### Theme File
+
+The `theme.js` file (provided via `--js-theme`) is used to retrieve theme values during migration. These theme values are used to transform theme-based values into valid style props. When the migration tool encounters theme values in your components, it references this file to:
+
+- Look up theme tokens and design values
+- Convert theme-based styling to appropriate style prop values
+- Ensure migrated components maintain visual consistency with your project's design system
+
+The theme file should contain your project's complete theme structure, including all design tokens, colors, spacing, typography, and component-specific theme values that are used in your Tapestry React components.
+
 ### Unsupported Props
 
 For properties that cannot be automatically migrated, the tool will:
@@ -84,23 +175,3 @@ The comment includes guidance on how to handle the unsupported prop. Common reco
 - Using CSS classes for styling instead of props
 - Moving state-based styles (hover, focus, active) to CSS selectors
 - Applying responsive styles through CSS media queries
-
-## Alternative: Local Installation
-
-If you prefer to install it locally and use a shorter command:
-
-```bash
-# Install locally
-yarn add --dev @planningcenter/tapestry-migration-cli
-
-# Add to package.json scripts
-{
-  "scripts": {
-    "migrate": "tapestry-migration-cli"
-  }
-}
-
-# Then run (following recommended order)
-yarn migrate run button -p app/javascript/components
-yarn migrate run link -p app/javascript/components
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planningcenter/tapestry-migration-cli",
-  "version": "2.5.0-rc.4",
+  "version": "2.5.0-rc.5",
   "description": "CLI tool for Tapestry migrations",
   "type": "module",
   "main": "dist/index.js",
@@ -51,5 +51,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "914423c21b5fea1b57801efb46cea9c181e8896f"
+  "gitHead": "7510de206443c259c4c885252e6ff59f15bf8668"
 }