@forgedevstack/harbor 1.0.0

package/templates/default/README.md

@@ -0,0 +1,97 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+Built with [Harbor](https://github.com/yaghobieh/Harbor) - The pipeline for Node.js backends.
+
+## Features
+
+- 🚀 **Express Server** - Fast and minimal web framework
+- 📦 **MongoDB** - Database with Harbor ODM
+- 🔒 **TypeScript** - Type-safe development
+- 📝 **ESLint** - Code linting and formatting
+- 🧪 **Vitest** - Testing framework
+- 📁 **Clean Architecture** - Organized folder structure
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- MongoDB (local or Atlas)
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Copy environment variables
+cp .env.example .env
+
+# Start development server
+npm run dev
+```
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start development server with hot reload |
+| `npm run build` | Build for production |
+| `npm start` | Start production server |
+| `npm run lint` | Run ESLint |
+| `npm run lint:fix` | Fix ESLint errors |
+| `npm test` | Run tests |
+
+## Project Structure
+
+```
+├── server.ts          # Application entry point
+├── routes/            # Route definitions
+│   ├── index.ts       # Route aggregator
+│   └── user.routes.ts # User routes
+├── controllers/       # Request handlers
+│   └── user.controller.ts
+├── services/          # Business logic
+│   └── user.service.ts
+├── models/            # Database models
+│   └── user.model.ts
+├── types/             # TypeScript definitions
+├── utils/             # Utility functions
+├── constants/         # App constants & config
+└── package.json
+```
+
+## API Endpoints
+
+### Users
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/users` | Get all users |
+| GET | `/api/users/:id` | Get user by ID |
+| POST | `/api/users` | Create new user |
+| PUT | `/api/users/:id` | Update user |
+| DELETE | `/api/users/:id` | Delete user |
+
+### Health Check
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Server health status |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | `3000` |
+| `NODE_ENV` | Environment | `development` |
+| `MONGODB_URI` | MongoDB connection string | - |
+| `DB_NAME` | Database name | `harbor_app` |
+| `JWT_SECRET` | JWT signing secret | - |
+
+## License
+
+MIT
+

package/templates/default/constants/config.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+
+export const config = {
+  // Server
+  PORT: parseInt(process.env.PORT || '3000', 10),
+  NODE_ENV: process.env.NODE_ENV || 'development',
+  
+  // Database
+  MONGODB_URI: process.env.MONGODB_URI || '',
+  DB_NAME: process.env.DB_NAME || 'harbor_app',
+  
+  // JWT
+  JWT_SECRET: process.env.JWT_SECRET || 'your-secret-key',
+  JWT_EXPIRES_IN: process.env.JWT_EXPIRES_IN || '7d',
+  
+  // CORS
+  CORS_ORIGIN: process.env.CORS_ORIGIN || '*',
+  
+  // Logging
+  LOG_LEVEL: process.env.LOG_LEVEL || 'info',
+  
+  // Rate Limiting
+  RATE_LIMIT_WINDOW: parseInt(process.env.RATE_LIMIT_WINDOW || '900000', 10), // 15 minutes
+  RATE_LIMIT_MAX: parseInt(process.env.RATE_LIMIT_MAX || '100', 10),
+} as const;
+

package/templates/default/constants/http.ts

@@ -0,0 +1,32 @@
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+} as const;
+
+export const HTTP_MESSAGES = {
+  [HTTP_STATUS.OK]: 'Success',
+  [HTTP_STATUS.CREATED]: 'Created successfully',
+  [HTTP_STATUS.NO_CONTENT]: 'Deleted successfully',
+  [HTTP_STATUS.BAD_REQUEST]: 'Bad request',
+  [HTTP_STATUS.UNAUTHORIZED]: 'Unauthorized',
+  [HTTP_STATUS.FORBIDDEN]: 'Access denied',
+  [HTTP_STATUS.NOT_FOUND]: 'Resource not found',
+  [HTTP_STATUS.CONFLICT]: 'Resource already exists',
+  [HTTP_STATUS.UNPROCESSABLE_ENTITY]: 'Validation error',
+  [HTTP_STATUS.TOO_MANY_REQUESTS]: 'Too many requests',
+  [HTTP_STATUS.INTERNAL_SERVER_ERROR]: 'Internal server error',
+  [HTTP_STATUS.BAD_GATEWAY]: 'Bad gateway',
+  [HTTP_STATUS.SERVICE_UNAVAILABLE]: 'Service unavailable',
+} as const;
+

package/templates/default/constants/index.ts

@@ -0,0 +1,3 @@
+export { config } from './config';
+export { HTTP_STATUS, HTTP_MESSAGES } from './http';
+

package/templates/default/controllers/index.ts

@@ -0,0 +1,6 @@
+export { UserController } from './user.controller';
+
+// Add more controller exports here:
+// export { ProductController } from './product.controller';
+// export { OrderController } from './order.controller';
+

package/templates/default/controllers/user.controller.ts

@@ -0,0 +1,77 @@
+import { Request, Response } from 'express';
+import { UserService } from '../services';
+import { CreateUserDto, UpdateUserDto } from '../types';
+
+export class UserController {
+  /**
+   * Get all users
+   */
+  static async getAll(req: Request, res: Response) {
+    const { page = 1, limit = 10 } = req.query;
+    
+    const result = await UserService.findAll({
+      page: Number(page),
+      limit: Number(limit),
+    });
+
+    return res.json(result);
+  }
+
+  /**
+   * Get user by ID
+   */
+  static async getById(req: Request, res: Response) {
+    const { id } = req.params;
+    
+    const user = await UserService.findById(id);
+    
+    if (!user) {
+      return res.status(404).json({ error: 'User not found' });
+    }
+
+    return res.json(user);
+  }
+
+  /**
+   * Create new user
+   */
+  static async create(req: Request, res: Response) {
+    const data: CreateUserDto = req.body;
+    
+    const user = await UserService.create(data);
+
+    return res.status(201).json(user);
+  }
+
+  /**
+   * Update user
+   */
+  static async update(req: Request, res: Response) {
+    const { id } = req.params;
+    const data: UpdateUserDto = req.body;
+    
+    const user = await UserService.update(id, data);
+
+    if (!user) {
+      return res.status(404).json({ error: 'User not found' });
+    }
+
+    return res.json(user);
+  }
+
+  /**
+   * Delete user
+   */
+  static async delete(req: Request, res: Response) {
+    const { id } = req.params;
+    
+    const deleted = await UserService.delete(id);
+
+    if (!deleted) {
+      return res.status(404).json({ error: 'User not found' });
+    }
+
+    return res.status(204).send();
+  }
+}
+

package/templates/default/env.example

@@ -0,0 +1,22 @@
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# Database
+MONGODB_URI=mongodb://localhost:27017
+DB_NAME=harbor_app
+
+# JWT Authentication
+JWT_SECRET=your-super-secret-key-change-in-production
+JWT_EXPIRES_IN=7d
+
+# CORS
+CORS_ORIGIN=http://localhost:3000
+
+# Logging
+LOG_LEVEL=info
+
+# Rate Limiting
+RATE_LIMIT_WINDOW=900000
+RATE_LIMIT_MAX=100
+

package/templates/default/harbor.version.json

@@ -0,0 +1,7 @@
+{
+  "harborVersion": "1.3.0",
+  "templateVersion": "1.0.0",
+  "createdAt": "{{CREATED_AT}}",
+  "templateName": "default"
+}
+

package/templates/default/models/index.ts

@@ -0,0 +1,6 @@
+export { User } from './user.model';
+
+// Add more model exports here:
+// export { Product } from './product.model';
+// export { Order } from './order.model';
+

package/templates/default/models/user.model.ts

@@ -0,0 +1,68 @@
+import { Schema, model } from 'harbor/database';
+
+// Define the User schema
+const userSchema = new Schema({
+  email: {
+    type: 'string',
+    required: true,
+    unique: true,
+  },
+  name: {
+    type: 'string',
+    required: true,
+  },
+  password: {
+    type: 'string',
+    required: true,
+    select: false, // Don't include in query results by default
+  },
+  role: {
+    type: 'string',
+    enum: ['user', 'admin', 'moderator'],
+    default: 'user',
+  },
+  isActive: {
+    type: 'boolean',
+    default: true,
+  },
+  profile: {
+    avatar: { type: 'string' },
+    bio: { type: 'string' },
+  },
+  lastLogin: {
+    type: 'date',
+  },
+}, {
+  timestamps: true, // Adds createdAt and updatedAt
+  collection: 'users',
+});
+
+// Virtual for full display name
+userSchema.virtual('displayName').get(function() {
+  return this.name || this.email.split('@')[0];
+});
+
+// Pre-save hook for password hashing
+userSchema.pre('save', async function(next) {
+  if (this.isModified('password')) {
+    // Hash password here (use bcrypt in production)
+    // this.password = await bcrypt.hash(this.password, 10);
+  }
+  next();
+});
+
+// Static method for finding by email
+userSchema.statics.findByEmail = function(email: string) {
+  return this.findOne({ email: email.toLowerCase() });
+};
+
+// Instance method for comparing passwords
+userSchema.methods.comparePassword = async function(candidatePassword: string) {
+  // Compare passwords here (use bcrypt in production)
+  // return bcrypt.compare(candidatePassword, this.password);
+  return candidatePassword === this.password;
+};
+
+// Export the model
+export const User = model('User', userSchema);
+

package/templates/default/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "description": "{{PROJECT_DESCRIPTION}}",
+  "main": "dist/server.js",
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage"
+  },
+  "keywords": [
+    "nodejs",
+    "express",
+    "mongodb",
+    "harbor",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "harbor": "^1.2.0",
+    "mongodb": "^6.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.55.0",
+    "tsx": "^4.6.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+

package/templates/default/routes/index.ts

@@ -0,0 +1,12 @@
+import { Router } from 'express';
+import { userRoutes } from './user.routes';
+
+export const routes = Router();
+
+// Register all route modules
+routes.use('/users', userRoutes);
+
+// Add more routes here:
+// routes.use('/products', productRoutes);
+// routes.use('/orders', orderRoutes);
+

package/templates/default/routes/user.routes.ts

@@ -0,0 +1,21 @@
+import { Router } from 'express';
+import { GET, POST, PUT, DELETE } from 'harbor';
+import { UserController } from '../controllers';
+
+export const userRoutes = Router();
+
+// GET /api/users - Get all users
+userRoutes.get('/', GET(UserController.getAll));
+
+// GET /api/users/:id - Get user by ID
+userRoutes.get('/:id', GET(UserController.getById));
+
+// POST /api/users - Create new user
+userRoutes.post('/', POST(UserController.create));
+
+// PUT /api/users/:id - Update user
+userRoutes.put('/:id', PUT(UserController.update));
+
+// DELETE /api/users/:id - Delete user
+userRoutes.delete('/:id', DELETE(UserController.delete));
+

package/templates/default/server.ts

@@ -0,0 +1,45 @@
+import { createServer, connect, httpLogger } from 'harbor';
+import { routes } from './routes';
+import { config } from './constants';
+
+async function bootstrap() {
+  // Create server with Harbor
+  const app = createServer({
+    port: config.PORT,
+    cors: true,
+    helmet: true,
+    json: true,
+    urlencoded: true,
+  });
+
+  // HTTP request logging
+  app.use(httpLogger({
+    format: 'dev',
+    skip: (req) => req.path === '/health',
+  }));
+
+  // Connect to MongoDB (optional)
+  if (config.MONGODB_URI) {
+    await connect(config.MONGODB_URI, {
+      dbName: config.DB_NAME,
+    });
+    console.log('📦 Connected to MongoDB');
+  }
+
+  // Register all routes
+  app.use('/api', routes);
+
+  // Health check endpoint
+  app.get('/health', (req, res) => {
+    res.json({ status: 'ok', timestamp: new Date().toISOString() });
+  });
+
+  // Start server
+  app.listen(config.PORT, () => {
+    console.log(`🚀 Server running on http://localhost:${config.PORT}`);
+    console.log(`📚 API Docs: http://localhost:${config.PORT}/api-docs`);
+  });
+}
+
+bootstrap().catch(console.error);
+

package/templates/default/services/index.ts

@@ -0,0 +1,6 @@
+export { UserService } from './user.service';
+
+// Add more service exports here:
+// export { ProductService } from './product.service';
+// export { OrderService } from './order.service';
+

package/templates/default/services/user.service.ts

@@ -0,0 +1,84 @@
+import { User } from '../models';
+import { CreateUserDto, UpdateUserDto, PaginationOptions, PaginatedResult } from '../types';
+
+export class UserService {
+  /**
+   * Find all users with pagination
+   */
+  static async findAll(options: PaginationOptions): Promise<PaginatedResult<typeof User>> {
+    const { page = 1, limit = 10 } = options;
+    const skip = (page - 1) * limit;
+
+    const [users, total] = await Promise.all([
+      User.find()
+        .skip(skip)
+        .limit(limit)
+        .sort({ createdAt: -1 }),
+      User.countDocuments(),
+    ]);
+
+    return {
+      data: users,
+      pagination: {
+        page,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  /**
+   * Find user by ID
+   */
+  static async findById(id: string) {
+    return User.findById(id);
+  }
+
+  /**
+   * Find user by email
+   */
+  static async findByEmail(email: string) {
+    return User.findOne({ email: email.toLowerCase() });
+  }
+
+  /**
+   * Create new user
+   */
+  static async create(data: CreateUserDto) {
+    const user = await User.create({
+      ...data,
+      email: data.email.toLowerCase(),
+    });
+
+    return user;
+  }
+
+  /**
+   * Update user
+   */
+  static async update(id: string, data: UpdateUserDto) {
+    return User.findByIdAndUpdate(
+      id,
+      { $set: data },
+      { new: true }
+    );
+  }
+
+  /**
+   * Delete user
+   */
+  static async delete(id: string) {
+    const result = await User.deleteOne({ _id: id });
+    return result.deletedCount > 0;
+  }
+
+  /**
+   * Check if email exists
+   */
+  static async emailExists(email: string): Promise<boolean> {
+    const count = await User.countDocuments({ email: email.toLowerCase() });
+    return count > 0;
+  }
+}
+

package/templates/default/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}
+

package/templates/default/types/index.ts

@@ -0,0 +1,57 @@
+// User DTOs
+export interface CreateUserDto {
+  email: string;
+  name: string;
+  password: string;
+  role?: 'user' | 'admin' | 'moderator';
+}
+
+export interface UpdateUserDto {
+  email?: string;
+  name?: string;
+  password?: string;
+  role?: 'user' | 'admin' | 'moderator';
+  isActive?: boolean;
+  profile?: {
+    avatar?: string;
+    bio?: string;
+  };
+}
+
+// Pagination
+export interface PaginationOptions {
+  page?: number;
+  limit?: number;
+  sort?: string;
+  order?: 'asc' | 'desc';
+}
+
+export interface Pagination {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  pagination: Pagination;
+}
+
+// API Response
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+}
+
+// Request with user (for auth)
+export interface AuthenticatedRequest extends Express.Request {
+  user?: {
+    id: string;
+    email: string;
+    role: string;
+  };
+}
+

package/templates/default/utils/asyncHandler.ts

@@ -0,0 +1,14 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/**
+ * Wraps async route handlers to automatically catch errors
+ * and pass them to Express error handling middleware
+ */
+export const asyncHandler = (
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>
+): RequestHandler => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};
+

package/templates/default/utils/index.ts

@@ -0,0 +1,5 @@
+export { logger } from './logger';
+export { asyncHandler } from './asyncHandler';
+export { formatResponse, formatError } from './response';
+export { validateObjectId } from './validation';
+