@sundaysf/cli-v2 0.0.2 → 0.0.4

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

@@ -0,0 +1,374 @@
+# 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 migrate:create` - Create a new migration file in TypeScript
+- `npm run migrate:deploy` - Apply pending migrations
+- `npm run seed:create` - Create a new seed file in TypeScript
+- `npm run seed:run` - Execute seed files
+- `npm run db:build` - Compile the db module TypeScript to JavaScript
+- `npm run db:publish` - Publish the db module as an independent npm package
+
+## Architecture
+
+This is a Sundays Framework backend built with Express.js and TypeScript following a modular MVC pattern, with an embedded Knex.js database module in `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**: `db/` contains the Knex.js module with DAOs, migrations, seeds, and interfaces
+
+### 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 (`db/`)
+
+The `db/` directory is an independently publishable Knex.js module:
+
+- **KnexManager** (`db/src/KnexConnection.ts`): Singleton for managing database connections with pooling and SSL support
+- **DAO Pattern**: Data Access Objects implement `IBaseDAO<T>` with CRUD + pagination
+- **Migrations**: `db/migrations/` - Knex migration files in TypeScript
+- **Seeds**: `db/seeds/` - Seed data files
+- **Interfaces**: `db/src/interfaces/` - Entity type definitions
+- **Configuration**: `db/knexfile.ts` - Knex configuration for all environments
+
+#### File Structure Conventions
+
+**Interfaces**: `db/src/interfaces/{entity}/{entity}.interfaces.ts`
+**DAOs**: `db/src/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
+
+- **Backend** (`tsconfig.json`): Strict mode, ES2022, CommonJS. Source in `./src`, output to `./dist`. Excludes `db/`.
+- **Database** (`db/tsconfig.json`): Strict mode, ES2022, CommonJS with declarations. Source in `db/src`, output to `db/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/src";
+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/src` (relative path from controllers)

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

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

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

@@ -0,0 +1,34 @@
+# Sundays Framework Project
+
+This directory contains the starter backend with 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 migrate:deploy
+   ```
+4. Start the development server:
+   ```
+   npm run start:dev
+   ```
+
+The server will run on the port specified in your `.env` file.
+
+## Database module
+
+The `db/` directory contains an independently publishable Knex.js database module. It can be used as part of this backend or published separately as an npm package.
+
+### Database commands
+
+- `npm run migrate:create` - Create a new migration
+- `npm run migrate:deploy` - Run pending migrations
+- `npm run seed:create` - Create a new seed file
+- `npm run seed:run` - Run seed files
+- `npm run db:build` - Compile the database module
+- `npm run db:publish` - Publish the database module to npm

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

@@ -0,0 +1,33 @@
+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",
+  },
+};
+
+const config: { [key: string]: Knex.Config } = {
+  development: sharedConfig,
+  staging: sharedConfig,
+  production: sharedConfig,
+};
+
+export default config;

package/dist/templates/backend-db-sql/db/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-db-sql/db/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-db-sql/db/src/KnexConnection.ts

@@ -0,0 +1,74 @@
+import { knex, Knex } from 'knex';
+
+class KnexManager {
+  private static knexInstance: Knex<any, unknown[]> | null = null;
+
+  /**
+   * Open a new connection. Reuse the already existing one if there's any.
+   */
+  static async connect(
+    config?: Knex.Config,
+    connections?: number
+  ): Promise<Knex<any, unknown[]>> {
+    if (!KnexManager.knexInstance) {
+      const isLocalhost = process.env.SQL_HOST === 'localhost' || process.env.SQL_HOST === '127.0.0.1';
+      const rejectUnauthorized = process.env.SQL_REJECT_UNAUTHORIZED !== 'false';
+      const defaultConfig = {
+        client: 'pg',
+        connection: {
+          host: process.env.SQL_HOST,
+          user: process.env.SQL_USER,
+          password: process.env.SQL_PASSWORD,
+          database: process.env.SQL_DB_NAME,
+          port: Number(process.env.SQL_PORT) || 5432,
+          ssl: isLocalhost ? false : { rejectUnauthorized },
+        },
+        pool: {
+          min: 1,
+          max: connections || 15,
+          idleTimeoutMillis: 20000,
+          acquireTimeoutMillis: 30000,
+        },
+        migrations: {
+          tableName: 'knex_migrations',
+        },
+      };
+      KnexManager.knexInstance = knex(config || defaultConfig);
+      try {
+        await KnexManager.knexInstance.raw('SELECT 1');
+        console.info(`Knex connection established`);
+      } catch (error) {
+        console.error(`Failed to establish Knex connection:`, error);
+        KnexManager.knexInstance = null;
+        throw error;
+      }
+    }
+
+    return KnexManager.knexInstance;
+  }
+
+  /**
+   * Returns the active connection.
+   */
+  static getConnection(): Knex<any, unknown[]> {
+    if (!KnexManager.knexInstance) {
+      throw new Error(
+        'Knex connection has not been established. Call connect() first.'
+      );
+    }
+    return KnexManager.knexInstance;
+  }
+
+  /**
+   * Closes the connection and destroys the instance.
+   */
+  static async disconnect(): Promise<void> {
+    if (KnexManager.knexInstance) {
+      await KnexManager.knexInstance.destroy();
+      KnexManager.knexInstance = null;
+      console.info(`Knex connection closed`);
+    }
+  }
+}
+
+export default KnexManager;

package/dist/templates/backend-db-sql/db/src/d.types.ts

@@ -0,0 +1,18 @@
+export interface IBaseDAO<T> {
+    create(item: T): Promise<T>;
+    getById(id: number): Promise<T | null>;
+    getByUuid(uuid: string): Promise<T | null>;
+    update(id: number, item: Partial<T>): Promise<T | null>;
+    delete(id: number): Promise<boolean>;
+    getAll(page: number, limit: number): Promise<IDataPaginator<T>>;
+}
+
+export interface IDataPaginator<T> {
+    success: boolean;
+    data: T[];
+    page: number;
+    limit: number;
+    count: number;
+    totalCount: number;
+    totalPages: number;
+}

package/dist/templates/backend-db-sql/db/src/dao/sundays-package-version/sundays-package-version.dao.ts

@@ -0,0 +1,71 @@
+import { Knex } from "knex";
+import { IBaseDAO, IDataPaginator } from "../../d.types";
+import { ISundaysPackageVersion } from "../../interfaces/sundays-package-version/sundays-package-version.interfaces";
+import KnexManager from "../../KnexConnection";
+
+export class SundaysPackageVersionDAO implements IBaseDAO<ISundaysPackageVersion> {
+    private _knex: Knex<any, unknown[]> = KnexManager.getConnection();
+
+    async create(item: ISundaysPackageVersion): Promise<ISundaysPackageVersion> {
+        const [created] = await this._knex("sundays_package_version").insert(item).returning("*");
+        return created;
+    }
+
+    async getById(id: number): Promise<ISundaysPackageVersion | null> {
+        const result = await this._knex("sundays_package_version")
+            .select("*")
+            .where("id", id)
+            .first();
+        return result || null;
+    }
+
+    async getByUuid(uuid: string): Promise<ISundaysPackageVersion | null> {
+        const result = await this._knex("sundays_package_version")
+            .select("*")
+            .where("uuid", uuid)
+            .first();
+        return result || null;
+    }
+
+    async update(id: number, item: Partial<ISundaysPackageVersion>): Promise<ISundaysPackageVersion | null> {
+        const [updated] = await this._knex("sundays_package_version")
+            .where({ id })
+            .update(item)
+            .returning("*");
+        return updated || null;
+    }
+
+    async delete(id: number): Promise<boolean> {
+        const result = await this._knex("sundays_package_version").where({ id }).del();
+        return result > 0;
+    }
+
+    async getAll(page: number, limit: number): Promise<IDataPaginator<ISundaysPackageVersion>> {
+        const safeLimit = Math.max(limit, 1);
+        const offset = (page - 1) * safeLimit;
+
+        const query = this._knex("sundays_package_version").select("*");
+
+        const [countResult] = await query.clone().clearSelect().count("* as count");
+        const totalCount = +countResult.count;
+        const data = await query.clone().limit(safeLimit).offset(offset).orderBy("id", "desc");
+
+        return {
+            success: true,
+            data,
+            page,
+            limit: safeLimit,
+            count: data.length,
+            totalCount,
+            totalPages: Math.ceil(totalCount / safeLimit),
+        };
+    }
+
+    async getLatestVersion(): Promise<ISundaysPackageVersion | null> {
+        const result = await this._knex("sundays_package_version")
+            .select("*")
+            .orderBy("id", "desc")
+            .first();
+        return result || null;
+    }
+}

package/dist/templates/backend-db-sql/db/src/index.ts

@@ -0,0 +1,9 @@
+// DAOs
+export { SundaysPackageVersionDAO } from "./dao/sundays-package-version/sundays-package-version.dao";
+
+// Interfaces
+export { IDataPaginator } from "./d.types";
+export { ISundaysPackageVersion } from "./interfaces/sundays-package-version/sundays-package-version.interfaces";
+
+import KnexManager from './KnexConnection';
+export { KnexManager };

package/dist/templates/backend-db-sql/db/src/interfaces/sundays-package-version/sundays-package-version.interfaces.ts

@@ -0,0 +1,6 @@
+export interface ISundaysPackageVersion {
+  id: number;
+  versionName: string;
+  createdAt: string;
+  updatedAt: string;
+}

package/dist/templates/backend-db-sql/db/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "CommonJS",
+    "target": "ES2022",
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "declaration": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}