@currentjs/gen 0.3.2 → 0.5.0

package/dist/generators/templates/data/cursorRulesTemplate

@@ -3,11 +3,14 @@
 ## Architecture Overview
 This is a CurrentJS framework application using clean architecture principles with the following layers:
 - **Controllers**: Handle HTTP requests/responses and route handling
+- **UseCases**: Orchestrate handler calls in sequence
 - **Services**: Contain business logic and orchestrate operations
 - **Stores**: Provide data access layer and database operations
 - **Domain Entities**: Core business models
 - **Views**: HTML templates for server-side rendering
 
+All layers (except Domain and Views) are auto-wired via **dependency injection** — the generator scans `@Injectable` and `@Controller` decorators, resolves constructor dependencies, and generates wiring code in `src/app.ts`.
+
 ## Commands
 
 ```bash
@@ -26,9 +29,10 @@ current diff [module] # Show differences between generated and current code
 1. Create an empty app (`current create app`) – this step is already done.
 2. Create a new module: `current create module Name`
 3. In the module's yaml file, define module's:
- - model(s)
- - routes & actions
- - permissions
+ - domain (aggregates and value objects)
+ - useCases (with input/output and handlers)
+ - api endpoints (with auth)
+ - web pages (with auth and onSuccess/onError)
 4. Generate TypeScript files: `current generate Name`
 5. If required, make changes in the:
  - model (i.e. some specific business rules or validations)
@@ -38,7 +42,7 @@ current diff [module] # Show differences between generated and current code
 --- If needed more than CRUD: ---
 
 7. Define action in the service by creating a method
-8. Describe this action in the module's yaml. Additionaly, you may define routes and permissions.
+8. Describe this action in the module's yaml under useCases. Additionally, you may define api/web endpoints.
 9. `current generate Modulename`
 10. commit changes: `current commit`
 
@@ -54,189 +58,223 @@ current diff [module] # Show differences between generated and current code
 
 **Complete Module Example:**
 ```yaml
-models:
-  - name: Post                          # Entity name (capitalized)
-    fields:
-      - name: title                     # Field name
-        type: string                    # Field type: string, number, boolean, datetime
-        required: true                  # Validation requirement
-      - name: content
-        type: string
-        required: true
-      - name: authorId
-        type: number
-        required: true
-      - name: publishedAt
-        type: datetime
-        required: false
-      - name: status
-        type: string
-        required: true
-
-api:                                    # REST API configuration
-  prefix: /api/posts                    # Base URL for API endpoints
-  model: Post                           # Optional: which model this API serves (defaults to first model)
-  endpoints:
-    - method: GET                       # HTTP method
-      path: /                           # Relative path (becomes /api/posts/)
-      action: list                      # Action name (references actions section)
-    - method: GET
-      path: /:id                        # Path parameter
-      action: get
-    - method: POST
-      path: /
-      action: create
-    - method: PUT
-      path: /:id
-      action: update
-    - method: DELETE
-      path: /:id
-      action: delete
-    - method: POST                      # Custom endpoint
-      path: /:id/publish
-      action: publish
-      model: Post                       # Optional: override model for specific endpoint
-
-routes:                                 # Web interface configuration
-  prefix: /posts                        # Base URL for web pages
-  model: Post                           # Optional: which model this route serves (defaults to first model)
-  strategy: [toast, back]               # Default success strategies for forms
-  endpoints:
-    - path: /                           # List page
-      action: list
-      view: postList                    # Template name
-    - path: /:id                        # Detail page
-      action: get
-      view: postDetail
-    - path: /create                     # Create form page
-      action: empty                     # No data loading action
-      view: postCreate
-    - path: /:id/edit                   # Edit form page
-      action: get                       # Load existing data
-      view: postUpdate
-      model: Post                       # Optional: override model for specific endpoint
-
-actions:                                # Business logic mapping
-  list:
-    handlers: [Post:default:list]       # Use built-in list handler
-  get:
-    handlers: [Post:default:get]    # Use built-in get handler
-  create:
-    handlers: [Post:default:create]     # Built-in create
-  update:
-    handlers: [Post:default:update]
-  delete:
-    handlers: [                         # Chain multiple handlers
-      Post:checkCanDelete,              # Custom business logic
-      Post:default:delete
-    ]
-  publish:                              # Custom action
-    handlers: [
-      Post:default:get,             # Fetch entity
-      Post:validateForPublish,          # Custom validation
-      Post:updatePublishStatus          # Custom update logic
-    ]
-
-permissions:                            # Role-based access control
-  - role: all
-    actions: [list, get]                # Anyone (including anonymous)
-  - role: authenticated
-    actions: [create]                   # Must be logged in
-  - role: owner
-    actions: [update, publish]          # Entity owner permissions
-  - role: admin
-    actions: [update, delete, publish]  # Admin role permissions
-  - role: editor
-    actions: [publish]                  # Editor role permissions
+domain:
+  aggregates:
+    Post:
+      root: true                          # Marks as aggregate root
+      fields:
+        title: { type: string, required: true }
+        content: { type: string, required: true }
+        authorId: { type: id, required: true }
+        publishedAt: { type: datetime }
+        status: { type: string, required: true }
+
+useCases:
+  Post:
+    list:
+      input:
+        pagination: { type: offset, defaults: { limit: 20, maxLimit: 100 } }
+      output: { from: Post, pagination: true }
+      handlers: [default:list]            # Built-in list handler
+    get:
+      input: { identifier: id }
+      output: { from: Post }
+      handlers: [default:get]             # Built-in get handler
+    create:
+      input: { from: Post }
+      output: { from: Post }
+      handlers: [default:create]          # Built-in create
+    update:
+      input: { identifier: id, from: Post, partial: true }
+      output: { from: Post }
+      handlers: [default:update]
+    delete:
+      input: { identifier: id }
+      output: void
+      handlers: [                         # Chain multiple handlers
+        checkCanDelete,                   # Custom → PostService.checkCanDelete(result, input)
+        default:delete                    # Built-in delete
+      ]
+    publish:                              # Custom action
+      input: { identifier: id }
+      output: { from: Post }
+      handlers: [
+        default:get,                      # Fetch entity
+        validateForPublish,               # Custom → PostService.validateForPublish(result, input)
+        updatePublishStatus               # Custom → PostService.updatePublishStatus(result, input)
+      ]
+
+api:                                      # REST API configuration
+  Post:                                   # Keyed by model name
+    prefix: /api/posts                    # Base URL for API endpoints
+    endpoints:
+      - method: GET                       # HTTP method
+        path: /                           # Relative path (becomes /api/posts/)
+        useCase: Post:list                # References useCases.Post.list
+        auth: all                         # Public access
+      - method: GET
+        path: /:id                        # Path parameter
+        useCase: Post:get
+        auth: all
+      - method: POST
+        path: /
+        useCase: Post:create
+        auth: authenticated               # Must be logged in
+      - method: PUT
+        path: /:id
+        useCase: Post:update
+        auth: [owner, admin]              # Owner OR admin (OR logic)
+      - method: DELETE
+        path: /:id
+        useCase: Post:delete
+        auth: [owner, admin]
+      - method: POST                      # Custom endpoint
+        path: /:id/publish
+        useCase: Post:publish
+        auth: [owner, editor, admin]
+
+web:                                      # Web interface configuration
+  Post:                                   # Keyed by model name
+    prefix: /posts                        # Base URL for web pages
+    layout: main_view                     # Layout template name
+    pages:
+      - path: /                           # List page
+        useCase: Post:list
+        view: postList                    # Template name
+        auth: all
+      - path: /:id                        # Detail page
+        useCase: Post:get
+        view: postDetail
+        auth: all
+      - path: /create                     # Create form (GET = show form)
+        method: GET
+        view: postCreate
+        auth: authenticated
+      - path: /create                     # Create form (POST = submit)
+        method: POST
+        useCase: Post:create
+        auth: authenticated
+        onSuccess:                        # What happens after successful submission
+          redirect: /posts/:id
+          toast: "Post created successfully"
+        onError:
+          stay: true
+          toast: error
+      - path: /:id/edit                   # Edit form (GET = show form)
+        method: GET
+        useCase: Post:get                 # Load existing data
+        view: postUpdate
+        auth: [owner, admin]
+      - path: /:id/edit                   # Edit form (POST = submit)
+        method: POST
+        useCase: Post:update
+        auth: [owner, admin]
+        onSuccess:
+          back: true
+          toast: "Post updated successfully"
 ```
 
-**Make sure no `ID`/`owner id`/`is deleted` fields are present in the model definition, since it's added automatically**
-
-**Field Types:**
-- `string` - Text data
-- `number` - Numeric data (integer or float)
-- `boolean` - True/false values
-- `datetime` - Date and time values
-- `ModelName` - Relationship to another model (e.g., `Owner`, `User`, `Post`)
-
-**Multi-Model Endpoint Configuration:**
+**Make sure no `id`/`owner_id`/`created_at`/`updated_at`/`deleted_at` fields are present in the domain definition, since they are added automatically**
 
-When working with multiple models in a single module, you have flexible options:
+**Use case option: withChild (aggregate root with child entities)**
 
-**Option 1: Per-Endpoint Model Override**
-
-Specify `model` on individual endpoints to override the section default:
+Per use case you can set `withChild: true` (default `false`) to show child entities on the root's pages. Only applies when the entity has child entities (e.g. Invoice with InvoiceItem). Ignored if there are no child entities.
+- **list** + `withChild: true`: adds a link column on the list page to the child entity list (no extra loading).
+- **get** + `withChild: true`: on the detail page, renders a table of child entities below the main card, with View/Edit/Add links.
 
+Example:
 ```yaml
-models:
-  - name: Cat
-  - name: Person
-
-routes:
-  prefix: /cat
-  model: Cat  # Default for this section
-  endpoints:
-    - path: /create
-      view: catCreate
-      # Uses Cat model
-    
-    - path: /createOwner
-      view: ownerCreate
-      model: Person  # Override for this endpoint
+useCases:
+  Invoice:
+    get:
+      withChild: true
+      input: { identifier: id }
+      output: { from: Invoice }
+      handlers: [default:get]
 ```
 
-**Option 2: Multiple API/Routes Sections**
+**Field Types:**
+- `string` - Text data (VARCHAR in database)
+- `number` - Numeric data (INT/DECIMAL in database)
+- `integer` - Integer data (INT in database)
+- `decimal` - Decimal data (DECIMAL in database)
+- `boolean` - True/false values (BOOLEAN in database)
+- `datetime` - Date and time values (DATETIME in database)
+- `date` - Date values (DATE in database)
+- `id` - Foreign key reference (INT in database)
+- `json` - JSON data
+- `enum` - Enumerated values (use with `values: [...]`)
+- `ModelName` - Relationship to another model (e.g., `Owner`, `User`, `Post`)
+
+**Multi-Model Configuration:**
 
-Use arrays to organize endpoints by model:
+When working with multiple models in a single module, each model is a separate key in `api` and `web`:
 
 ```yaml
-routes:
-  - prefix: /cat
-    model: Cat
-    endpoints: [...]
-  
-  - prefix: /person
-    model: Person
-    endpoints: [...]
-
-# Same works for api sections
+domain:
+  aggregates:
+    Cat:
+      root: true
+      fields:
+        name: { type: string, required: true }
+    Person:
+      root: true
+      fields:
+        name: { type: string, required: true }
+        email: { type: string, required: true }
+
 api:
-  - prefix: /api/cat
-    model: Cat
-    endpoints: [...]
-  
-  - prefix: /api/person
-    model: Person
-    endpoints: [...]
+  Cat:
+    prefix: /api/cat
+    endpoints:
+      - method: GET
+        path: /
+        useCase: Cat:list
+        auth: all
+  Person:
+    prefix: /api/person
+    endpoints:
+      - method: GET
+        path: /
+        useCase: Person:list
+        auth: all
+
+web:
+  Cat:
+    prefix: /cat
+    layout: main_view
+    pages:
+      - path: /
+        useCase: Cat:list
+        view: catList
+        auth: all
+  Person:
+    prefix: /person
+    layout: main_view
+    pages:
+      - path: /
+        useCase: Person:list
+        view: personList
+        auth: all
 ```
 
-**Model Resolution Priority:**
-1. `endpoint.model` (explicit override)
-2. Inferred from action handler (e.g., `Person:default:create`)
-3. `api.model` or `routes.model` (section default)
-4. First model in `models[]` array (fallback)
-
 **Model Relationships:**
 
-Define relationships by using another model's name as the field type:
+Define relationships by using another model's name as the field type in `domain.aggregates`:
 
 ```yaml
-models:
-  - name: Owner
-    fields:
-      - name: name
-        type: string
-        required: true
-
-  - name: Cat
-    fields:
-      - name: name
-        type: string
-        required: true
-      - name: owner
-        type: Owner        # Creates relationship with Owner model
-        required: true     # Auto-generates foreign key: ownerId
-        displayFields: [name]  # Optional: fields to show in dropdowns
+domain:
+  aggregates:
+    Owner:
+      root: true
+      fields:
+        name: { type: string, required: true }
+
+    Cat:
+      root: true
+      fields:
+        name: { type: string, required: true }
+        owner: { type: Owner, required: true }   # Creates relationship with Owner model
 ```
 
 **Generated Behavior:**
@@ -255,90 +293,146 @@ Foreign keys are auto-generated following the pattern `fieldName + 'Id'`:
 
 The foreign key always references the `id` field of the related model.
 
-**🔄 Handler vs Action Architecture:**
+**🔄 Handler vs Use Case Architecture:**
 - **Handler**: Creates a separate service method (one handler = one service method)
-- **Action**: Virtual controller concept that calls handler methods step-by-step
+- **Use Case**: Defined under `useCases.ModelName.actionName`, calls handler methods step-by-step
+- **UseCase reference**: Used in `api`/`web` endpoints as `ModelName:actionName` (e.g., `Post:list`)
+
+**Built-in Handlers (used in `useCases.*.*.handlers`):**
+- `default:list` - Creates service method with pagination parameters
+- `default:get` - Creates service method named `get` with ID parameter
+- `default:create` - Creates service method with DTO parameter
+- `default:update` - Creates service method with ID and DTO parameters
+- `default:delete` - Creates service method with ID parameter
 
-**Built-in Action Handlers:**
-- `ModelName:default:list` - Creates service method with pagination parameters
-- `ModelName:default:get` - Creates service method named `get` with ID parameter
-- `ModelName:default:create` - Creates service method with DTO parameter
-- `ModelName:default:update` - Creates service method with ID and DTO parameters
-- `ModelName:default:delete` - Creates service method with ID parameter
+Note: Handlers within `useCases` do NOT need a model prefix because the model is already the key.
 
-**Custom Action Handlers:**
-- `ModelName:customMethodName` - Creates service method that accepts `result, context` parameters
+**Custom Handlers:**
+- `customMethodName` - Creates service method that accepts `(result, input)` parameters
 - `result`: Result from previous handler (or `null` if it's the first handler)
-- `context`: The request context object
+- `input`: The parsed input DTO
 - Each handler generates a separate method in the service
 - User can customize the implementation after generation
 
-**🔗 Multiple Handlers per Action:**
-When an action has multiple handlers, each handler generates a separate service method, and the controller action calls them sequentially. The action returns the result from the last handler.
+**🔗 Multiple Handlers per Use Case:**
+When a use case has multiple handlers, each handler generates a separate service method, and the use case orchestrator calls them sequentially. The use case returns the result from the last handler.
 
 **Parameter Passing Rules:**
-- **Default handlers** (`:default:`): Receive standard parameters (id, pagination, DTO, etc.)
-- **Custom handlers**: Receive `(result, context)` where:
+- **Default handlers** (`default:*`): Receive standard parameters (id, pagination, DTO, etc.)
+- **Custom handlers**: Receive `(result, input)` where:
   - `result`: Result from previous handler, or `null` if it's the first handler
-  - `context`: Request context object
-
-**Handler Format Examples:**
-- `Post:default:list` - Creates Post service method `list(page, limit)`
-- `Post:default:get` - Creates Post service method `get(id)`
-- `Post:validateContent` - Creates Post service method `validateContent(result, context)`
-- `Comment:notifySubscribers` - Creates Comment service method `notifySubscribers(result, context)`
-
-**Strategy Options (for forms):**
-- `toast` - Success toast notification
-- `back` - Navigate back in browser history
-- `message` - Inline success message
-- `modal` - Modal success dialog
-- `redirect` - Redirect to specific URL
-- `refresh` - Reload current page
+  - `input`: Parsed input DTO
+
+**Handler Format Examples (inside `useCases`):**
+- `default:list` - Creates service method `list(page, limit)`
+- `default:get` - Creates service method `get(id)`
+- `validateContent` - Creates service method `validateContent(result, input)`
+- `notifySubscribers` - Creates service method `notifySubscribers(result, input)`
+
+**Form Success/Error Handling (in `web` pages):**
+
+Instead of a separate `strategy` field, use `onSuccess` and `onError` on web page endpoints:
+```yaml
+onSuccess:
+  redirect: /posts/:id   # Redirect to URL
+  toast: "Saved!"        # Show toast notification
+  back: true             # Navigate back in browser history
+  stay: true             # Stay on current page
+onError:
+  stay: true             # Stay on current page
+  toast: error           # Show error toast
+```
 
-**Permission Roles:**
+The template generator converts `onSuccess` options into `data-strategy` attributes on HTML forms.
+
+**Auth Configuration (per endpoint in `api` and `web`):**
 - `all` - Anyone (including anonymous users)
 - `authenticated` - Any logged-in user
-- `owner` - User who created the entity
+- `owner` - User who created the entity (checks `ownerId` field)
 - `admin`, `editor`, `user` - Custom roles from JWT token
-- Multiple roles can be specified for each action
+- `[owner, admin]` - Array syntax: user must match ANY (OR logic). Privileged roles bypass ownership check.
 
 **Generated Files from Configuration:**
 - Domain entity class (one per model)
-- Service class (one per model)
+- Use case orchestrator (one per model)
+- Service class with handler methods (one per model)
+- Input/Output DTOs (one per use case)
 - API controller with REST endpoints (one per model)
 - Web controller with page rendering (one per model)
 - Store class with database operations (one per model)
 - HTML templates for all views
-- TypeScript interfaces and DTOs
 
 **Multi-Model Support:**
-- Each model gets its own service, controller, and store
-- Use `model` parameter in `api` and `routes` to specify which model to use (defaults to first model)
-- Use `model` parameter on individual endpoints to override model for specific endpoints
-- Action handlers use `modelname:action` format to specify which model's service method to call
+- Each model gets its own Service, UseCase, Controller, and Store classes
+- In `api`/`web`, each model is a separate key (e.g., `api.Cat`, `api.Person`)
+- UseCase references use `ModelName:actionName` format (e.g., `Post:list`, `Person:create`)
+- Handlers within `useCases` do not need model prefix (model is already the key)
 - Controllers and services are generated per model, not per module
 
+## Dependency Injection & Wiring
+
+The application uses a decorator-driven DI system. All wiring is auto-generated in `src/app.ts` between `// currentjs:controllers:start` and `// currentjs:controllers:end` markers. **Never edit this block manually** — it is regenerated on each `current generate`.
+
+### `@Injectable` Decorator
+
+Lives in `src/system.ts`. Marks a class for automatic DI discovery:
+
+```typescript
+import { Injectable } from '../../../../system';
+
+@Injectable()
+export class MyService {
+  constructor(private myStore: MyStore) {}
+}
+```
+
+Generated Stores, Services, and UseCases already have `@Injectable()`. Controllers use `@Controller()` from `@currentjs/router` instead.
+
+### Adding Custom Classes to DI
+
+If you create a new class that should be auto-wired:
+1. Add `@Injectable()` decorator (import from `src/system.ts`)
+2. Declare dependencies as constructor parameters with their types
+3. Run `current generate` — the class will be auto-imported and instantiated in `app.ts`
+4. Run `current commit` to preserve your changes
+
+### How Wiring Works
+
+The generator:
+1. Scans all module `.ts` files for `@Injectable` and `@Controller` decorators
+2. Parses constructor parameters to build a dependency graph
+3. Topologically sorts classes (stores → services → use cases → controllers)
+4. Generates imports, instantiations, and the `controllers` array in `app.ts`
+
+Database provider instances are injected into stores based on `app.yaml` configuration (global, with optional per-module overrides). Both npm packages and local file paths are supported as providers.
+
 ## Module Structure
 ```
 src/modules/ModuleName/
-├── application/
-│   ├── services/ModuleService.ts      # Business logic
-│   └── validation/ModuleValidation.ts # DTOs and validation
 ├── domain/
-│   └── entities/Module.ts             # Domain model
+│   ├── entities/
+│   │   └── Entity.ts                  # Domain model (aggregate root)
+│   └── valueObjects/
+│       └── ValueObject.ts             # Value objects (if any)
+├── application/
+│   ├── useCases/
+│   │   └── EntityUseCase.ts           # Use case orchestrator
+│   ├── services/
+│   │   └── EntityService.ts           # Business logic handlers
+│   └── dto/
+│       └── EntityAction.ts            # Input/Output DTOs per action
 ├── infrastructure/
 │   ├── controllers/
-│   │   ├── ModuleApiController.ts     # REST API endpoints
-│   │   └── ModuleWebController.ts     # Web page controllers
-│   ├── interfaces/StoreInterface.ts   # Data access interface
-│   └── stores/ModuleStore.ts          # Data access implementation
+│   │   ├── EntityApiController.ts     # REST API endpoints
+│   │   └── EntityWebController.ts     # Web page controllers
+│   └── stores/
+│       └── EntityStore.ts             # Data access implementation
 ├── views/
-│   ├── modulelist.html               # List view template
-│   ├── moduledetail.html             # Detail view template
-│   ├── modulecreate.html             # Create form template
-│   └── moduleupdate.html             # Update form template
-└── module.yaml                       # Module configuration
+│   ├── entityList.html                # List view template
+│   ├── entityDetail.html              # Detail view template
+│   ├── entityCreate.html              # Create form template
+│   └── entityEdit.html               # Edit form template
+└── modulename.yaml                    # Module configuration
 ```
 
 ## Best Practices