@planningcenter/tapestry-migration-cli 3.4.1 → 3.6.0

package/README.md

@@ -18,11 +18,13 @@ This order ensures that Button components with navigation props are properly han
 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
    - Run your JS/TS code formatter (like Prettier) and commit any formatting 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)
@@ -69,6 +71,7 @@ Consider these steps to safely migrate your components:
    - 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
@@ -79,10 +82,12 @@ Consider these steps to safely migrate your components:
      ```
 
 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
@@ -94,11 +99,13 @@ Consider these steps to safely migrate your components:
    - 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. **Format your code**
+
    - Run your JS/TS code formatter (like Prettier) to ensure consistent code formatting
 
 9. **Commit your changes**
@@ -120,14 +127,66 @@ npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-t
 npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --report-path ./migration-report.md
 ```
 
+### Listing available migrations
+
+Use `list --json` to discover available migrations programmatically:
+
+```bash
+npx @planningcenter/tapestry-migration-cli list --json
+```
+
+**Stable JSON contract (stdout, exit 0):**
+
+```json
+{
+  "schemaVersion": 1,
+  "migrations": [
+    { "id": "button", "label": "Button" },
+    { "id": "checkbox", "label": "Checkbox" }
+  ]
+}
+```
+
+Contract guarantees:
+
+- Exit code `0` and **JSON only** on stdout — no progress text or emoji.
+- `schemaVersion` is the integer `1`. Future breaking changes increment this version.
+- Each `id` is the exact value accepted by `run <component-name>`.
+- Each `label` is nonempty display text (Spaced Title Case).
+- `id`s are unique; ordering is the CLI's recommended display order.
+- No `--path` required; no filesystem writes.
+- Diagnostics go to **stderr** with a **nonzero** exit code.
+
+Human-readable listing (non-contractual):
+
+```bash
+npx @planningcenter/tapestry-migration-cli list
+```
+
 ## Available Components
 
 - `button` - Migrate Button components
 - `checkbox` - Migrate Checkbox components
+- `date-picker` - Migrate DatePicker components
+- `dropdown` - Migrate Dropdown components
+- `input` - Migrate Input components
 - `link` - Migrate Link components
 - `radio` - Migrate Radio components
+- `select` - Migrate Select components
+- `text-area` - Migrate TextArea components
+- `time-field` - Migrate TimeField components
 - `toggle-switch` - Migrate ToggleSwitch components
 
+## Preflight Assessment
+
+Before running per-component migrations, use the `preflight` command to assess migration readiness across your `@planningcenter/tapestry-react` usage:
+
+```bash
+npx @planningcenter/tapestry-migration-cli preflight -p ./src/components --dry-run --report-path ./migration-plan.md
+```
+
+Preflight surfaces shorthand style props and unsupported `as` prop usage so you can plan the work. It is intended for assessment — running it with changes applied converts shorthand style props to inline `style={{}}` objects, which is rarely the desired end state. Use the per-component `run` migrations for the actual conversion.
+
 ## Required Arguments
 
 - `-p, --path <path>` - **REQUIRED**: Path to the folder or file to migrate