cabloy 5.1.50 → 5.1.52

package/cabloy-docs/backend/unit-testing.md

@@ -0,0 +1,209 @@
+# Unit Testing
+
+This guide explains the most important Vona testing workflows in the Cabloy monorepo.
+
+## Why testing is emphasized
+
+Test-driven development remains a strong default in the Cabloy monorepo.
+
+Vona’s testing story is valuable because it is closely integrated with:
+
+- app initialization
+- Redis cleanup
+- database recreation
+- migration execution
+- request-context simulation
+- action-level API verification
+
+That means tests can exercise framework behavior in a realistic way.
+
+## Unit testing in the backend contract loop
+
+A useful backend-contract-loop testing mental model is:
+
+- migration prepares the structural state
+- controllers expose the route/action surface
+- services and models execute the business and persistence logic
+- tests verify the resulting contract through scoped access and action execution
+
+This is why Vona testing should not be reduced to isolated helper-unit testing only.
+
+## Create a test file
+
+Example:
+
+```bash
+npm run vona :create:test student -- --module=demo-student
+```
+
+## Execute tests
+
+From the root repository:
+
+```bash
+npm run test
+```
+
+A typical Vona test flow includes:
+
+1. create a global `app` object
+2. clean Redis data
+3. recreate the database
+4. execute migration code
+5. run the test files
+
+This is one of the most important distinctions from ordinary app flow: test execution rebuilds and verifies the framework lifecycle, not only the target function.
+
+## Reset database without running tests
+
+Representative command:
+
+```bash
+cd vona && npm run db:reset
+```
+
+This is useful when you want to reapply migration logic without running the entire test suite.
+
+## Coverage
+
+Representative command:
+
+```bash
+cd vona && npm run cov
+```
+
+## Mock request context
+
+One of the most important Vona testing patterns is simulating a request context.
+
+Representative shape:
+
+```typescript
+await app.bean.executor.mockCtx(async () => {
+  // test logic here
+});
+```
+
+Locale-sensitive variants and additional request-context helpers are also available.
+
+## Working with module scope in tests
+
+Representative pattern:
+
+```typescript
+const scopeStudent = app.scope('demo-student');
+```
+
+This lets tests exercise:
+
+- services
+- models
+- entities
+- controller actions
+
+through the same scoped abstractions used in application code.
+
+## Testing controllers through actions
+
+Representative pattern:
+
+```typescript
+await app.bean.executor.performAction('get', '/demo/student');
+```
+
+This is especially useful because it exercises the controller path more realistically than only unit-testing isolated helper functions.
+
+A practical rule is:
+
+- use direct service/model assertions when the test target is truly internal behavior
+- use `performAction(...)` when the goal is to verify the backend API contract as a controller-facing workflow
+
+A representative contract-verification pattern is:
+
+```typescript
+await app.bean.executor.performAction('patch', '/test/rest/product/:id', {
+  params: { id: productId },
+  body: dataUpdate,
+});
+```
+
+This is a good default because the same test can exercise params, body, route wiring, validation, and response behavior together.
+
+## Authentication simulation
+
+Tests can also simulate signin and signout behavior.
+
+Representative patterns include:
+
+- `signinMock()`
+- `signinMock('admin')`
+- `signout()`
+
+This is important for testing permission-sensitive flows.
+
+A practical CRUD-style pattern is:
+
+- sign in
+- call create via `performAction(..., { body })`
+- call list/query and verify inclusion
+- call update via params + body
+- call find-one and verify new state
+- call delete and verify final state
+- sign out
+
+This keeps auth-sensitive CRUD verification close to the real controller contract path.
+
+## Assertion and error-handling helpers
+
+Two practical testing helpers are:
+
+- Node’s built-in `assert`
+- `catchError` from `@cabloy/utils`
+
+These help keep tests explicit while still fitting the framework’s async execution style.
+
+## End-to-end CRUD test story
+
+A realistic CRUD test usually verifies a whole backend thread, not only one method call.
+
+A practical sequence is:
+
+1. create request data
+2. sign in if auth is required
+3. call create action
+4. call list/query action and verify inclusion
+5. call update action
+6. call find-one action and verify the new state
+7. call delete action
+8. verify the final deleted/not-found state
+9. sign out
+
+This is the most framework-native verification path because it tests route, validation, DTO, service, model, and migration assumptions together.
+
+## Relationship to migration and CRUD generation
+
+Read this guide together with:
+
+- [CRUD Workflow](/backend/crud-workflow)
+- [Migration and Changes](/backend/migration-and-changes)
+- [Controller Guide](/backend/controller-guide)
+
+A practical split is:
+
+- CRUD generation creates the initial backend thread
+- migration keeps that thread structurally valid over time
+- tests verify the resulting contract through realistic execution
+
+## Implementation checks for backend testing changes
+
+When adding or changing backend behavior, do not stop at code generation.
+
+It should also ask:
+
+1. should a module test be created or updated?
+2. does the change need request-context simulation?
+3. does it affect migration/setup behavior that should be covered through the test flow?
+4. should controller behavior be verified through `performAction` rather than only direct method calls?
+5. does the change affect the end-to-end CRUD thread rather than only one isolated function?
+
+That leads to much stronger and more framework-native verification.

package/cabloy-docs/backend/upload-guide.md

@@ -0,0 +1,160 @@
+# Upload Guide
+
+## Why upload matters in Vona
+
+Vona treats file upload as a request-path capability that should integrate cleanly with controller decorators, validation-style metadata, and automatic temporary-file handling.
+
+That matters because upload flows often combine files, structured form fields, OpenAPI-facing request contracts, and cleanup responsibilities.
+
+## Core upload model
+
+Vona implements upload capabilities on top of Busboy.
+
+The most important framework-facing pieces are:
+
+- the upload interceptor enabled by `@Core.fileUpload()`
+- file and field parameter decorators under `@Arg.*`
+- automatic temporary-file lifecycle handling
+
+## Upload interceptor
+
+File upload is enabled through the upload interceptor.
+
+Representative pattern:
+
+```typescript
+@Web.post('file')
+@Core.fileUpload()
+@Api.contentType('application/json')
+async uploadFile(@Arg.file('file1', v.title('Upload Single File')) file1: IUploadFile) {
+  return file1.file;
+}
+```
+
+The upload interceptor:
+
+- parses incoming upload data
+- stores uploaded files in temporary files
+- exposes those files to controller parameters
+- automatically cleans up the temporary files after the business logic completes
+
+## Single-file upload
+
+Single-file upload usually uses `@Arg.file(...)`.
+
+```typescript
+@Arg.file('file1', v.title('Upload Single File')) file1: IUploadFile
+```
+
+`IUploadFile` includes fields such as:
+
+- `name`
+- `file`
+- `info.filename`
+- `info.encoding`
+- `info.mimeType`
+
+This gives controller code both the temporary file path and the original upload metadata.
+
+## Multiple-file upload
+
+Multiple-file upload uses `@Arg.files(...)`.
+
+```typescript
+@Arg.files('files', v.title('Upload Multiple Files')) files: IUploadFile[]
+```
+
+This is the preferred pattern when one field name represents an array of uploaded files.
+
+## Form fields alongside files
+
+Upload flows often include normal form fields in addition to file data.
+
+Vona supports both:
+
+- `@Arg.field(...)`
+- `@Arg.fields(...)`
+
+### `@Arg.field(...)`
+
+Use this when the frontend sends one field value directly, or a serialized array-like value under a single form entry.
+
+Representative frontend shape:
+
+```typescript
+const formData = new FormData();
+formData.append('name', 'vona');
+formData.append('tags', ['node', 'typescript']);
+```
+
+### `@Arg.fields(...)`
+
+Use this when the frontend appends the same field key multiple times, for example multiple `tags` entries in `FormData`.
+
+Representative frontend shape:
+
+```typescript
+const formData = new FormData();
+formData.append('name', 'vona');
+formData.append('tags', 'node');
+formData.append('tags', 'typescript');
+```
+
+This distinction matters because frontend upload construction style affects how the backend should read field values.
+
+## JSON content type note
+
+When an upload endpoint returns JSON data, it is useful to set:
+
+```typescript
+@Api.contentType('application/json')
+```
+
+That helps keep the API contract explicit even when the client upload request is multipart-based.
+
+## Relationship to controller design
+
+Upload is best understood as a controller-facing request-path capability.
+
+Read this guide together with:
+
+- [Controller Guide](/backend/controller-guide)
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+
+These guides explain the broader request-decorator, validation, and contract-generation model that upload participates in.
+
+A useful boundary is:
+
+- the upload interceptor owns multipart parsing and temporary-file lifecycle
+- controller decorators own request-shape declaration
+- business logic should focus on what to do with the uploaded content once those two layers have normalized the input
+
+## Typical backend workflow
+
+A practical upload flow often looks like this:
+
+1. enable the upload interceptor with `@Core.fileUpload()`
+2. declare file and form-field parameters with `@Arg.file`, `@Arg.files`, `@Arg.field`, or `@Arg.fields`
+3. apply titles or validation-oriented helpers where useful
+4. process the temporary files inside the controller or delegated service logic
+5. return the desired result while letting the interceptor handle cleanup
+
+In the current repo, test upload controllers also demonstrate a broader shape with mixed usage such as:
+
+- raw `@Arg.fields()` access to all parsed fields
+- named `@Arg.field(...)` extraction
+- named `@Arg.file(...)` and `@Arg.files(...)` extraction in the same endpoint
+
+That is a good reminder that upload endpoints can stay declarative even when multipart payloads become fairly rich.
+
+## Implementation checks for backend upload changes
+
+When editing backend upload behavior, ask:
+
+1. is the request-path correctly using `@Core.fileUpload()`?
+2. should this parameter use `@Arg.file`, `@Arg.files`, `@Arg.field`, or `@Arg.fields`?
+3. does the frontend upload construction style match the backend field decorators?
+4. should the response contract explicitly declare JSON content type or related metadata?
+
+That helps AI keep upload flows aligned with Vona’s real request and cleanup model.

package/cabloy-docs/backend/user-access-guide.md

@@ -0,0 +1,157 @@
+# User Access Guide
+
+## Why user access matters in Vona
+
+Vona separates general user, role, and passport capabilities from business-specific customization.
+
+That matters because the framework needs to stay reusable while still supporting project-specific identity, role, and activation workflows.
+
+## Core access model
+
+The user-access model is centered on three framework-level concepts:
+
+- **user**
+- **role**
+- **passport**
+
+## `IUser`
+
+The `a-user` module provides `IUser` as the core interface for the current user model.
+
+Representative fields include:
+
+- `id`
+- `name`
+- `avatar`
+- `email`
+- `mobile`
+- `activated`
+- `locale`
+- `anonymous`
+
+The `locale` field matters because current-locale resolution can fall back to the user locale in request context handling; see [I18n Guide](/backend/i18n-guide).
+
+## `bean.user`
+
+Vona exposes `bean.user` as the general business-facing API for user operations.
+
+Behind that unified API, the `home-user` module customizes behavior through `ServiceUserAdapter`, which is why business code can keep calling `bean.user` while the project still retains control over how users are created, looked up, updated, or removed.
+
+Representative capabilities include:
+
+- register a user
+- activate a user
+- create an anonymous user
+- find a user by name or id
+- update or remove a user
+- register a user from OAuth profile data
+
+This gives business logic a stable entrypoint even when deeper adapter behavior is customized elsewhere.
+
+## `IRole` and `bean.role`
+
+The `a-user` module also provides `IRole` and a global bean `bean.role`.
+
+As with users, the stable business-facing surface is backed by a project-customizable adapter layer, here via `ServiceRoleAdapter` in `home-user`.
+
+Representative capabilities include:
+
+- find a role by name or id
+- find all roles for a user
+
+This makes role lookup part of the same framework-level access model as user lookup.
+
+## `IPassport` and `bean.passport`
+
+When a request successfully authenticates, Vona creates a passport containing access-related context such as:
+
+- current user
+- current auth record
+- current roles
+
+`bean.passport` provides a unified calling surface for passport behavior.
+
+In the default `home-user` implementation, `ServicePassportAdapter` is what decides how passport state is serialized into JWT payloads and deserialized back into user/auth/role context on later requests.
+
+Representative capabilities include:
+
+- get the current passport
+- get current user/auth/roles
+- check authentication or activation state
+- sign in or sign out
+- mock sign in for tests
+- sign in as anonymous
+- refresh JWT tokens
+- create temporary auth tokens
+
+## Current user and current roles
+
+Backend code can retrieve the current user through several framework-native paths.
+
+### Controller parameter decorator
+
+```typescript
+@Arg.user() user: IUser
+```
+
+### Passport bean
+
+```typescript
+const user = this.bean.passport.currentUser;
+const roles = this.bean.passport.currentRoles;
+```
+
+### Request context
+
+```typescript
+const user = this.ctx.user;
+const passport = this.ctx.passport;
+```
+
+## Anonymous user behavior
+
+When anonymous access is allowed, Vona can create an anonymous user object automatically.
+
+That means request-path access rules and user identity handling stay consistent even before full authentication.
+
+## Registration and activation
+
+Vona’s user system is connected to event-driven customization points.
+
+Representative flows include:
+
+- registration
+- activation
+- assigning default roles
+- sending email confirmation or similar follow-up logic
+
+Those follow-up email behaviors often connect directly to queue-backed mail delivery; see [Mail Guide](/backend/mail-guide).
+
+The framework-level user APIs stay stable while project-specific modules can customize what happens before or after those core steps through event-driven hooks and related extension logic.
+
+The legacy user docs showed this especially clearly:
+
+- registration can trigger follow-up mail-confirm flows
+- activation can assign default roles such as `admin`
+- `autoActivate` can suppress the extra activation step when the business flow allows it
+
+## Relationship to auth and controller AOP
+
+This guide focuses on the user/role/passport model itself.
+
+Read it together with:
+
+- [Auth Guide](/backend/auth-guide) for provider-driven authentication
+- [Controller AOP Guide](/backend/controller-aop-guide) for `@Passport.*` and guard-based request-path behavior
+- [Event Guide](/backend/event-guide) for event-driven customization around registration, activation, and related lifecycle hooks
+
+## Implementation checks for user-access changes
+
+When editing user or access logic, ask:
+
+1. is the right layer `bean.user`, `bean.role`, `bean.passport`, or an auth provider?
+2. does the flow depend on current user, current roles, or current passport state?
+3. should anonymous, activated, or admin behavior be handled through existing framework conventions?
+4. does the change belong in business logic, event-driven customization, or request-path guard configuration?
+
+That helps AI keep access logic aligned with Vona’s real identity architecture.

package/cabloy-docs/backend/validation-guide.md

@@ -0,0 +1,80 @@
+# Validation Guide
+
+This guide explains how validation works in Vona within the Cabloy monorepo.
+
+## Why validation matters in Vona
+
+Vona builds validation around Zod and integrates it directly into controller argument handling, DTOs, entities, and OpenAPI generation.
+
+That means validation is not an isolated input-checking step. It is part of the contract layer shared across runtime behavior, types, and API documentation.
+
+## Automatic schema inference
+
+One very important convenience is that if a parameter type is a basic type, DTO, or entity, Vona can automatically infer the corresponding Zod schema.
+
+Representative cases:
+
+- `number` → `z.number()`
+- DTO → `z.object({...})`
+- Entity → `z.object({...})`
+
+This matters because Vona tries to keep the contract surface concise while still producing strong runtime validation.
+
+In controller AOP terms, this usually means built-in argument handling is enough for many request parameters without creating a custom pipe or argument pipe first.
+
+## Explicit schema rules
+
+You can also pass explicit schema rules when automatic inference is not enough.
+
+Representative pattern:
+
+```typescript
+findOne(@Arg.query('id', z.number().min(6)) id: number) {}
+```
+
+## Extending the inferred schema
+
+Inferred schemas can also be extended through helper tools like:
+
+- `v.optional`
+- `v.default`
+- `v.array`
+- `v.lazy`
+
+That is important because many real validation cases need augmentation rather than total replacement.
+
+## `@Arg.filter`
+
+The validation layer also supports more advanced query-style inputs through `@Arg.filter`, which ties into DTO/query helper structures.
+
+This is a good example of validation being connected to higher-level query semantics, not only primitive field checks.
+
+## Tool groups
+
+These helper tools fall into groups such as:
+
+- basic tools
+- string tools
+- OpenAPI tools
+- serializer tools
+- Zod tools
+
+For response-side shaping with those serializer helpers, see [Serialization Guide](/backend/serialization-guide).
+
+- query filter tools
+- special tools like `v.tableIdentity`
+
+This matters because the right answer is often “use the existing helper vocabulary” instead of hand-writing a one-off schema pattern.
+
+## Implementation checks for request-validation changes
+
+When changing request contracts, ask:
+
+1. can Vona infer the schema automatically?
+2. does the contract need explicit extension through the `v` helpers?
+3. does the same validation surface also feed OpenAPI and DTO behavior?
+4. is the validation logic better expressed at the controller, DTO, or entity layer?
+
+That produces more consistent backend contracts.
+
+For the broader request-path model around pipes, guards, middleware, interceptors, and filters, see [Controller AOP Guide](/backend/controller-aop-guide). Captcha verification flows commonly intersect with this request-path layer through a local interceptor; see [Captcha Guide](/backend/captcha-guide).

package/cabloy-docs/backend/worker-guide.md

@@ -0,0 +1,59 @@
+# Worker Guide
+
+This guide explains how workers fit into Vona within the Cabloy monorepo.
+
+## Why workers matter
+
+Vona uses a distributed worker-process architecture, which means the backend runtime is naturally multi-process rather than assuming one long-lived server instance only.
+
+This matters because operational behavior, reload behavior, queue execution, broadcast, and auth-sensitive runtime logic can all depend on worker semantics.
+
+## `bean.worker`
+
+A global worker-management bean provides capabilities such as:
+
+- get current worker id
+- exit current worker
+- exit all workers
+- reload current worker
+- reload all workers
+- manage alive state
+
+This makes worker control part of the application’s operational surface.
+
+## `SERVER_WORKERS`
+
+Worker count can be controlled through env or command-line setup.
+
+Representative idea:
+
+- development often uses multiple workers to expose distributed-environment issues earlier
+- single-worker modes still matter for Docker or simpler execution scenarios
+
+A practical runtime reading in the current repo is:
+
+- `SERVER_WORKERS` becomes part of backend server config
+- `npm run dev` and `cd vona && npm run dev` normally exercise multi-worker behavior
+- `dev:one`, `start:one`, and Docker-oriented single-worker flows remain important when you want simpler runtime shape or one-worker debugging
+
+## Worker control behavior
+
+At a high level:
+
+- `reload()` targets the current worker
+- `reloadAll()` broadcasts reload intent across workers
+- `exit()` closes the current app process and exits
+- `exitAll()` broadcasts a process-exit intent across workers
+
+This matters because worker control belongs to runtime behavior, not only to deployment tooling.
+
+## Implementation checks for worker-sensitive runtime changes
+
+When touching runtime or operational backend behavior, ask:
+
+1. does this assume a single-process runtime incorrectly?
+2. does the behavior change across worker count or worker lifecycle?
+3. is this a place where reload or worker-control operations matter?
+4. should the verification path consider multi-worker behavior explicitly?
+
+That keeps backend reasoning aligned with Vona’s actual runtime architecture.

package/cabloy-docs/editions/cabloy-basic.md

@@ -0,0 +1,26 @@
+# Cabloy Basic
+
+Cabloy Basic is the public framework/reference edition you are reading right now.
+
+## Repository marker
+
+The repository root contains:
+
+- `__CABLOY_BASIC__`
+
+This marker is the quickest safe signal for docs, skills, and rules that need to distinguish Cabloy Basic from Cabloy Start.
+
+## Typical role
+
+Use Cabloy Basic as the public reference edition for:
+
+- shared architecture explanations
+- root scripts and monorepo entrypoints
+- Vona and Zova source browsing
+- public CLI-backed workflows
+- public user-facing documentation
+- projects created with `npm create cabloy`
+
+## Frontend bias
+
+In the current source and docs, Cabloy Basic examples commonly align with a shared frontend engineering layer built on Zova, Vue, Vite, and Quasar tooling, plus a Basic-specific UI layer built with DaisyUI + Tailwind CSS. That does not mean Zova is limited to that UI stack, but it does mean docs and AI outputs should not accidentally project Vuetify-specific assumptions into Cabloy Basic unless the current source explicitly requires it.