@sundaysf/cli-v2 1.0.0 → 1.0.3

package/dist/templates/backend-embedded-db-sql/.env.example

@@ -0,0 +1,14 @@
+# Server
+PORT=3098
+ENVIRONMENT=local
+
+# CORS (comma-separated origins with protocol)
+CORS_ALLOWED_ORIGINS=http://localhost:3098
+
+# Database
+SQL_HOST=localhost
+SQL_PORT=5432
+SQL_USER=postgres
+SQL_PASSWORD=
+SQL_DB_NAME=mydb
+SQL_REJECT_UNAUTHORIZED=false

package/dist/templates/backend-embedded-db-sql/.prettierignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+package-lock.json

package/dist/templates/backend-embedded-db-sql/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": true,
+  "arrowParens": "always"
+}

package/dist/templates/backend-embedded-db-sql/CLAUDE.md

@@ -0,0 +1,371 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+
+- `npm run start:dev` - Start development server with auto-reload (uses nodemon)
+- `npm run build` - Compile TypeScript to JavaScript (output to dist/)
+- `npm start` - Run production server from compiled dist/
+
+### Code Quality
+
+- `npm run format` - Format code with Prettier
+- No linting command configured - consider using ESLint with the installed configuration
+
+### Testing
+
+- `npm test` - Run tests with Jest (no test files found yet)
+
+### Utilities
+
+- `npm run create:controller` - Generate new controller using Sundays Framework CLI
+
+### Database
+
+- `npm run db:migrate` - Apply pending migrations
+- `npm run db:rollback` - Rollback the last batch of migrations
+- `npm run db:seed` - Run seed files
+- `npm run db:make-migration` - Create a new migration file
+
+## Architecture
+
+This is a Sundays Framework backend built with Express.js and TypeScript following a modular MVC pattern, with the Knex.js database layer embedded in `src/db/`.
+
+### Core Structure
+
+- **Entry Points**: `src/server.ts` initializes the server and connects to the database, `src/app.ts` configures Express middleware
+- **Routing**: Dynamic route loading system in `src/routes/index.ts` that automatically discovers and mounts routers from subdirectories
+- **Controllers**: Business logic separated into controller classes (e.g., `HealthController`)
+- **Middleware**: Error handling middleware in `src/middlewares/error/`
+- **Configuration**: CORS origins managed in `src/common/config/origins/`
+- **Database**: `src/db/` contains the Knex.js module with DAOs, interfaces, and the KnexManager singleton
+
+### Key Patterns
+
+1. **Router Auto-Discovery**: The `IndexRouter` class scans the routes directory and automatically mounts any `*.router.ts` files found in subdirectories. Routes are mounted at `/{folder-name}`.
+
+2. **Controller Pattern**: Each router has a corresponding controller class that handles the business logic. Controllers are bound to router methods using `.bind()` to maintain proper context.
+
+3. **Environment Configuration**: Uses dotenv for environment variables. Server port defaults to 3005 if not specified in .env.
+
+4. **CORS Configuration**: Dynamic CORS origin configuration via `getAllowedOrigins()` function.
+
+5. **Database Connection**: `src/server.ts` calls `KnexManager.connect()` before starting the Express server. The KnexManager singleton manages connection pooling.
+
+6. **Dependencies**:
+   - Sundays Framework utilities (`@sundaysf/utils`) for pagination and validation
+   - Standard Express middleware (cors, morgan, etc.)
+   - Knex.js + PostgreSQL for database access
+
+### Database Module (`src/db/`)
+
+The `src/db/` directory contains the Knex.js database layer, compiled together with the rest of the application:
+
+- **KnexManager** (`src/db/KnexConnection.ts`): Singleton for managing database connections with pooling and SSL support
+- **DAO Pattern**: Data Access Objects implement `IBaseDAO<T>` with CRUD + pagination
+- **Migrations**: `migrations/` (root level) - Knex migration files in TypeScript
+- **Seeds**: `seeds/` (root level) - Seed data files
+- **Interfaces**: `src/db/interfaces/` - Entity type definitions
+- **Configuration**: `knexfile.ts` (root level) - Knex configuration for all environments
+
+#### File Structure Conventions
+
+**Interfaces**: `src/db/interfaces/{entity}/{entity}.interfaces.ts`
+**DAOs**: `src/db/dao/{entity}/{entity}.dao.ts`
+
+#### Environment Variables (Database)
+
+- `SQL_HOST` - PostgreSQL host
+- `SQL_PORT` - Database port (defaults to 5432)
+- `SQL_USER` - Database user
+- `SQL_PASSWORD` - Database password
+- `SQL_DB_NAME` - Database name
+- `SQL_REJECT_UNAUTHORIZED` - Set to 'false' to disable SSL certificate verification
+
+### TypeScript Configuration
+
+- **Single tsconfig.json**: Strict mode, ES2022, CommonJS. Source in `./src` (including `src/db/`), output to `./dist`.
+
+## Controller Implementation Guide
+
+When creating new controllers, follow the established pattern demonstrated in the CompanyController:
+
+### 1. Controller Structure
+```typescript
+import { Request, Response, NextFunction } from "express";
+import { IBaseController } from "../../types";
+import { inputValidator, IInputValidator, paginationHelper } from "@sundaysf/utils";
+import { [Entity]DAO, I[Entity], IDataPaginator } from "../../db";
+import { [Entity]CreateInputDTO } from "../../dto/input/[entity]/[entity].create.dto";
+import { [Entity]UpdateInputDTO } from "../../dto/input/[entity]/[entity].update.dto";
+import { v4 as uuidv4 } from 'uuid';
+
+export class [Entity]Controller implements IBaseController {
+  private _[entity]DAO: [Entity]DAO = new [Entity]DAO();
+
+  // Implement CRUD methods
+}
+```
+
+### 2. API Response Format
+
+All API responses must follow a consistent format:
+
+**Success Response**:
+```json
+{
+  "success": true,
+  "data": {...} // or "message": "Action completed successfully" for operations without data
+}
+```
+
+**Error Response**:
+```json
+{
+  "success": false,
+  "message": "Error description"
+}
+```
+
+**Paginated Response** (from IDataPaginator):
+```json
+{
+  "success": true,
+  "data": [...],
+  "page": 1,
+  "limit": 10,
+  "count": 10,
+  "totalCount": 100,
+  "totalPages": 10
+}
+```
+
+Note: The `IDataPaginator` interface already includes the standard response format with `success` and `data` fields, so responses from paginated endpoints should be returned directly without additional wrapping.
+
+### 3. Standard CRUD Methods
+
+**getAll** - List with pagination:
+```typescript
+public async getAll(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const {page, limit} = paginationHelper(req);
+    const result: IDataPaginator<I[Entity]> = await this._[entity]DAO.getAll(page, limit);
+    res.status(200).json(result); // IDataPaginator already includes success and data fields
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**getByUuid** - Get single resource:
+```typescript
+public async getByUuid(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const { uuid } = req.params;
+    const result = await this._[entity]DAO.getByUuid(uuid);
+    if (!result) {
+      res.status(404).json({ success: false, message: "[Entity] not found" });
+      return;
+    }
+    res.status(200).json({
+      success: true,
+      data: result
+    });
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**create** - Create new resource with DTO validation:
+```typescript
+public async create(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const data = req.body;
+    const inputDTO = new [Entity]CreateInputDTO(data).build();
+    const validation: IInputValidator = await inputValidator(inputDTO);
+    if (!validation.success) {
+      req.statusCode = 400;
+      return next(new Error(validation.message));
+    }
+    const dataToCreate = {...inputDTO, uuid: uuidv4()};
+    const result = await this._[entity]DAO.create(dataToCreate);
+    res.status(201).json({
+      success: true,
+      data: result
+    });
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**update** - Update existing resource with DTO validation:
+```typescript
+public async update(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const { uuid } = req.params;
+    const data = req.body;
+
+    // First get the entity by UUID to find its ID
+    const existing = await this._[entity]DAO.getByUuid(uuid);
+    if (!existing || !existing.id) {
+      res.status(404).json({ success: false, message: "[Entity] not found" });
+      return;
+    }
+
+    const inputDTO = new [Entity]UpdateInputDTO(data).build();
+    const validation: IInputValidator = await inputValidator(inputDTO);
+    if (!validation.success) {
+      req.statusCode = 400;
+      return next(new Error(validation.message));
+    }
+
+    const result = await this._[entity]DAO.update(existing.id, inputDTO);
+    res.status(200).json({
+      success: true,
+      data: result
+    });
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**delete** - Delete resource:
+```typescript
+public async delete(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const { uuid } = req.params;
+
+    // First get the entity by UUID to find its ID
+    const existing = await this._[entity]DAO.getByUuid(uuid);
+    if (!existing || !existing.id) {
+      res.status(404).json({ success: false, message: "[Entity] not found" });
+      return;
+    }
+
+    const result = await this._[entity]DAO.delete(existing.id);
+    if (result) {
+      res.status(200).json({ success: true, message: "[Entity] deleted successfully" });
+    } else {
+      res.status(404).json({ success: false, message: "Failed to delete [entity]" });
+    }
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+### 4. Router Implementation
+Create a corresponding router in `src/routes/[entity]/[entity].router.ts`:
+
+```typescript
+import { Router } from "express";
+import { [Entity]Controller } from "../../controllers/[entity]/[entity].controller";
+
+export class [Entity]Router {
+  private _router: Router;
+  private _[entity]Controller = new [Entity]Controller();
+
+  constructor() {
+    this._router = Router();
+    this.initRoutes();
+  }
+
+  private initRoutes(): void {
+    this._router.get("/", this._[entity]Controller.getAll.bind(this._[entity]Controller));
+    this._router.get("/:uuid", this._[entity]Controller.getByUuid.bind(this._[entity]Controller));
+    this._router.post("/", this._[entity]Controller.create.bind(this._[entity]Controller));
+    this._router.put("/:uuid", this._[entity]Controller.update.bind(this._[entity]Controller));
+    this._router.delete("/:uuid", this._[entity]Controller.delete.bind(this._[entity]Controller));
+  }
+
+  public get router(): Router {
+    return this._router;
+  }
+}
+```
+
+### 5. DTO Implementation
+
+Create DTOs to validate and sanitize input data:
+
+**Create DTO** (`src/dto/input/[entity]/[entity].create.dto.ts`):
+```typescript
+export class [Entity]CreateInputDTO {
+    // Define only allowed properties
+    property1: type;
+    property2: type;
+
+    constructor(data: any){
+        this.property1 = data.property1;
+        this.property2 = data.property2;
+        // Set defaults for optional properties
+    }
+
+    public build(): this {
+        return this;
+    }
+}
+```
+
+**Update DTO** (`src/dto/input/[entity]/[entity].update.dto.ts`):
+```typescript
+export class [Entity]UpdateInputDTO {
+    // Define optional properties
+    property1?: type;
+    property2?: type;
+
+    constructor(data: any){
+        // Only set properties that are present in the input
+        if (data.property1 !== undefined) this.property1 = data.property1;
+        if (data.property2 !== undefined) this.property2 = data.property2;
+    }
+
+    public build(): this {
+        // Remove any properties that weren't set
+        const cleanData: any = {};
+        if (this.property1 !== undefined) cleanData.property1 = this.property1;
+        if (this.property2 !== undefined) cleanData.property2 = this.property2;
+
+        // Clear all properties and reassign only the allowed ones
+        Object.keys(this).forEach(key => delete (this as any)[key]);
+        Object.assign(this, cleanData);
+
+        return this;
+    }
+}
+```
+
+### 6. Working with Related Entities
+
+When your entity has foreign key relationships, DAOs can include related entities using PostgreSQL's `to_jsonb()` function:
+
+```typescript
+async getById(id: number): Promise<IEntity | null> {
+  const result = await this._knex("entity as e")
+    .leftJoin("related as r", "e.relatedId", "r.id")
+    .select("e.*", this._knex.raw("to_jsonb(r.*) as related"))
+    .where("e.id", id)
+    .first();
+  return result || null;
+}
+```
+
+### 7. Important Notes
+- Always use `.bind()` when assigning controller methods to router to maintain proper context
+- Use UUID for public-facing endpoints (params) but convert to ID for internal DAO operations
+- Return appropriate HTTP status codes (200, 201, 404, etc.)
+- Pass errors to the next() function for centralized error handling
+- Use paginationHelper from @sundaysf/utils for consistent pagination
+- Use DTOs to validate and sanitize input data, preventing unwanted fields from being processed
+- DTOs ensure only allowed fields are passed to the DAO layer
+- Update DTOs should handle partial updates properly
+- Always generate UUID in the controller for new resources (not in DTO or client-side)
+- All API responses must follow the standard format: `{success: boolean, data?: any, message?: string}`
+- Use status 200 for successful DELETE operations (not 204) to include success message
+- Import DAOs and interfaces from `../db` (relative path from controllers to src/db/index.ts)

package/dist/templates/backend-embedded-db-sql/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:22-alpine AS builder
+WORKDIR /var/api
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /var/api
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY --from=builder /var/api/dist ./dist
+EXPOSE 3098
+CMD ["node", "dist/server.js"]

package/dist/templates/backend-embedded-db-sql/README.md

@@ -0,0 +1,32 @@
+# Sundays Framework Project
+
+This directory contains the starter backend with an embedded database module generated by the CLI.
+
+## Quick start
+
+1. Install dependencies:
+   ```
+   npm install
+   ```
+2. Copy `.env.example` to `.env` and set your environment variables (especially the `SQL_*` database variables).
+3. Run database migrations:
+   ```
+   npm run db:migrate
+   ```
+4. Start the development server:
+   ```
+   npm run start:dev
+   ```
+
+The server will run on the port specified in your `.env` file.
+
+## Database
+
+The database layer lives in `src/db/` and is compiled together with the rest of the application.
+
+### Database commands
+
+- `npm run db:migrate` - Apply pending migrations
+- `npm run db:rollback` - Rollback the last batch of migrations
+- `npm run db:seed` - Run seed files
+- `npm run db:make-migration` - Create a new migration file

package/dist/templates/backend-embedded-db-sql/eslint.config.js

@@ -0,0 +1,20 @@
+const eslint = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+
+module.exports = tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {},
+  },
+  {
+    ignores: ['dist/', 'node_modules/'],
+  }
+);
+
+//# sourceMappingURL=eslint.config.js.map

package/dist/templates/backend-embedded-db-sql/knexfile.ts

@@ -0,0 +1,37 @@
+import type { Knex } from "knex";
+import dotenv from "dotenv";
+dotenv.config();
+
+const isLocalhost = process.env.SQL_HOST === 'localhost' || process.env.SQL_HOST === '127.0.0.1';
+const rejectUnauthorized = process.env.SQL_REJECT_UNAUTHORIZED !== 'false';
+
+const sharedConfig: Knex.Config = {
+  client: "postgresql",
+  connection: {
+    database: process.env.SQL_DB_NAME,
+    user: process.env.SQL_USER,
+    password: process.env.SQL_PASSWORD,
+    host: process.env.SQL_HOST,
+    port: process.env.SQL_PORT ? +process.env.SQL_PORT : 5432,
+    ssl: isLocalhost ? false : { rejectUnauthorized },
+  },
+  pool: {
+    min: 2,
+    max: 10,
+  },
+  migrations: {
+    tableName: "knex_migrations",
+    directory: "./migrations",
+  },
+  seeds: {
+    directory: "./seeds",
+  },
+};
+
+const config: { [key: string]: Knex.Config } = {
+  development: sharedConfig,
+  staging: sharedConfig,
+  production: sharedConfig,
+};
+
+export default config;

package/dist/templates/backend-embedded-db-sql/migrations/001_create_sundays_package_version.ts

@@ -0,0 +1,13 @@
+import type { Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable("sundays_package_version", (table) => {
+    table.increments("id").primary();
+    table.string("versionName").notNullable();
+    table.timestamps(true, true); // created_at, updated_at
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists("sundays_package_version");
+}

package/dist/templates/backend-embedded-db-sql/seeds/001_sundays_package_version_seed.ts

@@ -0,0 +1,11 @@
+import { Knex } from "knex";
+
+export async function seed(knex: Knex): Promise<void> {
+    // Deletes ALL existing entries
+    await knex("sundays_package_version").del();
+
+    // Inserts seed entries
+    await knex("sundays_package_version").insert([
+        { versionName: "1.0.0" }
+    ]);
+}

package/dist/templates/backend-embedded-db-sql/src/app.ts

@@ -0,0 +1,35 @@
+import dotenv from 'dotenv';
+import express, { type Express } from 'express';
+import logger from 'morgan';
+import cors from 'cors';
+import { IndexRouter } from './routes/index';
+import { errorMiddleware } from './middlewares/error/error.middleware';
+import { getAllowedOrigins } from './common/config/origins/origins.config';
+dotenv.config();
+
+const app: Express = express();
+
+app.use(
+    logger('tiny', {
+        skip: (req, _res) => {
+            return req.originalUrl.startsWith('/api/health');
+        },
+    })
+);
+
+app.use(
+    cors({
+        origin: getAllowedOrigins(),
+        credentials: true,
+        allowedHeaders: ['Content-Type', 'Authorization'],
+    })
+);
+
+app.use(express.urlencoded({ extended: true }));
+app.use(express.json());
+
+app.use('/api', new IndexRouter().router);
+
+app.use(errorMiddleware);
+
+export default app;

package/dist/templates/backend-embedded-db-sql/src/common/config/origins/origins.config.ts

@@ -0,0 +1,11 @@
+export const getAllowedOrigins = (): string[] => {
+  let origins: string = process.env.CORS_ALLOWED_ORIGINS || 'http://localhost:3098';
+  origins = origins
+    .split('\n')
+    .join('')
+    .split('\r')
+    .join('')
+    .split(' ')
+    .join('');
+  return origins.split(',');
+};

package/dist/templates/backend-embedded-db-sql/src/common/utils/environment.resolver.ts

@@ -0,0 +1,4 @@
+export const getServiceEnvironment = (): string => {
+    const serEnv: string = process.env.ENVIRONMENT || 'undefined';
+    return serEnv.charAt(0).toUpperCase() + serEnv.slice(1);
+};

package/dist/templates/backend-embedded-db-sql/src/common/utils/version.resolver.ts

@@ -0,0 +1,5 @@
+const pjson = require('../../../package.json');
+
+export const getServiceVersion = (): string => {
+    return pjson['version'];
+};

package/dist/templates/backend-embedded-db-sql/src/controllers/health/health.controller.ts

@@ -0,0 +1,24 @@
+import { NextFunction, Request, Response } from 'express';
+import { getServiceVersion } from '../../common/utils/version.resolver';
+import { getServiceEnvironment } from '../../common/utils/environment.resolver';
+
+export class HealthController {
+  public async getHealthStatus(
+    _req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> {
+    try {
+      const version: string = await getServiceVersion();
+      const environment: string = await getServiceEnvironment();
+      res.status(200).json({
+        success: true,
+        health: 'Up!',
+        version,
+        environment,
+      });
+    } catch (err: any) {
+      next(err);
+    }
+  }
+}