@dawudesign/node-hexa-cli 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,282 @@
+# @dawudesign/node-hexa-cli
+
+> Scaffold and enforce **NestJS Hexagonal DDD** architecture from the command line.
+
+**node-hexa** automates the repetitive parts of clean architecture in NestJS:
+
+- **Scaffold** — generates a full bounded context with dependency injection pre-wired, in one command
+- **Enforce** — statically analyzes your TypeScript source and reports architecture violations
+- **Document** — exports a Mermaid diagram and architecture report as Markdown or SVG
+
+---
+
+## Requirements
+
+- **Node.js ≥ 20**
+
+---
+
+## Installation
+
+```bash
+npm install -g @dawudesign/node-hexa-cli
+```
+
+Verify:
+
+```bash
+node-hexa --version
+node-hexa --help
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Create a new NestJS Hexagonal DDD project
+node-hexa init my-app
+cd my-app
+
+# 2. Start the server
+pnpm start:dev
+
+# 3. Verify architecture is clean
+node-hexa check .
+# ✓ Architecture check passed
+```
+
+---
+
+## Commands
+
+### `init`
+
+Creates a new NestJS project with the complete Hexagonal DDD structure.
+
+```bash
+node-hexa init <name>
+```
+
+```bash
+node-hexa init my-app
+```
+
+Generates:
+
+```
+my-app/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   └── contexts/
+│       └── iam/
+│           ├── iam.module.ts
+│           ├── domain/
+│           │   ├── entities/user.entity.ts
+│           │   └── ports/user.repository.port.ts
+│           ├── application/
+│           │   └── use-cases/create-user.usecase.ts
+│           └── infrastructure/
+│               ├── http/user.controller.ts
+│               └── persistence/in-memory-user.repository.ts
+└── node-hexa.config.json
+```
+
+---
+
+### `generate context`
+
+Generates a complete bounded context inside an existing NestJS project.
+
+```bash
+node-hexa generate context <name>
+```
+
+```bash
+cd my-app
+node-hexa generate context orders
+# ✓ Context 'orders' generated at src/contexts/orders/
+# → Import OrdersModule in your AppModule to activate it.
+```
+
+---
+
+### `generate usecase`
+
+Generates a use case with its DTO and Vitest spec inside an existing bounded context.
+
+```bash
+node-hexa generate usecase <name> <context>
+```
+
+```bash
+node-hexa generate usecase delete-user iam
+# ✓ Use case 'delete-user' generated in context 'iam'
+```
+
+Generated files:
+```
+src/contexts/iam/application/use-cases/
+├── delete-user.usecase.ts
+├── delete-user.dto.ts
+└── delete-user.usecase.spec.ts
+```
+
+---
+
+### `generate aggregate`
+
+Generates a full DDD aggregate (entity, value object, port, use case, in-memory repository, HTTP controller, NestJS module).
+
+```bash
+node-hexa generate aggregate <name> <context>
+```
+
+```bash
+node-hexa generate aggregate product catalog
+# ✓ Aggregate 'product' generated in context 'catalog'
+```
+
+---
+
+### `check`
+
+Checks architecture rules — exits `0` if clean, `1` if violations found. Designed for CI/CD.
+
+```bash
+node-hexa check <path> [--watch]
+```
+
+```bash
+# One-shot (CI)
+node-hexa check .
+
+# Watch mode (development)
+node-hexa check . --watch
+```
+
+Output:
+```
+✓ Architecture check passed
+```
+or:
+```
+✗ Architecture violations detected
+
+  [CRITICAL] Domain must not depend on infrastructure → UserEntity
+  [HIGH] Application must not depend on infrastructure → CreateUserUseCase
+```
+
+---
+
+### `analyze`
+
+Full analysis: layers, violations, bounded contexts, Mermaid diagram, and score.
+
+```bash
+node-hexa analyze <path>
+```
+
+```bash
+node-hexa analyze .
+```
+
+---
+
+### `list`
+
+Lists all bounded contexts and their components.
+
+```bash
+node-hexa list <path>
+```
+
+```bash
+node-hexa list .
+```
+
+Output:
+```
+Bounded Contexts (2)
+
+  IAM
+    Entities      : user.entity
+    Ports         : user.repository.port
+    Use Cases     : create-user.usecase
+
+  CATALOG
+    Entities      : product.entity
+    Ports         : product.repository.port
+    Use Cases     : create-product.usecase
+```
+
+---
+
+### `docs`
+
+Generates an `architecture.md` at the project root with the Mermaid diagram, violations, and score.
+
+```bash
+node-hexa docs <path>
+```
+
+```bash
+node-hexa docs .
+# Architecture documentation generated: ./architecture.md
+```
+
+---
+
+### `graph`
+
+Generates an `architecture.svg` dependency graph (requires `@mermaid-js/mermaid-cli`).
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+node-hexa graph .
+# Architecture graph generated: ./architecture.svg
+```
+
+---
+
+## Configuration
+
+`node-hexa.config.json` at the project root (created by `init`, all keys optional):
+
+```json
+{
+  "architecture": "hexagonal-ddd",
+  "strict": true,
+  "contextsDir": "src/contexts"
+}
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `architecture` | `string` | required | Architecture type — `hexagonal-ddd` |
+| `strict` | `boolean` | `true` | `false` silences `MEDIUM` violations |
+| `contextsDir` | `string` | `"src/contexts"` | Path to bounded contexts directory |
+
+---
+
+## Violation rules
+
+| Violation | Severity | Score penalty |
+|---|---|---|
+| Domain imports from infrastructure / adapter | `CRITICAL` | −25 pts |
+| Domain imports from application | `CRITICAL` | −25 pts |
+| Application imports from infrastructure / adapter | `HIGH` | −15 pts |
+| Domain imports a framework (`@nestjs/*`, `prisma`, etc.) | `CRITICAL` | −25 pts |
+
+Score = `100 − sum of penalties`, minimum 0.
+
+---
+
+## License
+
+`activate` command required for production use:
+
+```bash
+node-hexa activate <your-license-key>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dawudesign/node-hexa-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "CLI to scaffold and analyze NestJS Hexagonal DDD projects",
   "keywords": [
     "nestjs",