````md
# morph-cli
> Fast AST-based codebase migration tool for JavaScript and TypeScript projects.
`morph-cli` helps modernize large codebases using structured AST transforms, safe dry-runs, rollback support, migration planning, review workflows, and incremental analysis.
Built for developers who want safer large-scale migrations without relying on fragile regex replacements.
---
## Features
### Codebase Migrations
- CommonJS → ESM
- JavaScript → TypeScript
- React class components → hooks
- Express → Fastify
- Tailwind modernization foundations
### Safety & Review
- Dry-run by default
- Interactive review mode
- Rollback support
- Migration checkpoints
- Confidence scoring
- Verification mode
- Replay support
### Project Intelligence
- Framework detection
- Dependency analysis
- Workspace/monorepo support
- Migration planner
- Recipe recommendations
- Modernization scoring
### Developer Experience
- Incremental caching
- Watch mode
- Presets & profiles
- Execution reports
- Shell completions
- Library/API mode
- Local dashboard foundation
---
# Why morph-cli?
Large migrations are painful.
Most migration tooling:
- relies on regex replacements
- breaks formatting
- lacks rollback support
- provides poor visibility into risky changes
`morph-cli` focuses on:
- AST-based transforms
- safety-first workflows
- explainable migrations
- incremental adoption
- scalable repository analysis
---
# Installation
## Cargo
```bash
cargo install morph-cli
````
## From Source
```bash
git clone https://github.com/s0r0j/morph-cli.git
cd morph-cli
cargo build --release
```
Binary:
```bash
./target/release/morph
```
---
# Quick Start
## Scan a project
```bash
morph scan .
```
## Generate migration recommendations
```bash
morph plan .
```
## Run a dry-run migration
```bash
morph run commonjs-to-esm .
```
## Apply changes
```bash
morph run commonjs-to-esm . --write
```
## Review changes interactively
```bash
morph run commonjs-to-esm . --review
```
## Verify migration output
```bash
morph verify
```
## Rollback a migration
```bash
morph rollback <session-id>
```
---
# Example Workflow
```bash
# Analyze repository
morph scan .
# Generate migration plan
morph plan .
# Run migration safely
morph run commonjs-to-esm . --review
# Verify results
morph verify
# Export report
morph run commonjs-to-esm . --export-report report.json
```
---
# Supported Recipes
| `commonjs-to-esm` | Convert CommonJS modules to ESM |
| `js-to-ts` | Migrate JavaScript projects to TypeScript |
| `react-class-to-hooks` | Convert React class components to hooks |
| `express-to-fastify` | Migrate Express applications to Fastify |
---
# Safety Features
`morph-cli` is designed to be conservative by default.
Features include:
* Dry-run execution
* Confidence scoring
* Verification checks
* Rollback support
* Review mode
* Risk detection
* Execution safeguards
* Incremental checkpoints
Unsafe or unsupported patterns are skipped with warnings instead of being forcefully rewritten.
---
# Monorepo Support
`morph-cli` supports:
* npm workspaces
* pnpm workspaces
* yarn workspaces
You can scope migrations to specific packages:
```bash
morph run commonjs-to-esm . --package api
```
---
# Presets
Built-in migration presets:
```bash
morph preset list
```
Examples:
* `modern-node`
* `typescript-adoption`
* `react-modernization`
---
# Reports & Sessions
`morph-cli` stores:
* migration sessions
* dry-run snapshots
* scan summaries
* validation reports
Useful commands:
```bash
morph sessions
morph history
morph scans
morph dry-runs
```
---
# Watch Mode
Incrementally analyze repositories during development:
```bash
morph watch
```
---
# Configuration
Example `morph-cli.toml`:
```toml
dry_run_default = true
excluded_paths = [
"dist",
"build",
"node_modules"
]
[profiles.safe]
review = true
allow_risky = false
[profiles.aggressive]
review = false
allow_risky = true
```
---
# Philosophy
`morph-cli` is built around a few core principles:
* AST-based transforms over regex hacks
* Conservative migrations over risky rewrites
* Explainable automation
* Safe incremental modernization
* Human review when confidence is low
---
# Project Status
`morph-cli` is currently under active development.
Some advanced framework patterns and ecosystem edge cases may still require manual migration work.
Always review important migrations before deploying to production.
---
# Roadmap
Planned areas of improvement:
* Better transform coverage
* Real-world repository validation
* Stronger semantic verification
* Plugin runtime support
* AI-assisted migration suggestions
* Expanded ecosystem recipes
---
# Contributing
Contributions are welcome.
Before contributing:
* keep changes focused
* avoid broad unrelated refactors
* preserve existing behavior where possible
---
# License
MIT License
---
# Author
Built by **Shreyaj Dinesh**
GitHub:
[https://github.com/s0r0j](https://github.com/s0r0j)
```
```