@planningcenter/tapestry-migration-cli 2.4.0-rc.13 → 2.4.0-rc.14

package/README.md

@@ -1,12 +1,106 @@
 # tapestry-migration-cli
 
-A simple cli tool used to help to migration Tapestry React components to formats that match Planning Center specs (usually to `@planningcenter/tapestry` components).
+A CLI tool to migrate Tapestry React components to Planning Center's Tapestry format.
 
-## Quick Use
+## Installation
 
 ```bash
-# For help
-npx @planningcenter/tapestry-migration-cli
-# Run a migration with autofixing
-npx @planningcenter/tapestry-migration-cli run ComponentName -p ./path/to/files -f
+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 --fix`
+2. **Link components second**: `npx @planningcenter/tapestry-migration-cli run link -p ./src/components --fix`
+
+This order ensures that Button components with navigation props are properly handled before Link components are migrated.
+
+### Basic Commands
+
+```bash
+# Run a dry-run migration (preview changes)
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components
+
+# Apply the migration changes
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix
+
+# Run with verbose output
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix --verbose
+
+# Generate a migration report
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix --report-path ./migration-report.md
+```
+
+## Available Components
+
+- `button` - Migrate Button components
+- `link` - Migrate Link components
+
+## Required Arguments
+
+- `-p, --path <path>` - **REQUIRED**: Path to the folder or file to migrate
+
+## Optional Arguments
+
+- `-f, --fix` - Write changes to files (without this flag, it's a dry run)
+- `-v, --verbose` - Show detailed output
+- `-j, --js-theme <path>` - Path to JavaScript theme file
+- `-r, --report-path <path>` - Path for migration report (default: MIGRATION_REPORT.md)
+
+## How It Works
+
+The migration tool automatically transforms your components to match Planning Center's current Tapestry specifications. Most property and usage changes are handled automatically, including:
+
+- Converting deprecated props to their modern equivalents
+- Updating import statements and component references
+- Adjusting prop names and values to match current API
+
+### Unsupported Props
+
+For properties that cannot be automatically migrated, the tool will:
+
+1. **Keep the prop as-is** - The prop remains in your code but will not work with the new Tapestry component
+2. **Add a TODO comment** - Flagging the prop for manual migration
+
+Example of an unsupported prop comment:
+
+```tsx
+<Button
+  /* TODO: tapestry-migration (propName): 'mediaQueries' is not supported, please migrate as needed.
+   * It is recommended to use CSS media queries in a class that you apply to the component.
+   */
+  mediaQueries={{ mobile: { fontSize: 14 } }}
+>
+  Click me
+</Button>
+```
+
+The comment includes guidance on how to handle the unsupported prop. Common recommendations include:
+
+- 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 --fix
+yarn migrate run link -p app/javascript/components --fix
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planningcenter/tapestry-migration-cli",
-  "version": "2.4.0-rc.13",
+  "version": "2.4.0-rc.14",
   "description": "CLI tool for Tapestry migrations",
   "type": "module",
   "main": "dist/index.js",
@@ -51,5 +51,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "275d9583901bea8ef0d121ef25eff0a1fdf309b4"
+  "gitHead": "45113757c963d9d1267cd969edb5569a17312aeb"
 }

package/src/index.ts

@@ -15,9 +15,15 @@ const COMPONENTS = ["button", "link"]
 program
   .command("run")
   .description("Run a migration of a component from Tapestry React to Tapestry")
-  .argument("<component-name>", "The name of the component to migrate")
-  .option("-f, --fix", "Write the changes")
-  .requiredOption("-p, --path <path>", "The path to the folder/file to migrate")
+  .argument(
+    "<component-name>",
+    "The name of the component to migrate (button, link)"
+  )
+  .requiredOption(
+    "-p, --path <path>",
+    "REQUIRED: The path to the folder/file to migrate"
+  )
+  .option("-f, --fix", "Write the changes to files (default: dry run)")
   .option("-v, --verbose", "Verbose output")
   .option(
     "-j, --js-theme <path>",
@@ -29,16 +35,21 @@ program
     "MIGRATION_REPORT.md"
   )
   .action((componentName, options) => {
-    console.log("Hello from Tapestry Migration CLI! 🎨")
-    console.log(`Component: ${componentName}`)
     const key = componentName.toLowerCase()
 
     if (COMPONENTS.includes(key)) {
+      console.log(`🎨 Migrating ${componentName} components...`)
+      console.log(`📁 Target: ${options.path}`)
+      console.log(
+        `🔧 Mode: ${options.fix ? "Apply changes" : "Dry run (preview only)"}`
+      )
       runTransforms(key, options)
     } else {
-      console.log(
-        `Invalid component name: ${componentName}. Valid components are: ${COMPONENTS.join(", ")}`
+      console.error(`❌ Invalid component: "${componentName}"`)
+      console.error(
+        `✅ Available components: ${COMPONENTS.map((c) => c.charAt(0).toUpperCase() + c.slice(1)).join(", ")}`
       )
+      process.exit(1)
     }
   })