create-theta-code 1.0.1

package/templates/mongo-js/README.md

@@ -0,0 +1,429 @@
+# Production-Grade Node.js API Boilerplate
+
+A secure, scalable, and production-ready Node.js API built with Express.js, MongoDB, and modern security practices. This boilerplate provides a solid foundation for building enterprise-grade REST APIs with authentication, authorization, rate limiting, and comprehensive error handling.
+
+## 🚀 Features
+
+### Core Architecture
+- **Express.js 4** - Fast, unopinionated web framework
+- **MongoDB + Mongoose** - NoSQL database with ODM
+- **ESM Modules** - Modern JavaScript module system
+- **Zod Validation** - Type-safe input validation
+- **JWT Authentication** - Secure token-based auth with refresh tokens
+- **Role-Based Access Control (RBAC)** - Admin/User permissions
+
+### Security & Hardening
+- **Helmet** - Security headers middleware
+- **CORS** - Configurable cross-origin resource sharing
+- **Rate Limiting** - Global and auth-specific rate limits
+- **bcryptjs** - Secure password hashing
+- **HTTP-Only Cookies** - Secure token storage
+- **Input Validation** - Comprehensive request validation
+- **Error Handling** - Centralized error management
+
+### Developer Experience
+- **ESLint + Prettier** - Code linting and formatting
+- **Vitest** - Fast unit and integration testing
+- **Nodemon** - Development auto-restart
+- **Morgan** - HTTP request logging (dev only)
+- **Request ID Tracing** - Correlation ID for debugging
+
+## 📋 Prerequisites
+
+- **Node.js** >= 18.0.0
+- **MongoDB** >= 4.0 (local or cloud instance)
+- **npm** or **yarn** package manager
+
+## 🛠️ Installation
+
+1. **Create a new project** using the CLI:
+   ```bash
+   npx create-theta-code my-api
+   cd my-api
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Environment Setup**:
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` with your configuration:
+   ```env
+   NODE_ENV=development
+   PORT=3000
+   MONGODB_URI=mongodb://localhost:27017/your-database
+   JWT_SECRET=your-super-secure-jwt-secret-min-32-chars
+   JWT_REFRESH_SECRET=your-super-secure-refresh-secret-min-32-chars
+   JWT_EXPIRES_IN=7d
+   JWT_REFRESH_EXPIRES_IN=30d
+   BCRYPT_SALT_ROUNDS=12
+   RATE_LIMIT_WINDOW_MS=900000
+   RATE_LIMIT_MAX=100
+   AUTH_RATE_LIMIT_MAX=10
+   CORS_ORIGIN=http://localhost:3000
+   LOG_LEVEL=info
+   ```
+
+4. **Start MongoDB** (if running locally):
+   ```bash
+   mongod
+   ```
+
+5. **Run the application**:
+   ```bash
+   # Development mode
+   npm run dev
+
+   # Production mode
+   npm start
+   ```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npx vitest
+```
+
+## 📚 API Documentation
+
+### Base URL
+```
+http://localhost:3000/api/v1
+```
+
+### Authentication
+All protected endpoints require a JWT token in the `Authorization` header or `accessToken` cookie.
+
+### Endpoints
+
+#### Health Check
+```http
+GET /health
+```
+Returns server health status (no authentication required).
+
+**Response:**
+```json
+{
+  "status": "UP",
+  "environment": "development",
+  "uptime": 123.456,
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "memory": {
+    "rss": 12345678,
+    "heapTotal": 1234567,
+    "heapUsed": 987654,
+    "external": 12345
+  }
+}
+```
+
+#### User Registration
+```http
+POST /api/v1/users/register
+```
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "password": "SecurePass123!"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "User registered successfully",
+  "data": {
+    "user": {
+      "_id": "...",
+      "email": "user@example.com",
+      "firstName": "John",
+      "lastName": "Doe",
+      "role": "user",
+      "isActive": true,
+      "createdAt": "2024-01-01T00:00:00.000Z",
+      "updatedAt": "2024-01-01T00:00:00.000Z"
+    }
+  },
+  "timestamp": "2024-01-01T00:00:00.000Z"
+}
+```
+
+#### User Login
+```http
+POST /api/v1/users/login
+```
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Login successful",
+  "data": {
+    "user": {
+      "_id": "...",
+      "email": "user@example.com",
+      "firstName": "John",
+      "lastName": "Doe",
+      "role": "user",
+      "isActive": true,
+      "createdAt": "2024-01-01T00:00:00.000Z",
+      "updatedAt": "2024-01-01T00:00:00.000Z"
+    }
+  },
+  "timestamp": "2024-01-01T00:00:00.000Z"
+}
+```
+
+**Note:** Sets `accessToken` and `refreshToken` HTTP-only cookies.
+
+#### Get User Profile
+```http
+GET /api/v1/users/profile
+```
+**Auth Required:** Bearer token or cookie
+
+#### Update User Profile
+```http
+PUT /api/v1/users/profile
+```
+**Auth Required:** Bearer token or cookie
+
+**Request Body:**
+```json
+{
+  "firstName": "Jane",
+  "lastName": "Smith"
+}
+```
+
+#### Get All Users (Admin Only)
+```http
+GET /api/v1/users/users?limit=10&skip=0
+```
+**Auth Required:** Bearer token or cookie + Admin role
+
+**Query Parameters:**
+- `limit` (optional): Number of users to return (max 100, default 10)
+- `skip` (optional): Number of users to skip (default 0)
+
+#### Logout
+```http
+POST /api/v1/users/logout
+```
+**Auth Required:** Bearer token or cookie
+
+Clears authentication cookies.
+
+#### Delete Account
+```http
+DELETE /api/v1/users/account
+```
+**Auth Required:** Bearer token or cookie
+
+## 🏗️ Project Structure
+
+```
+├── bin/
+│   └── create.js                 # CLI script for project generation
+├── src/
+│   ├── config/
+│   │   ├── app.config.js         # Express app factory & middleware
+│   │   ├── db.config.js          # MongoDB connection
+│   │   ├── env.config.js         # Environment validation (Zod)
+│   │   └── rateLimiter.config.js # Rate limiting configuration
+│   ├── middlewares/
+│   │   ├── auth.middleware.js    # JWT authentication
+│   │   ├── error.middleware.js   # Global error handling
+│   │   ├── notFound.middleware.js # 404 handler
+│   │   ├── requestId.middleware.js # Request correlation ID
+│   │   ├── requireRole.middleware.js # RBAC guard
+│   │   └── validate.middleware.js # Input validation
+│   ├── modules/
+│   │   └── user/
+│   │       ├── user.controller.js # HTTP handlers
+│   │       ├── user.model.js      # Mongoose schema
+│   │       ├── user.repository.js # Data access layer
+│   │       ├── user.routes.js     # Route definitions
+│   │       ├── user.service.js    # Business logic
+│   │       └── user.validator.js  # Input validation schemas
+│   └── utils/
+│       ├── AppError.js           # Custom error class
+│       ├── apiResponse.js        # Response formatting
+│       ├── asyncHandler.js       # Async error wrapper
+│       ├── constants.js          # Application constants
+│       └── jwt.utils.js          # JWT utilities
+├── tests/
+│   ├── integration/
+│   │   └── user.routes.test.js   # API integration tests
+│   └── unit/
+│       └── user.service.test.js  # Unit tests
+├── .env.example                  # Environment template
+├── .gitignore                    # Git ignore rules
+├── package.json                  # Dependencies & scripts
+├── README.md                     # This file
+└── server.js                     # Application entry point
+```
+
+## 🔒 Security Features
+
+### Authentication & Authorization
+- **JWT Tokens**: Access and refresh tokens with configurable expiration
+- **HTTP-Only Cookies**: Secure token storage, XSS protection
+- **Password Hashing**: bcryptjs with configurable salt rounds
+- **Role-Based Access**: Admin/User roles with middleware guards
+
+### Input Validation & Sanitization
+- **Zod Schemas**: Type-safe validation for all inputs
+- **Request Size Limits**: 10KB limit on JSON payloads
+- **SQL Injection Protection**: Parameterized queries via Mongoose
+
+### Rate Limiting
+- **Global Limits**: 100 requests per 15 minutes per IP
+- **Auth Limits**: 10 login attempts per 15 minutes per IP
+- **Custom Messages**: Consistent error response format
+
+### Security Headers
+- **Helmet**: Comprehensive security headers
+- **CORS**: Configurable origin allowlist
+- **HSTS**: HTTP Strict Transport Security (production)
+
+### Error Handling
+- **No Data Leaks**: Sensitive information never exposed
+- **Consistent Format**: All errors follow API response schema
+- **Logging**: Request correlation IDs for debugging
+
+## 🧪 Testing Strategy
+
+### Unit Tests
+- **Service Layer**: Business logic testing with mocked repositories
+- **Middleware**: Authentication, validation, and error handling
+- **Utilities**: JWT, password hashing, and response formatting
+
+### Integration Tests
+- **API Endpoints**: Full request/response cycle testing
+- **Database Operations**: Real database interactions (test DB)
+- **Middleware Chain**: Authentication, validation, and rate limiting
+
+### Test Coverage
+- **Vitest**: Fast, ESM-compatible test runner
+- **Supertest**: HTTP endpoint testing
+- **Coverage Reports**: Detailed coverage analysis
+
+## 🚀 Deployment
+
+### Environment Variables
+Ensure all required environment variables are set in production:
+
+```bash
+NODE_ENV=production
+PORT=3000
+MONGODB_URI=mongodb://username:password@host:port/database
+JWT_SECRET=your-production-jwt-secret
+JWT_REFRESH_SECRET=your-production-refresh-secret
+CORS_ORIGIN=https://yourdomain.com
+```
+
+### Production Checklist
+- [ ] Set `NODE_ENV=production`
+- [ ] Use strong, unique JWT secrets (min 32 characters)
+- [ ] Configure production MongoDB URI
+- [ ] Set secure CORS origins
+- [ ] Enable HTTPS/SSL
+- [ ] Set up monitoring and logging
+- [ ] Configure rate limits appropriately
+- [ ] Set up database backups
+- [ ] Configure firewall rules
+
+### Docker Support (Optional)
+Add a `Dockerfile` and `docker-compose.yml` for containerized deployment:
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+## 📈 Performance Considerations
+
+### Database Optimization
+- **Indexes**: Create indexes on frequently queried fields
+- **Connection Pooling**: MongoDB connection pooling enabled
+- **Query Optimization**: Use Mongoose's built-in query optimization
+
+### Caching Strategy
+- **Response Caching**: Implement Redis for frequently accessed data
+- **Token Caching**: Cache JWT validation results
+- **Rate Limit Caching**: Use Redis for distributed rate limiting
+
+### Monitoring
+- **Health Checks**: `/health` endpoint for load balancer monitoring
+- **Request Tracing**: Correlation IDs for distributed tracing
+- **Performance Metrics**: Response times, error rates, throughput
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Guidelines
+- Follow ESLint configuration
+- Write tests for new features
+- Update documentation as needed
+- Use conventional commit messages
+- Ensure all tests pass before submitting PR
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [Express.js](https://expressjs.com/) - Web framework
+- [MongoDB](https://www.mongodb.com/) - NoSQL database
+- [Mongoose](https://mongoosejs.com/) - MongoDB ODM
+- [JWT.io](https://jwt.io/) - JSON Web Tokens
+- [Zod](https://zod.dev/) - TypeScript-first schema validation
+
+## 📞 Support
+
+For questions or issues:
+- Create an issue on GitHub
+- Check the documentation
+- Review existing issues and solutions
+
+---
+
+**Built with ❤️ for production-ready Node.js APIs**

package/templates/mongo-js/_env.example

@@ -0,0 +1,13 @@
+NODE_ENV=development
+PORT=3000
+MONGODB_URI=mongodb://localhost:27017/theta-app
+JWT_SECRET=your-super-secret-jwt-key-min-32-characters-required
+JWT_REFRESH_SECRET=your-super-secret-refresh-key-min-32-characters-required
+JWT_EXPIRES_IN=7d
+JWT_REFRESH_EXPIRES_IN=30d
+BCRYPT_SALT_ROUNDS=12
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX=100
+AUTH_RATE_LIMIT_MAX=10
+CORS_ORIGIN=http://localhost:3000
+LOG_LEVEL=info

package/templates/mongo-js/_gitignore

@@ -0,0 +1,22 @@
+node_modules/
+.env
+dist/
+build/
+coverage/
+.nyc_output/
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.cache/
+.env.local
+.env.*.local
+.env.test