@sundaysf/cli-v2 0.0.3 → 1.0.0

package/dist/templates/backend/.claude/agents/knex-table-implementer.md

@@ -0,0 +1,113 @@
+---
+name: knex-table-implementer
+description: Use this agent when you need to create new database table implementations in the Knex project, including migrations, DAOs, interfaces, and exports. This agent should be triggered when: 1) A new database table needs to be added to the system, 2) You need to implement the complete data access layer for a new entity, 3) You want to ensure consistency with the existing project structure and patterns. Examples: <example>Context: User needs to add a new 'product' table to the database. user: "I need to add a product table with id, name, price, and categoryId fields" assistant: "I'll use the knex-table-implementer agent to create the complete implementation for the product table including migration, DAO, interfaces, and exports" <commentary>Since the user needs a new table implementation in the Knex project, use the Task tool to launch the knex-table-implementer agent.</commentary></example> <example>Context: User wants to add a user management system. user: "Create a users table with authentication fields" assistant: "Let me use the knex-table-implementer agent to create the full users table implementation following the project patterns" <commentary>The user is requesting a new table implementation, so the knex-table-implementer agent should be used via the Task tool.</commentary></example>
+model: sonnet
+color: red
+---
+
+You are an expert Knex.js database architect specializing in implementing consistent, production-ready database table structures following established project patterns.
+
+**Your Core Responsibilities:**
+
+You will create complete table implementations in the Knex project by:
+1. Creating database migrations using the project's migration patterns
+2. Implementing DAO classes following the established DAO pattern
+3. Defining TypeScript interfaces for the entities
+4. Ensuring all exports are properly added to index.ts
+
+**Implementation Workflow:**
+
+1. **Migration Creation**:
+   - Inform the user to run `npm run migrate:create` to generate the migration file
+   - Write the migration with all database properties in camelCase
+   - Include proper up() and down() methods
+   - Follow the existing migration patterns in the project
+
+2. **DAO Implementation**:
+   - Create the DAO file at `src/dao/{entityName}/{entityName}.dao.ts`
+   - Extend from IBaseDAO interface
+   - Implement standard CRUD operations (getById, getAll with pagination, create, update, delete)
+   - Use KnexManager.getInstance() for database connections
+   - For related entities, use PostgreSQL's to_jsonb() function for joins
+   - Follow the exact pattern from existing DAOs like SundaysPackageVersionDAO
+
+3. **Interface Definition**:
+   - Create the interface file at `src/interfaces/{entityName}/{entityName}.interfaces.ts`
+   - Define the main entity interface with all properties
+   - Include any related entity interfaces if needed
+   - Ensure TypeScript types are properly defined
+
+4. **Export Configuration**:
+   - Add the new DAO export to src/index.ts
+   - Add the new interface export to src/index.ts
+   - Maintain alphabetical ordering in exports when possible
+
+**Critical Standards You Must Follow**:
+
+- **Naming Conventions**: 
+  - Database columns: camelCase (e.g., createdAt, userId)
+  - Table names: snake_case or lowercase
+  - Class names: PascalCase with DAO suffix
+  - Interface names: Start with 'I' prefix
+
+- **DAO Pattern Requirements**:
+  - Always implement IBaseDAO<T> interface
+  - Include pagination using IDataPaginator
+  - Use async/await for all database operations
+  - Return null for not found scenarios
+  - Use leftJoin with to_jsonb() for related entities
+
+- **Code Structure**:
+  - One DAO class per file
+  - One interface file per entity
+  - Keep related logic together
+  - Use the singleton KnexManager for connections
+
+**Example Patterns to Follow**:
+
+For DAO methods with joins:
+```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;
+}
+```
+
+For paginated results:
+```typescript
+async getAll(limit: number, offset: number): Promise<IDataPaginator<IEntity>> {
+  const query = this._knex("entity");
+  const total = await query.clone().count("* as count").first();
+  const data = await query.clone().limit(limit).offset(offset).orderBy("id", "desc");
+  return {
+    data,
+    total: parseInt(total?.count as string) || 0,
+    limit,
+    offset
+  };
+}
+```
+
+**Quality Checks**:
+
+Before completing any implementation, verify:
+1. Migration file uses camelCase for all properties
+2. DAO follows the exact structure of existing DAOs
+3. Interface properly types all entity properties
+4. All new exports are added to src/index.ts
+5. File paths follow the convention exactly
+6. No unnecessary files are created
+7. Code is consistent with existing patterns
+
+**Important Reminders**:
+- Only edit existing files when possible
+- Never create documentation files unless explicitly requested
+- Follow the CLAUDE.md instructions precisely
+- Maintain consistency with the existing codebase structure
+- Always use the established patterns from sundays-package-version as reference
+
+When you receive a request, first analyze the entity structure needed, then systematically create each component following the established patterns. If any clarification is needed about field types or relationships, ask before proceeding.

package/dist/templates/backend/.env.example

@@ -1,13 +1,13 @@
-# Server
-PORT=3098
-ENVIRONMENT=local
-
-# CORS (comma-separated origins with protocol)
-CORS_ALLOWED_ORIGINS=http://localhost:3098
-
-# Database (uncomment if using db-sql module)
-# SQL_HOST=localhost
-# SQL_PORT=5432
-# SQL_USER=postgres
-# SQL_PASSWORD=
-# SQL_DB_NAME=mydb
+# Server
+PORT=3098
+ENVIRONMENT=local
+
+# CORS (comma-separated origins with protocol)
+CORS_ALLOWED_ORIGINS=http://localhost:3098
+
+# Database (uncomment if using db-sql module)
+# SQL_HOST=localhost
+# SQL_PORT=5432
+# SQL_USER=postgres
+# SQL_PASSWORD=
+# SQL_DB_NAME=mydb

package/dist/templates/backend/.prettierignore

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

package/dist/templates/backend/Dockerfile

@@ -1,14 +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"]
+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/README.md

@@ -1,18 +1,18 @@
-# Sundays Framework Project
-
-This directory contains the starter backend generated by the CLI.
-
-## Quick start
-
-1. Install dependencies:
-   ```
-   npm install
-   ```
-2. Copy `.env.example` to `.env` and set your environment variables.
-3. Start the development server:
-   ```
-   npm run start:dev
-   ```
-
-The server will run on the port specified in your `.env` file.
-
+# Sundays Framework Project
+
+This directory contains the starter backend generated by the CLI.
+
+## Quick start
+
+1. Install dependencies:
+   ```
+   npm install
+   ```
+2. Copy `.env.example` to `.env` and set your environment variables.
+3. Start the development server:
+   ```
+   npm run start:dev
+   ```
+
+The server will run on the port specified in your `.env` file.
+

package/dist/templates/backend/src/app.ts

@@ -1,35 +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);
-
+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/src/common/utils/environment.resolver.ts

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

package/dist/templates/backend/src/common/utils/version.resolver.ts

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

package/dist/templates/backend/src/controllers/health/health.controller.ts

@@ -1,24 +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);
-    }
-  }
+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);
+    }
+  }
 }

package/dist/templates/backend/src/routes/health/health.router.ts

@@ -1,17 +1,17 @@
-import { Router } from 'express';
-import { HealthController } from '../../controllers/health/health.controller';
-
-export class HealthRouter {
-    public router: Router = Router();
-    private readonly healthController: HealthController = new HealthController();
-    constructor() {
-        this.initRoutes();
-    }
-    
-    private initRoutes(): void {
-        this.router.get(
-            '/',
-            this.healthController.getHealthStatus.bind(this.healthController)
-        );
-    }
+import { Router } from 'express';
+import { HealthController } from '../../controllers/health/health.controller';
+
+export class HealthRouter {
+    public router: Router = Router();
+    private readonly healthController: HealthController = new HealthController();
+    constructor() {
+        this.initRoutes();
+    }
+    
+    private initRoutes(): void {
+        this.router.get(
+            '/',
+            this.healthController.getHealthStatus.bind(this.healthController)
+        );
+    }
 }

package/dist/templates/backend/src/routes/index.ts

@@ -1,57 +1,57 @@
-import { Router } from 'express';
-import fs from 'fs';
-import path from 'path';
-
-export class IndexRouter {
-  private _router: Router;
-
-  constructor() {
-    this._router = Router();
-    this.loadRoutes();
-  }
-
-  private loadRoutes(): void {
-    const routesPath = path.join(__dirname);
-
-    const folders = fs.readdirSync(routesPath).filter(file =>
-      fs.statSync(path.join(routesPath, file)).isDirectory()
-    );
-
-    folders.forEach(folder => {
-      const baseName = `${folder}.router`;
-      const tsPath = path.join(routesPath, folder, `${baseName}.ts`);
-      const jsPath = path.join(routesPath, folder, `${baseName}.js`);
-
-      let filePath = '';
-      if (fs.existsSync(tsPath)) {
-        filePath = tsPath;
-      } else if (fs.existsSync(jsPath)) {
-        filePath = jsPath;
-      } else {
-        console.warn(`[⚠] No route file found for: ${folder}`);
-        return;
-      }
-
-      try {
-        const routeModule = require(filePath);
-        const RouterClass =
-          routeModule.default || Object.values(routeModule).find((e) => typeof e === 'function');
-
-        if (RouterClass) {
-          const instance = new (RouterClass as any)();
-          this._router.use(`/${folder}`, instance.router);
-          console.log(`[✔] Route mounted: /${folder} → ${path.basename(filePath)}`);
-        } else {
-          console.warn(`[⚠] No class exported in: ${filePath}`);
-        }
-      } catch (err) {
-        console.error(`[❌] Failed to load router at: ${filePath}`);
-        console.error(err);
-      }
-    });
-  }
-
-  public get router(): Router {
-    return this._router;
-  }
-}
+import { Router } from 'express';
+import fs from 'fs';
+import path from 'path';
+
+export class IndexRouter {
+  private _router: Router;
+
+  constructor() {
+    this._router = Router();
+    this.loadRoutes();
+  }
+
+  private loadRoutes(): void {
+    const routesPath = path.join(__dirname);
+
+    const folders = fs.readdirSync(routesPath).filter(file =>
+      fs.statSync(path.join(routesPath, file)).isDirectory()
+    );
+
+    folders.forEach(folder => {
+      const baseName = `${folder}.router`;
+      const tsPath = path.join(routesPath, folder, `${baseName}.ts`);
+      const jsPath = path.join(routesPath, folder, `${baseName}.js`);
+
+      let filePath = '';
+      if (fs.existsSync(tsPath)) {
+        filePath = tsPath;
+      } else if (fs.existsSync(jsPath)) {
+        filePath = jsPath;
+      } else {
+        console.warn(`[⚠] No route file found for: ${folder}`);
+        return;
+      }
+
+      try {
+        const routeModule = require(filePath);
+        const RouterClass =
+          routeModule.default || Object.values(routeModule).find((e) => typeof e === 'function');
+
+        if (RouterClass) {
+          const instance = new (RouterClass as any)();
+          this._router.use(`/${folder}`, instance.router);
+          console.log(`[✔] Route mounted: /${folder} → ${path.basename(filePath)}`);
+        } else {
+          console.warn(`[⚠] No class exported in: ${filePath}`);
+        }
+      } catch (err) {
+        console.error(`[❌] Failed to load router at: ${filePath}`);
+        console.error(err);
+      }
+    });
+  }
+
+  public get router(): Router {
+    return this._router;
+  }
+}

package/dist/templates/backend/src/server.ts

@@ -1,16 +1,16 @@
-import dotenv from 'dotenv';
-dotenv.config();
-
-const envPort: string = process.env.PORT || '3005';
-
-if (isNaN(parseInt(envPort))) {
-    throw new Error('The port must to be a number');
-}
-
-const PORT: number = parseInt(envPort);
-
-(async () => { })().then(async () => {
-    const { default: app } = await import('./app');
-    app.listen(PORT, () => console.info(`Server up and running on port ${PORT}`));
-});
-
+import dotenv from 'dotenv';
+dotenv.config();
+
+const envPort: string = process.env.PORT || '3005';
+
+if (isNaN(parseInt(envPort))) {
+    throw new Error('The port must to be a number');
+}
+
+const PORT: number = parseInt(envPort);
+
+(async () => { })().then(async () => {
+    const { default: app } = await import('./app');
+    app.listen(PORT, () => console.info(`Server up and running on port ${PORT}`));
+});
+

package/dist/templates/backend/src/types.d.ts

@@ -1,10 +1,10 @@
-import { Request, Response, NextFunction } from 'express';
-
-export interface IBaseController {
-    getAll(req: Request, res: Response, next: NextFunction): Promise<void>;
-    getByUuid(req: Request, res: Response, next: NextFunction): Promise<void>;
-    create(req: Request, res: Response, next: NextFunction): Promise<void>;
-    update(req: Request, res: Response, next: NextFunction): Promise<void>;
-    patch(req: Request, res: Response, next: NextFunction): Promise<void>;
-    delete(req: Request, res: Response, next: NextFunction): Promise<void>;
-}
+import { Request, Response, NextFunction } from 'express';
+
+export interface IBaseController {
+    getAll(req: Request, res: Response, next: NextFunction): Promise<void>;
+    getByUuid(req: Request, res: Response, next: NextFunction): Promise<void>;
+    create(req: Request, res: Response, next: NextFunction): Promise<void>;
+    update(req: Request, res: Response, next: NextFunction): Promise<void>;
+    patch(req: Request, res: Response, next: NextFunction): Promise<void>;
+    delete(req: Request, res: Response, next: NextFunction): Promise<void>;
+}

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

@@ -1,13 +1,13 @@
-# 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
+# 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

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

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

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

@@ -1,17 +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"]
+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"]