next-lovable 0.0.63 → 0.0.71

package/README.md

@@ -7,6 +7,7 @@ An intelligent CLI tool to automatically migrate React applications to Next.js 1
 - 🚀 Smart React Router to Next.js App Router conversion
 - 📦 Automated migration from Vite to Next.js build system
 - 🔄 Intelligent component transformation with 'use client' directives
+- 📁 **NEW in v0.7+**: Single file conversion with credit tracking
 - 🎯 Automatic handling of:
   - Route configurations
   - Layouts and page structures
@@ -18,7 +19,7 @@ An intelligent CLI tool to automatically migrate React applications to Next.js 1
 
 - Node.js 18.x or higher
 - npm or yarn
-- A nextlovable.com account
+- A nextlovable.com account (for full project migrations)
 - A React project using:
   - React Router
   - Vite
@@ -32,23 +33,85 @@ npm install -g next-lovable
 
 ## Authentication
 
-The tool requires authentication with your nextlovable.com account:
+Authentication with your nextlovable.com account is required for all conversions:
 - Login will be prompted on first use
 - Sessions are securely stored for future use
 - Automatic token refresh handling
+- Required for both file conversion and full project migration
+
+## Credit System
+
+- **Initial credits**: 10 file conversion credits when you sign up
+- **Credit packages**: Each migration credit purchased grants 10 additional file conversion credits
+- **Usage**: 1 file conversion credit consumed per file converted (dry-run is free)
+- **Balance**: Check your current balance during conversion
 
 ## Usage
 
-### Basic Command
+### New in v0.0.7+: Command Structure
+
+Starting from version 0.0.7, the CLI uses subcommands:
 
+```bash
+# Full project migration (requires auth + migration credits)
+next-lovable migrate <source-directory> [target-directory]
+
+# Single file conversion (requires auth + file conversion credits)  
+next-lovable convert <file> [options]
+
+# Check your file conversion credit balance
+next-lovable credits
+```
+
+**Note**: In versions before 0.6, use the legacy format:
 ```bash
 next-lovable <source-directory> [target-directory]
 ```
 
+### Single File Conversion 📁
+
+Convert individual React files to Next.js with credit tracking:
+
+```bash
+# Convert a single component (consumes 1 file conversion credit)
+next-lovable convert MyComponent.tsx
+
+# Save to different location
+next-lovable convert MyComponent.tsx --output ./converted/MyComponent.tsx
+
+# Apply specific transformations only
+next-lovable convert MyComponent.tsx --transform router,client
+
+# Preview changes without consuming credits
+next-lovable convert MyComponent.tsx --dry-run --show-diff
+
+# List available transformations (no auth required)
+next-lovable convert --list
+```
+
+#### Available Transformations
+
+- `router`: React Router → Next.js Router (useNavigate, Link, etc.)
+- `helmet`: React Helmet → Next.js Head
+- `client`: Add "use client" directive where needed
+- `context`: Context provider transformations
+- `all`: Apply all transformations (default)
+
+#### Single File Options
+
+- `-o, --output <path>`: Output file path (default: overwrite input)
+- `-t, --transform <types>`: Comma-separated transformations (default: all)
+- `-d, --dry-run`: Preview changes without modification
+- `--show-diff`: Show before/after comparison (with --dry-run)
+- `--legacy`: Use legacy transformers instead of enhanced ones
+- `--list`: List available transformations
+
+### Full Project Migration
+
 ### Dry Run Mode (Recommended First Step)
 
 ```bash
-next-lovable ./my-react-app --dry-run
+next-lovable migrate ./my-react-app --dry-run
 ```
 
 The `--dry-run` option provides:
@@ -59,22 +122,24 @@ The `--dry-run` option provides:
 - 🎯 Preview of transformations
 - 0️⃣ No actual changes made
 
-### Full Migration
+### Complete Migration
 
 ```bash
-next-lovable ./my-react-app ./next-app --yes --install
+next-lovable migrate ./my-react-app ./next-app --yes --install
 ```
 
-### Available Options
+### Project Migration Options
 
 - `-y, --yes`: Skip confirmation prompts
 - `-i, --install`: Install dependencies after migration
 - `-d, --dry-run`: Simulation mode without changes
+- `-e, --enhanced`: Use enhanced migration (default)
+- `--legacy`: Use legacy migration mode
 - `--help`: Show help information
 
 ## Migration Process
 
-1. **Authentication & Validation**
+1. **Authentication & Validation** (Full Migration Only)
    - Account verification
    - Project structure validation
    - Dependencies check
@@ -92,11 +157,43 @@ next-lovable ./my-react-app ./next-app --yes --install
    - Dependency updates
    - Configuration generation
 
-4. **Post-Migration Setup**
+4. **Post-Migration Setup** (Full Migration Only)
    - Next.js configuration
    - TypeScript adjustments
    - Development environment setup
 
+## Workflow Examples
+
+### Testing Individual Components
+
+```bash
+# Test router conversion on a specific component (free with dry-run)
+next-lovable convert src/components/Navigation.tsx --dry-run
+
+# Convert only routing-related code (consumes 1 credit)
+next-lovable convert src/pages/Dashboard.tsx --transform router --output ./test-output.tsx
+
+# Preview all transformations with diff (free)
+next-lovable convert src/App.tsx --dry-run --show-diff
+```
+
+### Before Full Migration
+
+```bash
+# 0. Check your file conversion credit balance
+next-lovable credits
+
+# 1. Test key components individually (free with dry-run)
+next-lovable convert src/App.tsx --dry-run
+next-lovable convert src/components/Layout.tsx --dry-run
+
+# 2. Run full project dry-run (consumes migration credits)
+next-lovable migrate ./my-react-app --dry-run
+
+# 3. Execute full migration
+next-lovable migrate ./my-react-app ./next-app --install
+```
+
 ## Intelligent Features
 
 - 🧠 Smart component analysis for 'use client' directives
@@ -104,6 +201,33 @@ next-lovable ./my-react-app ./next-app --yes --install
 - 📱 Layout preservation and enhancement
 - 🛠️ Dependency resolution and cleanup
 - 🎯 Typescript support and type preservation
+- ⚡ **Enhanced transformers** (v0.6+):
+  - Advanced React Router pattern detection
+  - Smarter client/server component separation
+  - Better handling of complex routing scenarios
+  - Improved template literal preservation in routes
+
+## Transformation Details
+
+### Router Conversion (`router`)
+- `useNavigate()` → `useRouter()` from `next/navigation`
+- `<Link to="/path">` → `<Link href="/path">` from `next/link`
+- `useLocation()` → `usePathname()` + `useSearchParams()`
+- `useParams()` → Next.js `useParams()`
+- Template literals in paths preserved: `to={\`/user/\${id}\`}` → `href={\`/user/\${id}\`}`
+
+### Helmet Conversion (`helmet`)
+- `<Helmet>` → `<Head>` from `next/head`
+- Meta tags and title preservation
+- SEO attributes maintained
+
+### Client Directive (`client`)
+- Automatic "use client" directive addition
+- Smart detection of client-side features:
+  - React hooks (useState, useEffect, etc.)
+  - Event handlers (onClick, onChange, etc.)
+  - Browser APIs (window, document, localStorage)
+  - Third-party client libraries
 
 ## Post-Migration
 
@@ -112,6 +236,92 @@ next-lovable ./my-react-app ./next-app --yes --install
 3. Check converted routes
 4. Verify component functionality
 
+## Real-World Examples
+
+### Converting a React Router Navigation Component
+
+**Before** (React Router):
+```tsx
+import { Link, useNavigate, useLocation } from 'react-router-dom';
+
+export const Navigation = () => {
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  return (
+    <nav>
+      <Link to="/dashboard">Dashboard</Link>
+      <Link to={`/profile/${userId}`}>Profile</Link>
+      <button onClick={() => navigate('/settings')}>
+        Settings
+      </button>
+      <p>Current: {location.pathname}</p>
+    </nav>
+  );
+};
+```
+
+**After** (Next.js) - using `next-lovable convert`:
+```tsx
+'use client';
+
+import Link from 'next/link';
+import { useRouter, usePathname } from 'next/navigation';
+
+export const Navigation = () => {
+  const router = useRouter();
+  const pathname = usePathname();
+
+  return (
+    <nav>
+      <Link href="/dashboard">Dashboard</Link>
+      <Link href={`/profile/${userId}`}>Profile</Link>
+      <button onClick={() => router.push('/settings')}>
+        Settings
+      </button>
+      <p>Current: {pathname}</p>
+    </nav>
+  );
+};
+```
+
+### Converting React Helmet SEO Component
+
+**Before**:
+```tsx
+import { Helmet } from 'react-helmet';
+
+export const PageMeta = ({ title, description }) => (
+  <Helmet>
+    <title>{title}</title>
+    <meta name="description" content={description} />
+  </Helmet>
+);
+```
+
+**After**:
+```tsx
+import Head from 'next/head';
+
+export const PageMeta = ({ title, description }) => (
+  <Head>
+    <title>{title}</title>
+    <meta name="description" content={description} />
+  </Head>
+);
+```
+
+## Quick Command Reference
+
+| Task | Command | Credits Required |
+|------|---------|------------------|
+| List transformations | `next-lovable convert --list` | ❌ No |
+| Check credit balance | `next-lovable credits` | ❌ No (auth required) |
+| Test single file | `next-lovable convert MyComponent.tsx --dry-run` | ❌ No |
+| Convert single file | `next-lovable convert MyComponent.tsx` | ✅ 1 file credit |
+| Preview project migration | `next-lovable migrate ./my-app --dry-run` | ✅ Migration credits |
+| Full project migration | `next-lovable migrate ./my-app ./next-app` | ✅ Migration credits |
+
 ## Limitations
 
 - Complex custom route configurations may need manual adjustments
@@ -121,7 +331,40 @@ next-lovable ./my-react-app ./next-app --yes --install
 
 ## Best Practices
 
-1. Always run `--dry-run` first
-2. Keep a backup of your original project
-3. Review generated files before deployment
-4. Test thoroughly after migration
+1. **Start with Dry-Run Testing (Free)**
+   - Test key components individually with `convert --dry-run`
+   - No credits consumed for dry-run operations
+   - Perfect for understanding what changes will be made
+
+2. **Efficient Credit Usage**
+   - Use dry-run mode extensively before actual conversion
+   - Convert multiple files at once when possible
+   - Plan your transformations to minimize credit usage
+
+3. **Full Project Migration**
+   - Always run `migrate --dry-run` first
+   - Keep a backup of your original project
+   - Review generated files before deployment
+   - Test thoroughly after migration
+
+4. **Incremental Approach**
+   ```bash
+   # Test individual files first (free with dry-run)
+   next-lovable convert src/App.tsx --dry-run
+   next-lovable convert src/components/*.tsx --dry-run
+   
+   # Convert specific files (consumes file credits)
+   next-lovable convert src/App.tsx
+   next-lovable convert src/components/Navigation.tsx
+   
+   # Then migrate the full project (consumes migration credits)
+   next-lovable migrate ./my-react-app --dry-run
+   next-lovable migrate ./my-react-app ./next-app --install
+   ```
+
+## Version Notes
+
+- **v0.6+**: New subcommand structure (`migrate`, `convert`)
+- **v0.5 and earlier**: Legacy command format (direct arguments)
+- **v0.6+**: File conversion with credit tracking system added
+- **Credit System**: 10 initial credits + 10 credits per migration credit purchased

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "next-lovable",
-  "version": "0.0.63",
-  "description": "Cross-platform tool to migrate Lovable React projects to Next.js",
+  "version": "0.0.71",
+  "description": "Cross-platform tool to migrate Lovable React projects to Next.js with credit-free single file conversion",
   "main": "./dist/index.js",
   "homepage": "https://nextlovable.com",
   "scripts": {
+    "test": "node ./tests/test-runner.js",
+    "test:unit": "node ./tests/unit/codemods.test.js && node ./tests/unit/router.test.js && node ./tests/unit/file-ops.test.js",
+    "test:integration": "node ./tests/integration/migration.test.js",
+    "test:e2e": "node ./tests/e2e/cli.test.js",
+    "test:pre-publish": "node ./tests/pre-publish.js",
     "prepare-publish": "node ./scripts/prepare-publish.js",
     "post-publish": "node ./scripts/post-publish.js",
-    "prepublishOnly": "npm run build && npm run prepare-publish",
+    "prepublishOnly": "npm run build && npm run test:pre-publish && npm run prepare-publish",
     "postpublish": "npm run post-publish",
     "build": "bash ./build.sh"
   },
@@ -37,6 +42,7 @@
   "license": "ISC",
   "dependencies": {
     "@sentry/node": "^9.17.0",
+    "chalk": "^4.1.2",
     "commander": "^13.1.0",
     "fs-extra": "^11.3.0",
     "glob": "^11.0.1",