opticore-feature-component 1.0.0

package/README.md

@@ -0,0 +1,697 @@
+# opticore-feature-component
+
+OptiCore Feature component est un package qui permet via l'interaction d'une CLI de générer des features dans un projet **OptiCoreJs**.  
+Trois modes de scaffolding sont proposés : Simple Component, Clean Architecture pas à pas, et Full Clean Architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/opticore-feature-component.svg)](https://www.npmjs.com/package/opticore-feature-component)
+
+---
+
+## Table des matières
+
+- [Prérequis](#prérequis)
+- [Installation](#installation)
+- [Lancer le CLI](#lancer-le-cli)
+- [Flux interactif global](#flux-interactif-global)
+- [Option 1 — Simple Component](#option-1--simple-component)
+- [Option 2 — CLEAN Architecture by step](#option-2--clean-architecture-by-step)
+- [Option 3 — Full CLEAN Architecture component](#option-3--full-clean-architecture-component)
+- [Règles de nommage](#règles-de-nommage)
+- [Enregistrement automatique du router](#enregistrement-automatique-du-router)
+- [Contribuer](#contribuer)
+
+---
+
+## Prérequis
+
+- **Node.js** ≥ 18
+- **TypeScript** ≥ 5
+- Un projet qui expose le répertoire `src/features/` à la racine (le CLI y crée les features)
+
+```
+mon-projet > src > app > router > register.router.ts
+```
+
+Le fichier `register.router.ts` se met automatiquement à jour lors de la création du router de la feature
+
+> Si le dossier `features` est absent au lancement du server, le CLI affiche une erreur et s'arrête.
+
+---
+
+## Installation
+
+### En tant que dépendance de développement (recommandé)
+
+```bash
+npm install --save-dev opticore-feature-component
+# ou
+yarn add -D opticore-feature-component
+```
+
+### Globalement
+
+```bash
+npm install -g opticore-feature-component
+```
+
+### Depuis les sources (monorepo)
+
+```bash
+# depuis la racine du package
+npm install
+npm run build
+```
+
+---
+
+## Lancer le CLI
+
+### Avec `npx` ou `npm` (sans installation globale) 
+
+```bash
+npx opticore-feature-component
+```
+```bash
+npm exec opticore-feature-component
+```
+
+### Via le script `package.json` du projet (recommandé)
+
+Ajoutez un script dans le `package.json` de votre projet :
+
+```json
+{
+  "scripts": {
+    "feature": "opticore-feature-component"
+  }
+}
+```
+
+Puis lancez :
+
+```bash
+npm run feature
+# ou
+yarn feature
+```
+
+### Installation globale
+
+```bash
+opticore-feature-component
+```
+
+---
+
+## Flux interactif global
+
+À chaque lancement, le CLI suit toujours ce flux en 3 étapes avant de proposer les options :
+
+```
+╭────────────────────────────────────────────────────╮
+│                                                    │
+│          Welcome to Feature Component CLI          │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+
+  ◆  Please choose the creation principle for your feature :
+  │  ● OptiCoreJs CLEAN Module  (recommended)
+  │  ○ Custom feature
+  └
+
+  ◆  Enter feature's name :
+  │  login
+  └
+
+  ◆  Choose a type of component :
+  │  ○ Simple component
+  │  ○ CLEAN Architecture component by step
+  │  ● Full CLEAN Architecture component  (default)
+  └
+```
+
+**Étape 1 — Principe de création**
+
+| Choix | Comportement |
+|---|---|
+| `OptiCoreJs CLEAN Module` | Active le scaffolding automatisé — continue vers l'étape 2 |
+| `Custom feature` | Affiche un message d'information et quitte (création manuelle) |
+
+**Étape 2 — Nom de la feature**
+
+Le nom doit respecter la règle : `^[a-z][A-Za-z]+$`  
+→ camelCase, commence par une minuscule, minimum 2 caractères.
+
+```
+✅  userProfile
+✅  productOrder
+✅  authToken
+❌  UserProfile   (commence par une majuscule)
+❌  user_profile  (underscore interdit)
+❌  user          (1 seul caractère après la première lettre)
+```
+
+**Étape 3 — Type de composant** → voir les sections suivantes.
+
+> Appuyer sur **Ctrl+C** à n'importe quelle étape annule l'opération et supprime
+> les répertoires éventuellement créés.
+
+---
+
+## Option 1 — Simple Component
+
+Structure plate et pragmatique. Idéal pour des features légères sans couche de domaine.
+
+### Ce qui est généré
+
+```
+src/features/<featureName>/
+├── models/
+│   └── <featureName>.model.ts
+├── repositories/
+│   └── <featureName>.repository.ts
+├── services/
+│   └── <featureName>.service.ts
+├── controllers/
+│   └── <featureName>.controller.ts
+└── routes/
+    ├── <featureName>.router.handler.ts
+    └── <featureName>.router.ts
+```
+
+### Exemple — feature `order`
+
+```
+src/features/order/
+├── models/
+│   └── order.model.ts
+├── repositories/
+│   └── order.repository.ts
+├── services/
+│   └── order.service.ts
+├── controllers/
+│   └── order.controller.ts
+└── routes/
+    ├── order.router.handler.ts
+    └── order.router.ts
+```
+
+Le CLI demande si vous souhaitez des méthodes dans le controller :
+
+```
+  ◆  Do you want to add methods to the controller?
+  │  ● Yes  ○ No
+  └
+
+  ◆  Enter the method names (comma separated):
+  │  create, findAll, findById, update, delete
+  └
+```
+
+### Contenu généré — `order.service.ts`
+
+```typescript
+import { OrderRepository } from "../repositories/order.repository";
+import { OrderModel } from "../models/order.model";
+
+export class OrderService {
+    private readonly repository: OrderRepository;
+
+    constructor() {
+        this.repository = new OrderRepository();
+    }
+
+    async findAll(): Promise<OrderModel[]> {
+        return this.repository.findAll();
+    }
+
+    async findById(id: string): Promise<OrderModel | null> {
+        return this.repository.findById(id);
+    }
+
+    async create(data: Record<string, unknown>): Promise<OrderModel> {
+        const model = new OrderModel(String(Date.now()));
+        // TODO: Map data fields onto model
+        return this.repository.create(model);
+    }
+
+    async update(id: string, data: Record<string, unknown>): Promise<OrderModel | null> {
+        const existing = await this.repository.findById(id);
+        if (!existing) return null;
+        // TODO: Apply data fields onto existing model
+        return this.repository.update(existing);
+    }
+
+    async delete(id: string): Promise<boolean> {
+        return this.repository.delete(id);
+    }
+}
+```
+
+### Contenu généré — `order.controller.ts` (méthodes `create, findAll`)
+
+```typescript
+import { Request, Response } from "express";
+import { ResponseHandler, HttpStatusCode, IResponseHandlerSuccessData } from "opticore-http-response";
+import { OrderService } from "../services/order.service";
+
+export class OrderController {
+    private static buildService(): OrderService {
+        return new OrderService();
+    }
+
+    static async create(req: Request, res: Response): Promise<IResponseHandlerSuccessData | ReturnType<typeof ResponseHandler.error>> {
+        try {
+            const service = OrderController.buildService();
+            const result = await service.create(req.body);
+            return ResponseHandler.success(result, "created", HttpStatusCode.CREATED);
+        } catch (error) {
+            return OrderController.handleError(error);
+        }
+    }
+
+    static async findAll(req: Request, res: Response): Promise<IResponseHandlerSuccessData | ReturnType<typeof ResponseHandler.error>> {
+        try {
+            const service = OrderController.buildService();
+            const results = await service.findAll();
+            return ResponseHandler.success(results, "success", HttpStatusCode.OK);
+        } catch (error) {
+            return OrderController.handleError(error);
+        }
+    }
+
+    private static handleError(error: unknown) {
+        const message = error instanceof Error ? error.message : "Internal server error";
+        return ResponseHandler.error(message, HttpStatusCode.INTERNAL_SERVER_ERROR);
+    }
+}
+```
+
+### Mapping HTTP automatique des méthodes
+
+Le CLI déduit le verbe et le chemin HTTP à partir du nom de méthode :
+
+| Nom de méthode (exemples) | Verbe | Chemin |
+|---|---|---|
+| `findAll`, `getAll` | `GET` | `/<featureName>` |
+| `findById`, `getById`, `getOne` | `GET` | `/<featureName>/:id` |
+| `create`, `add` | `POST` | `/<featureName>` |
+| `update`, `edit` | `PUT` | `/<featureName>/:id` |
+| `delete`, `remove` | `DELETE` | `/<featureName>/:id` |
+| tout autre nom | `GET` | `/<featureName>/<methodName>` |
+
+---
+
+## Option 2 — CLEAN Architecture by step
+
+Mode interactif file-par-file. Le CLI propose chaque composant un à un et ne crée que ceux que vous confirmez. **Tous les fichiers créés sont vides** — aucun template n'est injecté.
+
+### Déroulement
+
+```
+── Domain ──────────────────────────────────────────────────────
+
+  ◆  Entity          →  payment.entity.ts
+  │  ○ Yes  ● No
+  └
+
+  ◆  Event           →  payment.event.ts
+  │  ● Yes  ○ No
+  └
+  ✅  Created: src/features/payment/domain/events/payment.event.ts
+
+  ◆  Exception       →  payment.exception.ts
+  │  ○ Yes  ● No
+  └
+
+── Application ─────────────────────────────────────────────────
+
+  ◆  Repo Interface  →  payment.repository.interface.ts
+  │  ● Yes  ○ No
+  └
+  ✅  Created: src/features/payment/application/ports/repositories/payment.repository.interface.ts
+
+  ◆  Presenter Port  →  payment.presenter.interface.ts
+  │  ○ Yes  ● No
+  └
+
+  ◆  Service Port    →  payment.service.ts
+  │  ○ Yes  ● No
+  └
+
+  ◆  DTO             →  payment.dto.ts
+  │  ● Yes  ○ No
+  └
+  ✅  Created: src/features/payment/application/dtos/payment.dto.ts
+
+  ◆  Use Case        →  payment.usecase.ts
+  │  ● Yes  ○ No
+  └
+  ✅  Created: src/features/payment/application/use-cases/payment.usecase.ts
+
+── Infrastructure ──────────────────────────────────────────────
+
+  ◆  Repo Impl       →  payment.repository.ts
+  │  ● Yes  ○ No
+  └
+  ✅  Created: src/features/payment/infrastructure/adapters/repositories/payment.repository.ts
+
+  ◆  Presenter Impl  →  payment.presenter.ts
+  │  ○ Yes  ● No
+  └
+
+  ◆  Controller      →  payment.controller.ts
+  │  ● Yes  ○ No
+  └
+  ✅  Created: src/features/payment/infrastructure/adapters/controllers/payment.controller.ts
+
+  ◆  Router Handler  →  payment.router.handler.ts
+  │  ○ Yes  ● No
+  └
+
+  ◆  Router          →  payment.router.ts
+  │  ○ Yes  ● No
+  └
+
+🎉  Feature "payment" — 5 file(s) created step by step.
+```
+
+### Résultat pour l'exemple ci-dessus
+
+```
+src/features/payment/
+├── application/
+│   ├── dtos/
+│   │   └── payment.dto.ts                           ← vide
+│   ├── ports/
+│   │   └── repositories/
+│   │       └── payment.repository.interface.ts      ← vide
+│   └── use-cases/
+│       └── payment.usecase.ts                       ← vide
+└── infrastructure/
+    └── adapters/
+        ├── controllers/
+        │   └── payment.controller.ts                ← vide
+        └── repositories/
+            └── payment.repository.ts                ← vide
+```
+
+> **Les répertoires ne sont créés que pour les fichiers confirmés.**  
+> Si aucun fichier n'est sélectionné, rien n'est créé sur le disque.
+
+### Composants disponibles
+
+| Groupe | Label affiché | Fichier créé | Répertoire |
+|---|---|---|---|
+| Domain | Entity | `<n>.entity.ts` | `domain/entities/` |
+| Domain | Event | `<n>.event.ts` | `domain/events/` |
+| Domain | Exception | `<n>.exception.ts` | `domain/exceptions/` |
+| Application | Repo Interface | `<n>.repository.interface.ts` | `application/ports/repositories/` |
+| Application | Presenter Port | `<n>.presenter.interface.ts` | `application/ports/presenters/` |
+| Application | Service Port | `<n>.service.ts` | `application/ports/services/` |
+| Application | DTO | `<n>.dto.ts` | `application/dtos/` |
+| Application | Use Case | `<n>.usecase.ts` | `application/use-cases/` |
+| Infrastructure | Repo Impl | `<n>.repository.ts` | `infrastructure/adapters/repositories/` |
+| Infrastructure | Presenter Impl | `<n>.presenter.ts` | `infrastructure/adapters/presenters/` |
+| Infrastructure | Controller | `<n>.controller.ts` | `infrastructure/adapters/controllers/` |
+| Infrastructure | Router Handler | `<n>.router.handler.ts` | `infrastructure/routes/` |
+| Infrastructure | Router | `<n>.router.ts` | `infrastructure/routes/` |
+
+---
+
+## Option 3 — Full CLEAN Architecture component
+
+Génère l'intégralité de la structure Clean Architecture en une seule commande. Chaque fichier est pré-rempli avec un template TypeScript fonctionnel et prêt à être adapté.
+
+### Ce qui est généré
+
+```
+src/features/<featureName>/
+├── domain/
+│   ├── entities/
+│   │   └── <featureName>.entity.ts
+│   ├── events/
+│   │   └── <featureName>.event.ts
+│   └── exceptions/
+│       └── <featureName>.exception.ts
+├── application/
+│   ├── dtos/
+│   │   └── <featureName>.dto.ts
+│   ├── ports/
+│   │   ├── repositories/
+│   │   │   └── <featureName>.repository.interface.ts
+│   │   ├── presenters/
+│   │   │   └── <featureName>.presenter.interface.ts
+│   │   └── services/
+│   │       └── <featureName>.service.ts
+│   └── use-cases/
+│       └── <featureName>.usecase.ts
+└── infrastructure/
+    ├── adapters/
+    │   ├── controllers/
+    │   │   └── <featureName>.controller.ts
+    │   ├── repositories/
+    │   │   └── <featureName>.repository.ts
+    │   └── presenters/
+    │       └── <featureName>.presenter.ts
+    └── routes/
+        ├── <featureName>.router.handler.ts
+        └── <featureName>.router.ts
+```
+
+13 fichiers, 12 répertoires — générés en une seule interaction.
+
+### Exemple — feature `invoice`
+
+Seule question posée pendant la génération : les méthodes du controller.
+
+```
+  ◆  Do you want to add methods to the controller?
+  │  ● Yes  ○ No
+  └
+
+  ◆  Enter the method names (comma separated):
+  │  create, findAll, findById, update, delete
+  └
+
+✅ Entity created:                src/features/invoice/domain/entities/invoice.entity.ts
+✅ Event created:                 src/features/invoice/domain/events/invoice.event.ts
+✅ Exception created:             src/features/invoice/domain/exceptions/invoice.exception.ts
+✅ Repository interface created:  src/features/invoice/application/ports/repositories/invoice.repository.interface.ts
+✅ Presenter interface created:   src/features/invoice/application/ports/presenters/invoice.presenter.interface.ts
+✅ Service interface created:     src/features/invoice/application/ports/services/invoice.service.ts
+✅ DTO created:                   src/features/invoice/application/dtos/invoice.dto.ts
+✅ UseCase created:               src/features/invoice/application/use-cases/invoice.usecase.ts
+✅ Repository implementation:     src/features/invoice/infrastructure/adapters/repositories/invoice.repository.ts
+✅ Presenter implementation:      src/features/invoice/infrastructure/adapters/presenters/invoice.presenter.ts
+✅ Controller created:            src/features/invoice/infrastructure/adapters/controllers/invoice.controller.ts
+✅ Router Handler created:        src/features/invoice/infrastructure/routes/invoice.router.handler.ts
+✅ Router created:                src/features/invoice/infrastructure/routes/invoice.router.ts
+✅ register.router.ts updated with InvoiceRouter.
+
+🎉  Feature "invoice" scaffolded with Clean Architecture!
+```
+
+### Contenu généré — `invoice.entity.ts`
+
+```typescript
+/**
+ * InvoiceEntity — Domain Entity
+ * Represents the core business object for the "invoice" feature.
+ * No framework dependency, pure business logic only.
+ */
+export class InvoiceEntity {
+    private readonly _id: string;
+    private _createdAt: Date;
+    private _updatedAt: Date;
+
+    constructor(
+        id: string,
+        // TODO: Add your business properties here
+        createdAt?: Date,
+        updatedAt?: Date,
+    ) {
+        this._id = id;
+        this._createdAt = createdAt ?? new Date();
+        this._updatedAt = updatedAt ?? new Date();
+        this.validate();
+    }
+
+    get id(): string { return this._id; }
+    get createdAt(): Date { return this._createdAt; }
+    get updatedAt(): Date { return this._updatedAt; }
+
+    public touch(): void {
+        this._updatedAt = new Date();
+    }
+
+    public toSnapshot(): Record<string, unknown> {
+        return { id: this._id, createdAt: this._createdAt, updatedAt: this._updatedAt };
+    }
+
+    private validate(): void {
+        if (!this._id || this._id.trim().length === 0) {
+            throw new Error(`[InvoiceEntity] id must not be empty.`);
+        }
+        // TODO: Add your domain invariant checks here
+    }
+}
+```
+
+### Contenu généré — `invoice.usecase.ts`
+
+```typescript
+import { IInvoiceRepository } from "../ports/repositories/invoice.repository.interface";
+import { InvoiceEntity } from "../../domain/entities/invoice.entity";
+import {
+    CreateInvoiceDto,
+    UpdateInvoiceDto,
+    InvoiceResponseDto,
+    InvoiceDtoMapper,
+} from "../dtos/invoice.dto";
+
+/**
+ * InvoiceUseCase — Application Use Case
+ *
+ * Orchestrates business operations for the "invoice" feature.
+ * Depends only on the repository port (interface), never on a concrete implementation.
+ */
+export class InvoiceUseCase {
+    constructor(private readonly repository: IInvoiceRepository) {}
+
+    async findAll(): Promise<InvoiceResponseDto[]> {
+        const entities = await this.repository.findAll();
+        return InvoiceDtoMapper.toResponseList(entities);
+    }
+
+    async findById(id: string): Promise<InvoiceResponseDto | null> {
+        const entity = await this.repository.findById(id);
+        if (!entity) return null;
+        return InvoiceDtoMapper.toResponse(entity);
+    }
+
+    async create(dto: CreateInvoiceDto): Promise<InvoiceResponseDto> {
+        const id = crypto.randomUUID();
+        const entity = new InvoiceEntity(id /* TODO: pass dto fields */);
+        const saved = await this.repository.create(entity);
+        return InvoiceDtoMapper.toResponse(saved);
+    }
+
+    async update(dto: UpdateInvoiceDto): Promise<InvoiceResponseDto | null> {
+        const existing = await this.repository.findById(dto.id);
+        if (!existing) return null;
+        existing.touch();
+        const updated = await this.repository.update(existing);
+        if (!updated) return null;
+        return InvoiceDtoMapper.toResponse(updated);
+    }
+
+    async delete(id: string): Promise<boolean> {
+        return this.repository.delete(id);
+    }
+}
+```
+
+### Contenu généré — `invoice.router.handler.ts` (méthodes `create, findAll, findById`)
+
+```typescript
+import { OpticoreRouting, ICustomContext, IMultipleRouteDefinition } from "opticore-router";
+import { InvoiceController } from "../adapters/controllers/invoice.controller";
+
+export const InvoiceHandlerRouter: () => IMultipleRouteDefinition = () => {
+    return OpticoreRouting.routes(
+        InvoiceController,
+        [
+            {
+                path: `/invoice`,
+                method: "post",
+                middlewares: [],
+                handler: async (ctx: ICustomContext) => await InvoiceController.create(ctx.req, ctx.res)
+            },
+            {
+                path: `/invoice`,
+                method: "get",
+                middlewares: [],
+                handler: async (ctx: ICustomContext) => await InvoiceController.findAll(ctx.req, ctx.res)
+            },
+            {
+                path: `/invoice/:id`,
+                method: "get",
+                middlewares: [],
+                handler: async (ctx: ICustomContext) => await InvoiceController.findById(ctx.req, ctx.res)
+            }
+        ]
+    );
+};
+```
+
+---
+
+## Règles de nommage
+
+Le nom de la feature est soumis à validation stricte :
+
+| Règle | Détail |
+|---|---|
+| Format | camelCase — `^[a-z][A-Za-z]+$` |
+| Premier caractère | Minuscule obligatoire |
+| Longueur minimale | 2 caractères |
+| Caractères autorisés | Lettres uniquement (a-z, A-Z) |
+| Caractères interdits | Chiffres, underscore, tiret, espaces |
+
+Le CLI rejette le nom si la feature existe déjà dans `src/features/`.
+
+---
+
+## Enregistrement automatique du router
+
+Lors de la génération des options **Simple Component** et **Full CLEAN Architecture**, le router de la feature est automatiquement enregistré dans `src/app/router/register.router.ts`.
+
+**Avant** :
+
+```typescript
+export const registerRouter: () => TFeatureRoutes[] = (): TFeatureRoutes[] => {
+    return new OpticoreRegisterRouter().registered([
+        AuthenticationRouter,
+    ]);
+}
+```
+
+**Après** (ajout de `InvoiceRouter`) :
+
+```typescript
+import { InvoiceRouter } from "../../features/invoice/infrastructure/routes/invoice.router";
+
+export const registerRouter: () => TFeatureRoutes[] = (): TFeatureRoutes[] => {
+    return new OpticoreRegisterRouter().registered([
+        AuthenticationRouter,
+        InvoiceRouter,
+    ]);
+}
+```
+
+> Si `register.router.ts` est introuvable, un avertissement est affiché mais la génération continue normalement.  
+> En mode **CLEAN by step**, l'enregistrement automatique n'est pas effectué car les fichiers sont vides.
+
+---
+
+## Récapitulatif des options
+
+| Option | Fichiers créés | Contenu | Interaction |
+|---|---|---|---|
+| Simple Component | 6 | Avec template | Nom des méthodes du controller |
+| CLEAN by step | 0 à 13 au choix | **Vides** | Confirmation pour chaque fichier |
+| Full CLEAN Architecture | 13 | Avec template | Nom des méthodes du controller |
+
+---
+
+## Contribuer
+
+`opticore-feature-component` est open source.  
+Pour contribuer : clonez le dépôt et ouvrez une pull request.
+
+- **Repository** : [github.com/guyzoum77/opticore-feature-cli](https://github.com/guyzoum77/opticore-feature-cli)
+- **Issues** : [github.com/guyzoum77/opticore-feature-cli/issues](https://github.com/guyzoum77/opticore-feature-cli/issues)
+
+**Auteur** : Guy-serge Kouacou — Licence MIT