@asad_dev/leo-generator 1.6.0

package/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+All notable changes to Leo Generate will be documented in this file.
+
+## [1.6.0] - 2025-12-28
+
+### 🌟 New: Asynchronous File Cleanup
+- **Enhanced `removeFile` Helper**: Replaced synchronous cleanup logic with a robust asynchronous implementation using `fs/promises`.
+- **Intelligent Path Normalization**: Automatically strips `/images/` prefixes and handles absolute/relative paths correctly.
+- **Improved Reliability**: Added specific error handling for missing files (`ENOENT`) to prevent process crashes.
+
+### 🛡️ Core Improvements
+- **Async Service Templates**: Updated generated service templates to `await` file removal operations, ensuring data consistency.
+- **Environment Detection**: Improved `.env` loading to prioritize Postman API keys and Collection IDs for automated syncing.
+- **Enhanced `--skip` Logic**: Refined file skipping mechanism to allow bypassing any file type (interface, model, constants, etc.) during generation.
+
+### 🔧 Fixes
+- **Module Dependency Fix**: Resolved `MODULE_NOT_FOUND` errors by ensuring proper dependency installation and build synchronization.
+
+---
+
+## [1.5.0] - 2025-12-20
+
+### 🚀 Major Feature: Automated Postman Cloud Sync
+
+#### Added
+- **Automated Postman Collection Import**: Automatically sync generated API collections to Postman Cloud
+  - Configure via `.env`, `package.json`, or CLI flags
+  - Supports `POSTMAN_API_KEY` and `POSTMAN_COLLECTION_ID`
+  - Seamlessly integrates with existing local file generation
+- **Smart Collection Merging**: Intelligently updates or adds module folders in existing collections
+- **Sequential Processing**: Prevents race conditions when updating multiple modules
+- **Variable Sanitization**: Automatically fixes invalid Postman variable types
+
+#### Enhanced
+- **update-docs Command**: Now supports automated Postman Cloud sync
+  - Properly detects TypeScript enum definitions and their values
+  - Correctly identifies changes to nested object properties
+  - Generates accurate Postman pre-request scripts with enum value arrays
+- **Enum Detection**: Enhanced field extraction to recognize TypeScript `enum` types
+- **Error Handling**: Graceful handling of API errors without breaking module generation
+
+#### Fixed
+- **Postman API Variable Type Error**: Fixed validation errors caused by invalid variable types
+- **Race Condition**: Fixed concurrent API update conflicts in `update-docs`
+- **Enum Value Detection**: Now properly extracts enum values from interface files
+
+---
+
+## [1.4.0] - 2025-12-18
+
+### 🚀 Major Enhancements
+- **Enhanced Enum Support**: Now uses TypeScript Enums (`export enum StatusEnum {...}`) instead of string unions, with proper validation using `z.nativeEnum` and Mongoose `Object.values`.
+- **File Removal Support**: Added `--file:true` flag. When used, automatically:
+  - Generates a `fileHelper` utility for removing uploaded files.
+  - Adds cleanup logic to the delete service to remove associated files (images/media) when a record is deleted.
+- **Smart Postman Scripts**: Pre-request scripts now auto-generate dynamic values for request bodies (e.g., timestamps, random numbers, random enum values), making testing easier.
+- **Nested Schema Fixes**: Improved nested schema generation order to ensure dependencies are defined before use.
+
+---
+
+## [1.3.1] - 2025-08-07
+
+### 🔧 Bug Fixes
+- **CLI Version**: Fixed hardcoded version display in CLI to match package.json version
+
+---
+
+## [1.3.0] - 2025-08-06
+
+### 🏭 Production-Ready Templates
+
+#### Updated Templates to Match Production Patterns
+- **Service Template**: Now includes `JwtPayload user` parameter, proper pagination with `paginationHelper`, advanced search and filtering
+- **Controller Template**: Updated with `req.user!` authentication, file handling for `images/media`, proper request structure
+- **Route Template**: Added comprehensive auth middleware, role-based access control, file upload middleware integration
+- **Constants Template**: Auto-generates filterable and searchable fields based on field types
+- **Interface Template**: Auto-generates `IModuleFilterables` interface for type-safe filtering
+
+#### Enhanced Features
+- **Role-Based Access Control**: Routes now include proper auth middleware with USER_ROLES
+- **Advanced Pagination**: Integrated with `paginationHelper.calculatePagination()`
+- **Search & Filter**: Automatic generation of searchable and filterable fields
+- **File Upload Support**: Proper handling of `images` and `media` fields with middleware
+- **Type Safety**: Enhanced interfaces with filter types for better TypeScript support
+
+#### Production Patterns
+- **Authentication**: All routes protected with role-based auth middleware
+- **Error Handling**: Enhanced error handling with proper status codes
+- **Validation**: Integrated request validation with Zod schemas
+- **Response Structure**: Consistent API response patterns
+- **Code Organization**: Follows production-grade folder and file structure
+
+---
+
+## [1.2.0] - 2025-08-06
+
+### 🧠 Enhanced Documentation Intelligence
+
+#### Added
+- **Code-Aware Documentation Updates**: System now reads both interface and model files for complete accuracy
+- **Smart Field Extraction**: Enhanced parsing that handles complex nested structures and type mappings
+- **Enum Value Detection**: Automatically extracts actual enum values from Mongoose schemas
+- **Array Type Intelligence**: Generates proper sample data for all array types (string[], number[], boolean[], etc.)
+- **100% Syntax Support**: Now handles every field type the generator can create
+- **Robust Interface Parsing**: Correctly identifies main interfaces vs nested interfaces
+
+#### Improved
+- **Postman Collection Generation**: Now generates type-appropriate sample data
+  - `scores:array:number` → `"scores": [123]` (was `["sample_scores_item"]`)
+  - `flags:array:boolean` → `"flags": [true]` (was `["sample_flags_item"]`)
+  - `status:enum[active,inactive]` → `"status": "active"` (was `"status": "sample_status"`)
+- **Swagger Documentation**: Enhanced schema generation with proper type definitions
+- **Field Type Detection**: More accurate mapping of TypeScript types to field definitions
+- **Nested Object Support**: Better handling of complex array-of-object structures
+
+#### Fixed
+- **Documentation Sync Issues**: Updates now accurately reflect code changes
+- **Array Type Parsing**: Fixed incorrect sample data generation for typed arrays
+- **Enum Value Extraction**: Now properly extracts enum values from model files
+- **Interface Detection**: Improved logic to find main interface vs helper interfaces
+
+### 📊 Technical Improvements
+
+#### Enhanced Parsing Logic
+- Improved regex patterns for interface and model file parsing
+- Better handling of multiline field definitions
+- Enhanced type mapping for complex structures
+- Robust error handling and fallback mechanisms
+
+#### Sample Data Generation
+- Type-aware sample data for all field types
+- Proper ObjectId string generation for references
+- Realistic enum value selection from actual schema definitions
+- Correct nested object structure preservation
+
+### 🔧 Developer Experience
+
+#### Better Feedback
+- Detailed logging showing exactly which fields are extracted
+- Clear indication of interface and model file processing
+- Progress reporting during bulk documentation updates
+
+#### Reliability
+- More robust parsing that handles edge cases
+- Better error messages for troubleshooting
+- Fallback mechanisms for incomplete type information
+
+---
+
+## [1.1.0] - 2025-08-05
+
+### 🚀 Major Feature Release
+
+#### Added
+- **Complex/Nested Fields Support**: Arrays of objects, nested structures, references
+- **Production-Ready CRUD Operations**: Enhanced controllers and services with pagination
+- **Postman Integration**: Automatic API collection generation
+- **Swagger Integration**: OpenAPI 3.0 documentation generation
+- **Bulk Documentation Updates**: Update docs for all existing modules
+
+#### Enhanced
+- **Field Type Support**: Comprehensive support for all data types
+- **CLI Interface**: New command structure with aliases
+- **Error Handling**: Improved error messages and validation
+- **Code Generation**: More robust and production-ready templates
+
+---
+
+## [1.0.0] - 2025-08-04
+
+### 🎉 Initial Release
+
+#### Core Features
+- Basic module generation with TypeScript support
+- Mongoose model creation
+- Express controller and service generation
+- RESTful route setup
+- Zod validation schemas
+- Basic field type support
+
+#### Supported Field Types
+- Basic types: string, number, boolean, date
+- ObjectId references
+- Simple arrays
+- Basic enum support
+
+---
+
+## Version Numbering
+
+- **Major** (x.0.0): Breaking changes or major new features
+- **Minor** (1.x.0): New features, backward compatible
+- **Patch** (1.1.x): Bug fixes, backward compatible

package/COMMAND_REFERENCE.md

@@ -0,0 +1,412 @@
+# 📚 Leo Generate - Complete Command Reference
+
+## 🚀 **Package Information**
+- **Package Name**: `@asad_dev/leo-generator`
+- **Version**: `1.6.0`
+- **Binary**: `leo-generate`
+
+## 📋 **All Available Commands**
+
+### **1. Module Generation Commands**
+
+#### **Primary Command: `generate` (Recommended)**
+```bash
+leo-generate generate <ModuleName> [field1:type] [field2:type] [...options]
+```
+
+**Alias**: `g`
+```bash
+leo-generate g <ModuleName> [field1:type] [field2:type] [...options]
+```
+
+**Examples**:
+```bash
+# Basic module
+leo-generate generate User name:string email:string age:number
+
+# With alias
+leo-generate g Product name:string price:number
+
+# Complex nested structures
+leo-generate generate Order \
+  customer:objectid:User \
+  items:array:object:name:string:price:number:quantity:number \
+  status:enum[pending,processing,shipped,delivered] \
+  shippingAddress:object:street:string:city:string:zipCode:string \
+  totalAmount:number
+
+# With required fields
+leo-generate generate User name!:string email!:string age:number
+
+# With optional fields
+leo-generate generate Post title:string content:string author?:string
+```
+
+#### **Legacy Command (Backward Compatibility)**
+```bash
+leo-generate <ModuleName> [field1:type] [field2:type] [...options]
+```
+
+**Examples**:
+```bash
+# Legacy syntax (still works)
+leo-generate User name:string email:string age:number
+leo-generate Product name:string price:number category:enum[Electronics,Clothing]
+```
+
+### **2. Smart Documentation Update Commands**
+
+#### **Intelligent Documentation Updates**
+```bash
+leo-generate update-docs [options]
+```
+
+**Alias**: `docs`
+```bash
+leo-generate docs [options]
+```
+
+**Enhanced Features (v1.2.0)**:
+- 🧠 **Code-Aware Analysis**: Reads both interface and model files
+- 🔍 **Smart Field Extraction**: Handles complex nested structures
+- 📊 **Accurate Sample Data**: Type-appropriate values for all field types
+- 🎯 **Enum Value Detection**: Uses actual enum values from schemas
+- ✅ **100% Syntax Support**: Handles every field type the generator creates
+
+**Examples**:
+```bash
+# Update both Postman and Swagger for all modules
+leo-generate update-docs
+
+# Using alias
+leo-generate docs
+
+# Update only Postman collections
+leo-generate update-docs --no-swagger
+
+# Update only Swagger documentation
+leo-generate update-docs --no-postman
+
+# Custom directories
+leo-generate update-docs \
+  --modules-dir src/modules \
+  --postman-dir api-collections \
+  --swagger-file docs/api-spec.json
+```
+
+### **3. Help and Version Commands**
+
+#### **Help**
+```bash
+leo-generate --help
+leo-generate generate --help
+leo-generate update-docs --help
+```
+
+#### **Version**
+```bash
+leo-generate --version
+```
+
+## ⚙️ **Command Options**
+
+### **Generate Command Options**
+
+| Option | Description | Default | Example |
+|--------|-------------|---------|---------|
+| `-c, --config <path>` | Path to custom config file | - | `--config ./custom-config.json` |
+| `--modules-dir <path>` | Path to modules directory | `src/app/modules` | `--modules-dir src/modules` |
+| `--routes-file <path>` | Path to routes file | `src/routes/index.ts` | `--routes-file src/routes.ts` |
+| `--no-postman` | Skip Postman collection generation | false | `--no-postman` |
+| `--no-swagger` | Skip Swagger documentation generation | false | `--no-swagger` |
+| `--postman-dir <path>` | Custom Postman output directory | `postman` | `--postman-dir collections` |
+| `--swagger-file <path>` | Custom Swagger file path | `swagger.json` | `--swagger-file api-docs.json` |
+| `--file:true` | Enable file upload support (async cleanup) | false | `--file:true` |
+| `--skip <files...>` | Skip specific file types | - | `--skip interface model constants` |
+
+### **Update-Docs Command Options**
+
+| Option | Description | Default | Example |
+|--------|-------------|---------|---------|
+| `--modules-dir <path>` | Path to modules directory | `src/app/modules` | `--modules-dir src/modules` |
+| `--no-postman` | Skip Postman collection generation | false | `--no-postman` |
+| `--no-swagger` | Skip Swagger documentation generation | false | `--no-swagger` |
+| `--postman-dir <path>` | Custom Postman output directory | `postman` | `--postman-dir collections` |
+| `--swagger-file <path>` | Custom Swagger file path | `swagger.json` | `--swagger-file api-spec.json` |
+
+## 🏗️ **Field Type Syntax**
+
+### **Basic Types**
+```bash
+name:string          # String field
+age:number           # Number field
+isActive:boolean     # Boolean field
+createdAt:date       # Date field
+```
+
+### **Field Modifiers**
+```bash
+name!:string         # Required field (!)
+email?:string        # Optional field (?)
+```
+
+### **Enum Fields**
+```bash
+status:enum[active,inactive,pending]
+role:enum[admin,user,moderator]
+category:enum[Electronics,Clothing,Books,Home]
+```
+
+### **Reference Fields**
+```bash
+author:objectid:User              # Single ObjectId reference
+categories:array:objectid:Category # Array of ObjectId references
+```
+
+### **Complex Nested Structures**
+
+#### **Array of Objects**
+```bash
+items:array:object:name:string:price:number:quantity:number
+variants:array:object:size:string:color:string:stock:number
+```
+
+#### **Nested Objects**
+```bash
+address:object:street:string:city:string:country:string:zipCode:string
+profile:object:firstName:string:lastName:string:bio:string
+```
+
+#### **Mixed Arrays**
+```bash
+tags:array:string           # Array of strings
+scores:array:number         # Array of numbers
+flags:array:boolean         # Array of booleans
+```
+
+## 📁 **Generated File Structure**
+
+### **Module Files Created**
+```
+src/app/modules/{modulename}/
+├── {modulename}.interface.ts    # TypeScript interfaces
+├── {modulename}.model.ts       # Mongoose schema
+├── {modulename}.controller.ts  # Express controllers
+├── {modulename}.service.ts     # Business logic
+├── {modulename}.route.ts       # Express routes
+├── {modulename}.validation.ts  # Zod validation
+└── {modulename}.constants.ts   # Constants
+```
+
+### **Documentation Files Created**
+```
+postman/
+└── {modulename}.postman_collection.json  # Postman collection
+
+swagger.json                               # OpenAPI 3.0 specification
+```
+
+### **Updated Files**
+```
+src/routes/index.ts                        # Auto-updated with new routes
+```
+
+## 🎯 **Complete Usage Examples**
+
+### **E-commerce System**
+
+#### **User Module**
+```bash
+leo-generate generate User \
+  name!:string \
+  email!:string \
+  password!:string \
+  role:enum[admin,user,customer] \
+  profile:object:firstName:string:lastName:string:phone:string \
+  isActive:boolean \
+  lastLogin?:date
+```
+
+#### **Product Module**
+```bash
+leo-generate generate Product \
+  name!:string \
+  description:string \
+  price!:number \
+  category:enum[Electronics,Clothing,Books,Home] \
+  variants:array:object:size:string:color:string:price:number:stock:number \
+  images:array:string \
+  tags:array:string \
+  isActive:boolean \
+  vendor:objectid:User
+```
+
+#### **Order Module**
+```bash
+leo-generate generate Order \
+  customer:objectid:User \
+  items:array:object:productId:objectid:Product:quantity:number:price:number \
+  status:enum[pending,processing,shipped,delivered,cancelled] \
+  shippingAddress:object:street:string:city:string:state:string:zipCode:string:country:string \
+  billingAddress:object:street:string:city:string:state:string:zipCode:string:country:string \
+  totalAmount!:number \
+  paymentStatus:enum[pending,paid,failed,refunded] \
+  orderDate:date \
+  deliveryDate?:date
+```
+
+### **Blog System**
+
+#### **Post Module**
+```bash
+leo-generate generate Post \
+  title!:string \
+  content!:string \
+  excerpt:string \
+  author:objectid:User \
+  category:objectid:Category \
+  tags:array:string \
+  status:enum[draft,published,archived] \
+  publishedAt?:date \
+  viewCount:number \
+  likes:array:objectid:User \
+  comments:array:object:author:objectid:User:content:string:createdAt:date
+```
+
+#### **Category Module**
+```bash
+leo-generate generate Category \
+  name!:string \
+  slug!:string \
+  description:string \
+  parent?:objectid:Category \
+  isActive:boolean
+```
+
+### **File Upload Module**
+```bash
+leo-generate generate Media \
+  title:string \
+  description:string \
+  filename!:string \
+  originalName:string \
+  mimeType:string \
+  size:number \
+  path:string \
+  uploadedBy:objectid:User \
+  isPublic:boolean
+```
+
+## 🔄 **Workflow Commands**
+
+### **Development Workflow**
+```bash
+# 1. Generate new module
+leo-generate generate User name:string email:string
+
+# 2. Update documentation after code changes
+leo-generate update-docs
+
+# 3. Generate another module
+leo-generate generate Product name:string price:number
+
+# 4. Update all documentation
+leo-generate docs
+```
+
+### **Team Workflow**
+```bash
+# Team member 1: Creates user module
+leo-generate generate User name:string email:string role:enum[admin,user]
+
+# Team member 2: Creates product module
+leo-generate generate Product name:string price:number category:string
+
+# Team lead: Updates all documentation
+leo-generate update-docs --postman-dir team-collections
+```
+
+### **CI/CD Integration**
+```bash
+# In CI/CD pipeline
+leo-generate update-docs --no-postman  # Only update Swagger for API docs
+```
+
+## 🛠️ **Configuration Options**
+
+### **Via package.json**
+```json
+{
+  "moduleGenerator": {
+    "modulesDir": "src/app/modules",
+    "routesFile": "src/routes/index.ts"
+  }
+}
+```
+
+### **Via CLI Options**
+```bash
+leo-generate generate User name:string \
+  --modules-dir src/modules \
+  --routes-file src/routes.ts \
+  --postman-dir collections \
+  --swagger-file docs/api.json
+```
+
+## 🚨 **Skip File Generation**
+
+### **Skip Specific Files**
+```bash
+# Skip specific file types during generation
+leo-generate generate User name:string email:string --skip controller service
+```
+
+### **Skip Documentation**
+```bash
+# Skip Postman collection generation
+leo-generate generate User name:string --no-postman
+
+# Skip Swagger documentation generation
+leo-generate generate User name:string --no-swagger
+
+# Skip both
+leo-generate generate User name:string --no-postman --no-swagger
+```
+
+## 📊 **Command Summary**
+
+| Command | Purpose | Output |
+|---------|---------|--------|
+| `generate <name> [fields...]` | Create new module with documentation | Module files + Postman + Swagger |
+| `g <name> [fields...]` | Alias for generate | Same as generate |
+| `<name> [fields...]` | Legacy syntax | Same as generate |
+| `update-docs` | Update all module documentation | Updated Postman + Swagger |
+| `docs` | Alias for update-docs | Same as update-docs |
+| `--help` | Show help information | Help text |
+| `--version` | Show version information | Version number |
+
+## 🎉 **Quick Start Commands**
+
+```bash
+# Install globally
+npm install -g @asad_dev/leo-generator
+
+# Generate your first module
+leo-generate generate User name:string email:string age:number
+
+# Check what was created
+ls src/app/modules/user/
+ls postman/
+cat swagger.json
+
+# Update documentation
+leo-generate update-docs
+
+# Generate complex module
+leo-generate generate Order \
+  customer:objectid:User \
+  items:array:object:name:string:price:number \
+  status:enum[pending,shipped]
+```
+
+This comprehensive command reference covers all the functionality available in your enhanced Leo Generate package! 🚀