@diagramers/cli/README.md

Diagramers CLI - Command-line tools for managing Diagramers projects

# Diagramers CLI

A powerful command-line interface for managing Diagramers projects, generating modules, and extending functionality with a comprehensive template system.

## 🚀 Features

### Core Capabilities
- **Project Initialization** - Create new projects from templates
- **Module Generation** - Generate complete modules with CRUD operations
- **Database Schema Generation** - Create tables and collections
- **Relation Management** - Generate database relations and references
- **Feature Extension** - Add features to existing projects
- **Template Management** - Download and update project templates

### Supported Templates
- **API Projects** - Full-featured Node.js API with TypeScript
- **Admin Projects** - Admin dashboard and management interfaces
- **Custom Templates** - Extensible template system

### Database Support
- **MongoDB** - Primary database with Mongoose schemas
- **SQL Databases** - MySQL, PostgreSQL, SQLite support
- **Schema Generation** - Automatic schema and relation creation

## 📦 Installation

### Global Installation
```bash
npm install -g @diagramers/cli
```

### Local Installation
```bash
npm install @diagramers/cli
npx diagramers --help
```

## 🚀 Quick Start

```bash
# Install the CLI globally
npm install -g @diagramers/cli

# Create a new API project
diagramers init api my-new-api

# Navigate to the project
cd my-new-api

# Set up environment variables
cp env.example .env.development
echo "NODE_ENV=development" >> .env.development

# Start development server
npm start
```

## 🛠️ Usage

### Initialize New Project
```bash
# Initialize new API project
diagramers init api my-api-project

# Initialize new admin project
diagramers init admin my-admin-project

# Initialize with specific template version
diagramers init api my-project --template 1.0.0

# Skip prompts and use defaults
diagramers init api my-project --yes
```

**Important:** After initializing a project, remember to:
1. Copy `env.example` to `.env.development`
2. Set `NODE_ENV=development` in `.env.development`
3. Configure your database and other environment variables

### Generate Modules
```bash
# Generate basic module
diagramers extend --module products

# Generate module with CRUD operations
diagramers extend --module orders --crud

# Generate module with custom fields
diagramers extend --module categories --fields name,description,slug

# Generate module with specific database type
diagramers extend --module users --type mongodb --fields email,username,role
```

### Generate Database Schemas
```bash
# Generate MongoDB collection
diagramers extend --table products --fields name,price,description

# Generate SQL table
diagramers extend --table orders --type mysql --fields customer_id,amount,status

# Generate PostgreSQL table
diagramers extend --table categories --type postgres --fields name,slug,parent_id
```

### Generate Database Relations
```bash
# Generate MongoDB relations
diagramers extend --relation user-posts --type mongodb

# Generate SQL relations
diagramers extend --relation product-categories --type mysql
```

### Add Features
```bash
# Add authentication feature
diagramers extend --feature auth

# Add email notification feature
diagramers extend --feature email

# Add WebSocket feature
diagramers extend --feature socket

# Add scheduled tasks feature
diagramers extend --feature cron

# Add audit logging feature
diagramers extend --feature audit
```

### List Available Options
```bash
# List all available features and templates
diagramers extend --list
```

### Update Projects
```bash
# Update project structure
diagramers update

# Update with specific version
diagramers update --version 1.0.0
```

## 📁 Generated Module Structure

When you generate a module, the CLI creates a complete structure:

```
src/modules/your-module/
├── entities/
│   └── your-module.entity.ts      # TypeScript interfaces
├── schemas/
│   └── your-module.schema.ts      # Database schemas
├── services/
│   └── your-module.service.ts     # Business logic
├── controllers/
│   └── your-module.controller.ts  # HTTP handlers
└── routes/
    └── your-module.routes.ts      # API routes
```

### Generated Files Include:
- **Entities** - TypeScript interfaces with CRUD operations
- **Schemas** - Database schemas with validation and indexes
- **Services** - Business logic with Result model integration
- **Controllers** - HTTP handlers with Swagger documentation
- **Routes** - Express routes with proper binding

## 🔧 Configuration

### Template Configuration
The CLI uses npm packages for templates:
- `@diagramers/api` - API project template
- `@diagramers/admin` - Admin project template

### Custom Templates
You can create custom templates by:
1. Creating a package with the template structure
2. Publishing to npm with `@diagramers/` prefix
3. Using the template with `--template` flag

## 📋 Available Features

### Authentication Features
- **Internal Auth** - Username/password with JWT
- **Firebase Auth** - Google Firebase integration
- **OAuth Providers** - Google, GitHub, Facebook
- **SMS OTP** - Twilio, AWS SNS integration
- **Email OTP** - Email-based verification

### Communication Features
- **Email System** - Nodemailer with templates
- **SMS System** - Twilio integration
- **WebSocket** - Real-time communication
- **Push Notifications** - Firebase messaging

### System Features
- **Cron Jobs** - Scheduled task system
- **Audit Logging** - Activity tracking
- **File Upload** - File management system
- **Caching** - Redis integration

## 🗄️ Database Support

### MongoDB (Default)
```bash
# Generate MongoDB collection
diagramers extend --table products --type mongodb --fields name,price,category
```

### SQL Databases
```bash
# MySQL table
diagramers extend --table orders --type mysql --fields customer_id,amount,status

# PostgreSQL table
diagramers extend --table users --type postgres --fields email,username,role

# SQLite table
diagramers extend --table settings --type sqlite --fields key,value
```

### Relations
```bash
# One-to-Many relations
diagramers extend --relation user-posts --type mongodb

# Many-to-Many relations
diagramers extend --relation product-categories --type mysql
```

## 🔌 Plugin System

The CLI supports plugin generation for extending functionality:

### Generate Plugin
```bash
# Generate plugin structure
diagramers extend --plugin my-plugin

# Generate plugin with configuration
diagramers extend --plugin payment-gateway --config stripe,paypal
```

## 📚 Examples

### Complete E-commerce Module
```bash
# Generate products module
diagramers extend --module products --crud --fields name,price,description,category,stock

# Generate orders module
diagramers extend --module orders --crud --fields customer_id,products,total,status

# Generate categories module
diagramers extend --module categories --crud --fields name,description,parent_id

# Generate relations
diagramers extend --relation product-category --type mongodb
diagramers extend --relation order-product --type mongodb
```

### User Management System
```bash
# Generate users module
diagramers extend --module users --crud --fields email,username,role,status

# Generate profiles module
diagramers extend --module profiles --crud --fields user_id,first_name,last_name,avatar

# Generate permissions module
diagramers extend --module permissions --crud --fields name,description,resource

# Generate relations
diagramers extend --relation user-profile --type mongodb
diagramers extend --relation user-permissions --type mongodb
```

## 🚀 Advanced Usage

### Custom Field Types
```bash
# Generate with different field types
diagramers extend --module products --fields name:string,price:number,active:boolean,created:date
```

### Nested Modules
```bash
# Generate nested module structure
diagramers extend --module admin/users --crud --fields email,role,permissions
```

### API Documentation
```bash
# Generate with enhanced Swagger docs
diagramers extend --module api/products --crud --swagger --fields name,price,description
```

## 🔧 Development

### Local Development
```bash
# Clone the repository
git clone https://github.com/diagramers/diagramers-cli.git
cd diagramers-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link
```

### Testing
```bash
# Run tests
npm test

# Run with coverage
npm run test:coverage
```

## 📄 License

This project is licensed under the MIT License.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

For support and questions:
- 📖 Check the documentation
- 🐛 Open an issue on GitHub
- 💬 Join our community discussions
- 📧 Contact: support@diagramers.com

## 🔗 Related Packages

- **@diagramers/api** - API framework and template
- **@diagramers/admin** - Admin dashboard template
- **@diagramers/shared** - Shared utilities and types