npm package: @kodeme-io/next-core-cli
Description: Powerful CLI for building Next.js + Odoo applications with code generation
Author: ABC Food
Latest version: 0.8.4

# @kodeme-io/next-core-cli

> **The Rails of Odoo Frontends** 🚀
> Powerful CLI for building Next.js + Odoo applications with code generation

Build complete Next.js + Odoo apps in **minutes** instead of **weeks** with intelligent code generation.

## ✨ What's Included

### Core Features
- ✅ **Project Scaffolding** - 10 app types with demo pages
- ✅ **Configuration Files** - Define everything once in config file
- ✅ **Package Management** - Manage 16 next-core packages with auto-dependencies
- ✅ **Smart Code Generation** - Detects installed packages & generates enhanced code
- ✅ **Odoo Introspection** - Browse 400+ models, 200+ fields per model
- ✅ **Page Generation** - List, detail, create, edit pages from models
- ✅ **CRUD Scaffolding** - Complete CRUD (4 pages) in 10 seconds
- ✅ **TypeScript Types** - Auto-generated from Odoo field definitions
- ✅ **Smart Field Selection** - AI picks best 8 fields from 200+
- ✅ **Form Handling** - Validation, many2one support, selection unions
- ✅ **Search & Filtering** - Built-in on all list pages

### 🚀 V2 Features (NEW!)
- ✅ **Watch Mode** - Live code generation with file watching & Odoo schema monitoring
- ✅ **API Routes Generation** - Complete REST APIs from Odoo models with validation & auth
- ✅ **Health Check** - Comprehensive project analysis with scoring (0-100)
- ✅ **Conflict Detection** - Smart regeneration that preserves user modifications
- ✅ **Real-time APIs** - WebSocket support for live updates
- ✅ **Advanced Monitoring** - Performance tracking & error handling
- ✅ **Auto-fix Issues** - Automatic resolution of common project problems

## 📊 Impressive Numbers

- 🚀 **480x faster** than manual coding
- ⚡ **10 seconds** to generate complete CRUD (4 pages)
- 📦 **16 packages** available with auto-dependency resolution
- 🧠 **Smart generation** adapts to installed packages
- 🎯 **8/245 fields** intelligently selected
- 🏗️ **10 app types** ready to use
- 🔧 **400+ Odoo models** supported
- 💻 **4 page types** (list, detail, create, edit)
- 🎨 **TypeScript** types auto-generated
- 👁️ **Watch Mode** detects file changes in <100ms
- 🔌 **API Generation** creates complete REST APIs in 5-30s
- 🏥 **Health Score** provides 0-100 project assessment
- 🛡️ **Conflict Detection** prevents data loss during regeneration

---

## 🎯 Quick Start

### Create a New Project

```bash
# Create new project (full demo with 13 working pages)
npx next-core new my-sfa --type=sfa --yes

# Or use the legacy command
npx create-next-core my-sfa --type=sfa --yes
```

### Check Project Health ✨ NEW

```bash
# Analyze your project and get V2 feature recommendations
next-core health

# Get detailed analysis with suggestions
next-core health --detailed

# Fix common issues automatically
next-core health --fix
```

### Start Live Development ✨ NEW

```bash
# Enable watch mode for live code generation
next-core watch

# Enable Odoo schema monitoring
next-core watch --odoo --verbose

# Monitor specific file patterns
next-core watch --include "src/**/*" --exclude "node_modules/**/*"
```

### Generate APIs ✨ NEW

```bash
# Generate complete REST API from Odoo model
next-core api generate customers --model=res.partner --auth --validation

# Generate real-time API with WebSocket support
next-core api generate products --model=product.template --real-time --monitoring

# Custom API with specific fields
next-core api generate users --model=res.users --include=name,email,login --methods=GET,POST,PUT
```

### Setup Configuration (Optional but Recommended)

```bash
# Create next-core.config.js in your project
cat > next-core.config.js << 'EOF'
module.exports = {
  odoo: {
    url: 'http://localhost:8069',
    database: 'my_database',
    username: 'admin',
    password: 'admin'
  },
  models: {
    'product.product': {
      fields: ['name', 'default_code', 'list_price', 'qty_available', 'categ_id', 'type', 'active']
    },
    'res.partner': {
      fields: ['name', 'email', 'phone', 'city', 'country_id']
    }
  }
}
EOF

# Now you can generate without typing credentials every time!
next-core scaffold crud products --model=product.product
# ✓ Loaded config from next-core.config.js
# ✓ Using field configuration for product.product from config file
```

### Generate Pages ✅

```bash
# Generate a customer list page
next-core generate page customers --model=res.partner --type=list

# Generate a product detail page
next-core generate page product-detail --model=product.product --type=detail

# Other page types: create, edit
next-core generate page products --model=product.product --type=create
```

### Scaffold Complete CRUD ✅

```bash
# Generate complete CRUD in 10 seconds!
next-core scaffold crud products --model=product.product

# Creates 4 pages instantly:
#   ✅ /app/products/page.tsx (list)
#   ✅ /app/products/[id]/page.tsx (detail)
#   ✅ /app/products/[id]/edit/page.tsx (edit)
#   ✅ /app/products/new/page.tsx (create)
#   ✅ TypeScript types automatically generated
```

---

## 📦 Commands

### 🚀 V2 Commands (NEW!)

#### `health` - Project Analysis & Health Scoring

```bash
next-core health [options]   # Comprehensive project health check

Options:
  --detailed                 # Show detailed analysis
  --fix                      # Attempt to fix common issues
  --score-only               # Show only health score (0-100)

Examples:
next-core health             # Basic health check
next-core health --detailed  # Detailed analysis with suggestions
next-core health --fix       # Auto-fix common issues
```

#### `watch` - Live Code Generation

```bash
next-core watch [options]    # Live file watching & regeneration

Options:
  --config <path>            # Config file (default: next-core.config.js)
  --odoo                     # Enable Odoo schema monitoring
  --poll-interval <sec>      # Odoo polling interval (default: 30s)
  --include <patterns>       # Include file patterns
  --exclude <patterns>       # Exclude file patterns
  --verbose                  # Verbose output

Examples:
next-core watch               # Basic watch mode
next-core watch --odoo       # Enable Odoo monitoring
next-core watch --verbose    # Detailed output
```

#### `api` - REST API Generation

```bash
next-core api generate <name> --model <odoo-model> [options]

Required:
  --model <model>            # Odoo model name

Options:
  --methods <methods>        # HTTP methods (GET,POST,PUT,DELETE)
  --auth                     # Enable authentication
  --validation               # Enable request validation
  --include <fields>         # Include specific fields
  --exclude <fields>         # Exclude specific fields
  --output <path>            # Output directory
  --middleware <middleware>  # Custom middleware
  --monitoring               # Enable monitoring
  --real-time                # Enable WebSocket support
  --overwrite                # Overwrite existing files

Examples:
next-core api generate customers --model=res.partner --auth --validation
next-core api generate products --model=product.template --real-time
```

### Core Commands

#### Project Creation

```bash
next-core new <name>         # Create new project
  --type <type>              # App type: sfa, lfa, report, scm, hris, etc.
  --adapter <adapter>        # Backend: odoo, none
  --minimal                  # Generate minimal starter
  --yes                      # Skip prompts
```

### Package Management ✨ NEW

```bash
next-core packages list      # List all available packages
  --category <category>      # Filter: core, ui, business-logic, integration, devtools
  --installed                # Show only installed
  --available                # Show only available

next-core packages info <pkg> # View package details & usage examples

next-core packages add <pkgs...>  # Install packages with dependencies
  --with-deps                # Include dependencies (default)
  --skip-deps                # Skip dependencies

next-core packages remove <pkgs...>  # Uninstall packages
  --check-dependents         # Warn if used by others (default)

next-core packages upgrade   # Upgrade all packages to latest
  --check-only               # Check without installing

next-core packages doctor    # Health check & validation
```

### Odoo Introspection ✅

```bash
# List all Odoo models
next-core odoo models

# Filter models
next-core odoo models --filter=res.partner

# View model fields
next-core odoo fields res.partner

# Filter by field type
next-core odoo fields res.partner --type=char

# Test Odoo connection
next-core odoo connect
```

### Code Generation ✅

```bash
next-core generate page <name>      # Generate page
  --model <model>                    # Odoo model (e.g., res.partner)
  --type <type>                      # Page type: list, detail, create, edit
  --fields <fields>                  # Optional: comma-separated fields
  --url <url>                        # Optional: Odoo URL
  --db <database>                    # Optional: Database name
  --username <user>                  # Optional: Username
  --password <pass>                  # Optional: Password
  --output <dir>                     # Optional: Output directory

# Examples:
next-core generate page customers --model=res.partner --type=list
next-core generate page product-detail --model=product.product --type=detail
```

### CRUD Scaffolding ✅

```bash
next-core scaffold crud <name>      # Complete CRUD (4 pages)
  --model <model>                    # Required: Odoo model
  --fields <fields>                  # Optional: comma-separated fields
  --url <url>                        # Optional: Odoo URL
  --db <database>                    # Optional: Database name
  --username <user>                  # Optional: Username
  --password <pass>                  # Optional: Password
  --output <dir>                     # Optional: Output directory

# Example:
next-core scaffold crud products --model=product.product

# Generates:
#   ✅ List page with search & filtering
#   ✅ Detail page with formatted fields
#   ✅ Create page with form validation
#   ✅ Edit page with pre-filled data
#   ✅ TypeScript interfaces & types
```

### Package Management ✅ NEW

```bash
# List all available next-core packages
next-core packages list
next-core packages list --category=ui          # Filter by category
next-core packages list --installed            # Show only installed
next-core packages list --available            # Show only available

# View package details
next-core packages info ui                     # Show UI package info
next-core packages info forms                  # Show Forms package info

# Install packages (auto-installs dependencies)
next-core packages add ui                      # Install UI package
next-core packages add forms workflow          # Install multiple packages
next-core packages add analytics --skip-deps   # Skip auto-dependencies

# Remove packages
next-core packages remove forms                # Remove Forms package
next-core packages remove ui forms             # Remove multiple packages

# Upgrade all packages
next-core packages upgrade                     # Check & upgrade all
next-core packages upgrade --check-only        # Check only, don't install

# Health check & validation
next-core packages doctor                      # Verify installations
                                              # Check dependencies
                                              # Report version mismatches
```

**Available Packages (16 total)**:

| Category | Package | Description |
|----------|---------|-------------|
| **Core** | `client` | HTTP client with retry & offline support |
| | `odoo-api` | Odoo RPC client for Next.js |
| | `patterns` | Reusable architectural patterns |
| | `hooks` | Custom React hooks |
| **UI** | `ui` | 50+ components + PWA tools (camera, scanner, etc.) |
| **Business** | `forms` | Dynamic form builder with validation |
| | `workflow` | Workflow engine with state management |
| | `analytics` | Analytics, dashboards & KPIs |
| **Integration** | `auth` | Authentication (Odoo, JWT, OAuth2) |
| | `license` | License validation system |
| | `storage` | Storage management (S3, local, Odoo) |
| | `n8n` | n8n workflow integration |
| | `monitoring` | Performance monitoring & error tracking |
| **DevTools** | `testing` | Testing utilities & mocks |
| | `codegen` | Code generation tools |
| | `cli` | This CLI tool |

---

## 🎨 Application Types

| Type | Description | Demo Pages |
|------|-------------|-----------|
| **sfa** | Sales Force Automation | 13 pages |
| **lfa** | Logistics Force Automation | 10 pages |
| **report** | Reports & Dashboards | 8 pages |
| **scm** | Supply Chain Monitoring | 10 pages |
| **hris** | HR Management System | 12 pages |
| **b2b** | B2B Sales App | 10 pages |
| **agri** | Agriculture Management | 10 pages |
| **desk** | Helpdesk Management | 10 pages |
| **talent** | Talent Recruitment | 10 pages |
| **minimal** | Minimal Setup | Basic structure |

---

## ⚡ Productivity Comparison

### Before (Manual Coding)
```bash
$ npx create-next-core my-app
# Then spend 40 hours coding pages manually...
😢 "This is a lot of work"
```

### After (With CLI)
```bash
$ next-core new my-sfa --type=sfa --yes
✅ Created with 13 working pages

$ next-core scaffold crud customers --model=res.partner
✅ Complete CRUD in 30 seconds

$ next-core scaffold crud products --model=product.product
✅ Complete CRUD in 30 seconds

$ pnpm dev
✅ Full app running!

⏱️ Total time: 5 minutes
🤩 "This is INCREDIBLE!"
```

**Result**: **480x faster** development 🚀

---

## 🧠 Smart Code Generation

The CLI automatically detects which `@kodeme-io/next-core-*` packages you have installed and generates **enhanced code** that leverages those packages.

### Example: List Page with Analytics Package

**Without `@next-core/analytics`:**
```tsx
// Basic list page with manual export logic
<MobileHeader
  title="Products"
  actions={<Button>Add</Button>}
/>
```

**With `@next-core/analytics` installed:**
```tsx
// Enhanced list page with ExportButton component
import { ExportButton } from '@kodeme-io/next-core-analytics'

<MobileHeader
  title="Products"
  actions={
    <div className="flex gap-2">
      <ExportButton data={items} filename="products.csv" />
      <Button>Add</Button>
    </div>
  }
/>
```

### Example: Forms with Forms Package

**Without `@next-core/forms`:**
```tsx
// Manual form fields with basic HTML inputs
<form>
  <Input name="name" />
  <Input name="email" />
  <textarea name="notes" />
</form>
```

**With `@next-core/forms` installed:**
```tsx
// Comment suggests using DynamicForm for better UX
{/* 💡 TIP: Consider using DynamicForm from @kodeme-io/next-core-forms for:
    - Auto-generated forms from Odoo fields
    - Built-in validation
    - Better UX with field types
    See: https://github.com/abc-food/next-core/tree/main/packages/forms
*/}
```

### How It Works

1. **Package Detection**: CLI checks your `package.json` for installed `@kodeme-io/next-core-*` packages
2. **Smart Templates**: Templates adapt based on available packages
3. **Zero Configuration**: Works automatically - no config needed
4. **Progressive Enhancement**: Basic code still works without packages

### Supported Package Integrations

| Package | Enhancement | Command |
|---------|-------------|---------|
| `analytics` | ExportButton on list pages | `next-core packages add analytics` |
| `forms` | DynamicForm suggestions | `next-core packages add forms` |
| `workflow` | Workflow state management | `next-core packages add workflow` |
| `storage` | File upload components | `next-core packages add storage` |
| `monitoring` | Performance tracking | `next-core packages add monitoring` |

---

## 📚 Real-World Examples

### Example 1: Create SFA App with Custom Pages

```bash
# 1. Create project (13 demo pages included)
next-core new my-sfa --type=sfa --yes
cd my-sfa

# 2. Configure Odoo connection
echo "ODOO_URL=http://localhost:8069
ODOO_DB=your_database
ODOO_USERNAME=admin
ODOO_PASSWORD=admin" > .env.local

# 3. Generate additional pages
next-core generate page customers --model=res.partner --type=list
next-core generate page invoices --model=account.move --type=list

# 4. Build and run
pnpm dev
# Visit http://localhost:3000
```

### Example 2: Build Complete CRM in 5 Minutes

```bash
# 1. Create project
next-core new my-crm --type=sfa --yes
cd my-crm

# 2. Configure .env.local (see above)

# 3. Scaffold complete CRUDs (4 pages each)
next-core scaffold crud contacts --model=res.partner
next-core scaffold crud companies --model=res.partner --fields=name,email,phone,website
next-core scaffold crud deals --model=crm.lead
next-core scaffold crud activities --model=mail.activity

# Done! 16 pages generated in ~40 seconds
# Total: 13 demo pages + 16 generated = 29 working pages
pnpm dev
```

### Example 3: E-commerce Product Management

```bash
# 1. Create minimal app
next-core new my-shop --type=minimal --yes
cd my-shop

# 2. Configure Odoo

# 3. Scaffold product features
next-core scaffold crud products --model=product.product
next-core scaffold crud categories --model=product.category
next-core scaffold crud orders --model=sale.order

# 4. Generate custom pages
next-core generate page inventory --model=stock.quant --type=list
next-core generate page shipping --model=stock.picking --type=list

# Result: Complete e-commerce admin in minutes
pnpm dev
```

### Example 4: Explore Odoo Models First

```bash
# 1. Check available models
next-core odoo models --filter=product

# Output:
#   product.product          Product
#   product.template         Product Template
#   product.category         Product Category
#   product.pricelist        Pricelist

# 2. Inspect model fields
next-core odoo fields product.product

# Output: Shows 224 fields with types

# 3. Generate based on what you found
next-core scaffold crud products --model=product.product
```

### Example 5: Smart Code Generation with Packages ✨ NEW

```bash
# 1. Create new project
next-core new my-app --type=sfa --yes
cd my-app

# 2. Check available packages
next-core packages list

# Output:
#   📦 Next-Core Packages
#
#   Core Infrastructure:
#     client     ○ not installed    HTTP client...
#     odoo-api   ✓ installed        Odoo RPC client...
#
#   UI & Interaction:
#     ui         ○ not installed    50+ components + PWA tools...
#
#   Business Logic:
#     forms      ○ not installed    Dynamic form builder...
#     workflow   ○ not installed    Workflow engine...
#     analytics  ○ not installed    Analytics, dashboards...

# 3. Install analytics for data export
next-core packages add analytics

# Output:
#   ✓ Installing @kodeme-io/next-core-analytics@0.6.1
#   ✓ Package installed successfully!
#
#   💡 Next steps:
#   - Use ExportButton component in your list pages
#   - See examples: https://...

# 4. Generate CRUD - will now include ExportButton!
next-core scaffold crud products --model=product.product

# Output shows enhanced list page with export functionality:
#   ✅ /app/products/page.tsx (with ExportButton!)
#   ✅ /app/products/[id]/page.tsx
#   ✅ /app/products/[id]/edit/page.tsx
#   ✅ /app/products/new/page.tsx

# 5. Install forms package for better UX
next-core packages add forms

# 6. Generate another CRUD - will suggest DynamicForm!
next-core scaffold crud customers --model=res.partner

# Result: Smart code that adapts to your packages!
pnpm dev
```

---

## 🔄 Backwards Compatibility

The old `create-next-core` command still works:

```bash
npx create-next-core my-app --type=sfa
```

But we recommend using `next-core` for access to new features:

```bash
npx next-core new my-app --type=sfa
```

---

## 🛠️ Development Roadmap

### ✅ Phase 1: Foundation (Complete)
- [x] Rename to `@kodeme-io/next-core-cli`
- [x] Multi-command architecture
- [x] `next-core new` command
- [x] Backwards compatibility with `create-next-core`
- [x] 10 app types (SFA, LFA, Report, SCM, HRIS, B2B, Agri, Desk, Talent, Minimal)

### ✅ Phase 2: Page Generation (Complete)
- [x] `next-core generate page` command
- [x] Template system with 4 page types (list, detail, create, edit)
- [x] Odoo model introspection via RPC
- [x] Intelligent field analyzer (selects best 8 fields from 200+)
- [x] TypeScript type generation from Odoo fields
- [x] EntityCard props generator
- [x] `next-core odoo models` - List all models
- [x] `next-core odoo fields` - View model fields
- [x] `next-core odoo connect` - Test connection

### ✅ Phase 3: CRUD Scaffolding (Complete)
- [x] `next-core scaffold crud` command
- [x] Generate complete CRUD (4 pages) in 10 seconds
- [x] Automatic TypeScript interface generation
- [x] Search & filtering on list pages
- [x] Form validation on create/edit pages
- [x] Many2one field handling with display names
- [x] Selection field type unions

### ✅ Phase 4A: Package Management & Smart Code Generation (Complete)
- [x] `next-core packages list` - List all 16 next-core packages
- [x] `next-core packages info <package>` - View package details
- [x] `next-core packages add <packages...>` - Install packages with auto-dependencies
- [x] `next-core packages remove <packages...>` - Uninstall packages
- [x] `next-core packages upgrade` - Upgrade all packages to latest
- [x] `next-core packages doctor` - Health check & validation
- [x] Smart code generation - Detects installed packages and generates enhanced code
- [x] Package registry with 16 packages (ui, forms, workflow, analytics, auth, storage, etc.)
- [x] Automatic dependency resolution
- [x] Package manager detection (pnpm/yarn/npm)

### ✅ Phase 4B: Advanced V2 Features (Complete!)
- [x] `next-core watch` - Watch mode for live generation ✨
- [x] `next-core api generate` - Complete API route generation ✨
- [x] `next-core health` - Project health analysis & scoring ✨
- [x] Conflict detection & safe regeneration ✨
- [x] Real-time API generation with WebSocket support ✨
- [x] Advanced monitoring & error handling ✨
- [x] Auto-fix capabilities for common issues ✨
- [x] Comprehensive test coverage (1,000+ tests) ✨
- [x] Performance optimization & statistics ✨

### 🔜 Phase 4C-4F: Future Enhancements (Coming Soon)
- [ ] Custom templates support
- [ ] Form builder with drag & drop
- [ ] Dashboard scaffolding with charts
- [ ] Relationship management (one2many, many2many)
- [ ] Interactive mode with preview
- [ ] Bundle analysis & optimization
- [ ] Deployment automation
- [ ] AI-powered code suggestions

---

## 📖 Documentation

### V2 Features Guides
- [V2 Features Overview](./docs/V2_FEATURES.md) - Complete guide to all V2 features
- [CLI Reference Guide](./docs/CLI_REFERENCE.md) - Comprehensive command reference
- [Watch Mode Guide](./docs/WATCH_MODE.md) - Live code generation setup
- [API Generation Guide](./docs/API_GENERATION.md) - REST API creation
- [Health Check Guide](./docs/HEALTH_CHECK.md) - Project analysis & scoring

### General Documentation
- [Main Documentation](https://github.com/kodeme-io/next-core)
- [CLI Strategy Analysis](https://github.com/kodeme-io/next-core/blob/main/docs/CLI_STRATEGY_ANALYSIS.md)
- [Next.js Documentation](https://nextjs.org/docs)

---

## 🤝 Contributing

We welcome contributions! See our [Contributing Guide](../../CONTRIBUTING.md).

---

## 📄 License

MIT © ABC Food

---

**Built with ❤️ to make Odoo frontend development legendary**