@appxdigital/appx-core 0.1.128 → 0.1.130

package/docs/data-access.md

@@ -46,8 +46,8 @@ The proxy can only enforce ABAC on methods that accept a `where` it can inject c
 **Consequences:**
 
 - `update()` / `delete()` return `{ count }`, **not** the affected record. Re-read if you need the row.
-- These operate on **all matching rows**, not one — always pass a `where`. With ABAC conditions injected, a cross-owner `update({ where: { id } })` simply affects `{ count: 0 }` rather than erroring.
-- The TypeScript types reflect this: calling `update()` with a lone unique `where` and expecting a record back is a **compile error**, not a runtime surprise.
+- These operate on **all matching rows**, not one — always pass a `where`. With ABAC conditions injected, a cross-owner `update({ where: { id } })` affects `{ count: 0 }` rather than erroring.
+- The TypeScript types reflect this: calling `update()` with a lone unique `where` and expecting a record back is a **compile error**.
 
 Use `findMany` / `findFirst` / `findFirstOrThrow` / `updateMany` / `deleteMany` directly if you prefer the explicit names.
 
@@ -68,6 +68,22 @@ A column annotated `/// @Role(ADMIN)` is returned only to roles in the list; for
   - If the related model has **no** read rule for the role, including it throws `403`. Grant a read rule on every model you expose through an `include`.
   - If the related row exists but doesn't satisfy the rule, the **whole parent row is dropped** (`findFirst` → `null`, `findMany` → the row is omitted). The parent is **not** returned with the relation set to `null`. In short: you can't see a row whose related record you're not allowed to see. This is intentional and fails closed.
 - **To-many relations are filtered in place**: the parent is kept, and the child list is narrowed to the rows the caller may read (possibly empty).
+- **Both rules apply at every depth**, including below a to-one relation: in `include: { project: { include: { owner: true, tasks: true } } }`, `owner` gates the row like `project` does, and `tasks` is narrowed.
+- **`_count` counts readable rows only.** `select: { _count: { select: { tasks: true } } }` returns how many related tasks the caller may read. Counting a relation whose model has no read rule for the role throws `403`.
+
+### Filtering and ordering by a relation
+
+A client filter or sort that reaches into a related model only takes into account the related rows the caller can read:
+
+```ts
+// Projects with a task assigned to alice — evaluated over the tasks the caller can read.
+prisma.model.project.findMany({ where: { tasks: { some: { assignee: { email: 'alice@x.io' } } } } });
+```
+
+- `some` / `none` / `is` / `isNot` match readable related rows only; `every` must hold for every readable related row. The same applies to the `where` of a nested selection and of a `_count` entry, at any depth.
+- Filtering through a relation whose model has **no** read rule for the role throws `403` (`Cannot filter by 'project.tasks' …`). Give the role a read rule, or expose the model for that request.
+- **Ordering by a related to-one field** (`orderBy: { assignee: { name: 'asc' } }`) requires that record to be readable, like including it: rows whose related record isn't readable are left out (a null relation is kept). A related model with no read rule throws `403`.
+- **Ordering by a to-many count** (`orderBy: { tasks: { _count: 'desc' } }`) requires the related model to be readable without conditions (`'ALL'` or exposed); otherwise it throws `403`.
 
 ---
 
@@ -75,8 +91,8 @@ A column annotated `/// @Role(ADMIN)` is returned only to roles in the list; for
 
 Use sparingly and deliberately; each disables part of the protection.
 
-- **Per-call options** — `prisma.<accessor>.<method>(args, { BYPASS_FILTERING, BYPASS_OMISSION })`. `BYPASS_FILTERING` skips condition injection (and create-enforcement); `BYPASS_OMISSION` skips field omission. Available on the typed accessors (`prisma.user`, `prisma.session`, `prisma.userRefreshToken`).
-- **`@ExposeModels(...)` / `@Permission(action, [models])`** — expose models for a request so they skip row/field filtering, scoped to the handler. See [permissions.md](./permissions.md).
+- **Per-call options** — `prisma.<accessor>.<method>(args, { BYPASS_FILTERING, BYPASS_OMISSION })`. `BYPASS_FILTERING` skips condition injection (and create-enforcement); `BYPASS_OMISSION` skips field omission (relations are still row-filtered). Accepted as the second argument of every proxied model method, but not declared in the method types.
+- **`@ExposeModels(...)` / `@Permission(action, [models])`** — expose models for a request so they skip row filtering, scoped to the handler. Field omission (`@Role`) still applies; combine with `BYPASS_OMISSION` to read hidden columns. See [permissions.md](./permissions.md).
 - **`prismaService.withExposedModels(models, async () => { ... })`** — service-level scoped exposure for a block of code (e.g. registration pre-checks). Model names are lowercased/case-insensitive.
 
 Framework flows that must write without a permission (registration, sessions, tokens) use `BYPASS_FILTERING`.
@@ -89,7 +105,7 @@ Framework flows that must write without a permission (registration, sessions, to
 
 - Own-scalar conditions are checked against `data`; `belongsTo` relation conditions are checked by looking up the referenced parent.
 - A model/role with **no** `create` permission is **default-denied** (`403`).
-- It **fails closed**: unsupported condition shapes for create (list-relation `some`/`every`/`none`, exotic operators) throw rather than silently allow. For those, use `setUserIdField` to set an owner id server-side and validate inputs in DTOs.
+- It **fails closed**: unsupported condition shapes for create (list-relation `some`/`every`/`none`, exotic operators) throw rather than silently allow. For those, use `set` on the rule to write an owner id server-side and validate inputs in DTOs.
 - In development only, a warning fires if a just-created row wouldn't satisfy the model's *read* rule (i.e. the creator couldn't read it back).
 
 ---

package/docs/dtos.md

@@ -95,7 +95,7 @@ model Task {
 
 There is **no per-role field strip** — a field is either writable through the generated DTO or it isn't. If one role may write a field and another may not (e.g. only `ADMIN` sets `role`), the field is a **privileged** one: mark it `/// @NoWrite` so generic CRUD never accepts it from anyone, and set it out-of-band — a dedicated admin endpoint/service (with its own guard), AdminJS, or a direct data-access call. Trying to express "writable for role A, not role B" through one shared CRUD DTO isn't possible; model it as a separate endpoint instead.
 
-> **Migrating off `restrictedFields`.** Earlier versions had a `restrictedFields: ['x']` option on a permission action that stripped keys from the body per role. It has been **removed**. Replace it: for a field no client should write, use `/// @NoWrite` (or `/// @Role(none)`); for one endpoint, use `OmitType`; for a value the server owns (like an owner id), use `setUserIdField`; for a genuinely per-role write difference, use a dedicated endpoint as above.
+> **Migrating off `restrictedFields`.** Earlier versions had a `restrictedFields: ['x']` option on a permission action that stripped keys from the body per role. It has been **removed**. Replace it: for a field no client should write, use `/// @NoWrite` (or `/// @Role(none)`); for one endpoint, use `OmitType`; for a value the server owns (like an owner id), use `set` on the permission rule; for a genuinely per-role write difference, use a dedicated endpoint as above.
 
 ---
 
@@ -159,7 +159,7 @@ Consequence for CRUD requests:
 Note the two layers behave differently on purpose:
 
 - **The proxy enforcement is fully recursive** — it authorizes nested `create`/`connect` at *any* depth (each level checked against that model's `create` / `connect` rule). So deep nesting is safe wherever it can reach the proxy.
-- **The generated DTOs cap the HTTP surface at one level.** Deep nesting simply isn't expressible through generic CRUD.
+- **The generated DTOs cap the HTTP surface at one level.** Deep nesting isn't expressible through generic CRUD.
 
 **To do multi-level nested writes, use an explicit controller/service method** that calls `prismaService.model.<x>.create(...)` with the deep payload — the proxy still enforces the `create`/`connect` allowlist recursively there. Do not try to widen the generated DTOs to accept deeper nesting.
 

package/docs/generate.md

@@ -1,6 +1,6 @@
 # Code generation — `generate` and `generate models`
 
-AppX Core generates code from your Prisma schema through **two commands with different responsibilities**. The split exists so that keeping generated types in sync (safe to automate) is separate from scaffolding CRUD modules (which writes code you own and edits `app.module.ts`).
+AppX Core generates code from your Prisma schema through **two commands with different responsibilities**. The split exists so that keeping generated types in sync (automatable) is separate from scaffolding CRUD modules (which writes code you own and edits `app.module.ts`).
 
 | Command | What it does | Writes | Safe in CI? |
 |---|---|---|---|
@@ -13,7 +13,7 @@ AppX Core generates code from your Prisma schema through **two commands with dif
 appx-core generate
 ```
 
-Runs `prisma generate` (which emits both the Prisma client and the prisma-nestjs-graphql artifacts) and regenerates the DTO base classes under `src/generated/dto/**`. It **never** writes `src/modules/**` and **never** edits `src/app.module.ts`, so it is safe to run in CI, a `postinstall`, or a predeploy step, and safe to re-run any number of times.
+Runs `prisma generate` (which emits both the Prisma client and the prisma-nestjs-graphql artifacts) and regenerates the DTO base classes under `src/generated/dto/**`. It **never** writes `src/modules/**` and **never** edits `src/app.module.ts`, so it can run in CI, a `postinstall`, or a predeploy step, and is idempotent.
 
 Run it **every time you change the Prisma schema** — it refreshes the client, GraphQL types, and DTO bases in one step (no separate `prisma generate` needed). Because everything it writes lives under the gitignored `src/generated/`, it never produces a diff in your committed code.
 

package/docs/graphql.md

@@ -224,10 +224,9 @@ Read from `@Parent()`, not the raw Prisma client — re-querying bypasses ABAC.
 
 ---
 
-## Not available yet
+## Aggregations
 
-- **Mutations** (create/update/delete) — use REST.
-- **Full `aggregate`** (sum/avg/min/max/groupBy) — only `count` is exposed today.
+Full `aggregate` (sum/avg/min/max/groupBy) is not available yet — `count` and nested `_count` are exposed today.
 
 ---
 

package/docs/limitations.md

@@ -13,12 +13,11 @@ Read this before using any method or surface not explicitly covered in [permissi
 - Need a count? Use `count(...)` — it **is** supported and falls back to your `findMany` rule.
 - Need a genuine aggregate behind trusted access? Compute it inside a `withExposedModels(...)` block (or a bypass) with your own authorization, and never expose it to untrusted roles until aggregate ABAC lands.
 
-### GraphQL — writes and `aggregate`
+### GraphQL — `aggregate`
 
-GraphQL currently supports **read queries only** (`findAll<Model>s` / `findFirst<Model>` / `findOne<Model>`), with ABAC applied. See **[graphql.md](./graphql.md)** for how to use it, including nested queries.
+GraphQL is a read-only API — namespaced `find` / `get` / `count` per model, with ABAC applied. See **[graphql.md](./graphql.md)** for how to use it, including nested queries.
 
-- **Mutations (create / update / delete) are not available yet** — use the REST CRUD endpoints for writes.
-- **`aggregate` is not ready** — same caveat as REST above.
+- **`aggregate` is not ready** — same caveat as REST above; `count` and nested `_count` are available.
 
 Let the generated resolvers serve the data (they go through `PrismaService`); a custom resolver that reaches the raw Prisma client would not get ABAC.
 
@@ -32,11 +31,11 @@ Let the generated resolvers serve the data (they go through `PrismaService`); a
 
 ### Including an unreadable to-one relation drops the parent row
 
-`include`/`select` of a `belongsTo` relation whose target the caller can't read removes the **whole parent row** (returns `null` / omits it), rather than nulling just the relation. To-many relations filter in place and keep the parent. Fails closed; intentional. See [data-access.md](./data-access.md#relations-in-conditions-and-includes).
+`include`/`select` of a `belongsTo` relation whose target the caller can't read removes the **whole parent row** (returns `null` / omits it), rather than nulling just the relation — at any depth, so an unreadable `project.owner` drops the root row. Ordering by a related to-one field has the same effect. To-many relations filter in place and keep the parent. Fails closed; intentional. See [data-access.md](./data-access.md#relations-in-conditions-and-includes).
 
-### `_count` pseudo-field filtering is not implemented
+### Ordering by a to-many count needs an unconditional read rule
 
-You can `select: { _count: ... }`, but ABAC conditions are **not** applied inside a `_count` sub-selection. Don't rely on `_count` to reflect only rows the caller may see.
+`orderBy: { tasks: { _count: 'desc' } }` is allowed only when the role reads the related model with `'ALL'` (or it is exposed); with a conditional rule it throws `403`, since the count can't be limited to readable rows. Select `_count` (which is scoped) and sort in code, or expose the model for that request.
 
 ### Nested writes over HTTP CRUD are one level deep
 
@@ -47,10 +46,10 @@ Generated CRUD accepts nested `create`/`connect` **one level deep only** — a `
 ## Sharp edges to know about
 
 - **No per-role field strip.** A field is either writable through the generated DTO or not (`/// @NoWrite` / `OmitType`). There is no way to accept a field for one role and reject it for another on the same CRUD endpoint — model a privileged column as `/// @NoWrite` + a dedicated endpoint. (The old `restrictedFields` option was removed — see [dtos.md](./dtos.md#per-role-differences).)
-- **Per-call bypass options are only on three accessors.** `{ BYPASS_FILTERING, BYPASS_OMISSION }` are available on `prismaService.user` / `.session` / `.userRefreshToken`. For an unfiltered read of another model, use `withExposedModels([...])` or `@ExposeModels(...)`, not a per-call option on `prisma.model.<x>`.
+- **Per-call bypass options are untyped.** `{ BYPASS_FILTERING, BYPASS_OMISSION }` work as the second argument of every proxied model method, but the method types don't declare it. For an unfiltered read of a model, prefer `withExposedModels([...])` or `@ExposeModels(...)`.
 - **Role strings are not type-checked.** `PermissionsConfig` keys are plain strings; a typo (`ADIMN`) silently yields "no permissions" → default-deny for that role. Double-check role spelling against your `Role` enum.
 - **No audit logging of denials.** A refused request returns `403` but emits no structured audit event; per-request diagnostics are opt-in via `prismaService.debugQueries(true)`.
-- **Exposed models are a full bypass.** `@ExposeModels` / `@Permission(a, [models])` / `withExposedModels` disable row *and* field filtering for the listed models within that scope. Keep the scope as narrow as possible.
+- **Exposed models are a full bypass.** `@ExposeModels` / `@Permission(a, [models])` / `withExposedModels` disable row filtering for the listed models within that scope (field omission still applies — add `BYPASS_OMISSION` to read `@Role`-hidden columns). Keep the scope as narrow as possible.
 - **`connect` defaults to one rule per target model; override per relation when needed.** By default every foreign key that points at model `T` is authorized by the single `T.connect` rule for the role. When a specific relation needs a different (stricter) rule — "a class's teacher must be a teacher" — declare a **relation-scoped** `connect` on the source model (`Source[role].relations[field].connect`); it is ANDed with `T.connect`, or stands alone if `T` has none. See [permissions.md](./permissions.md#two-places-to-declare-a-connect-rule). A relation rule can only strengthen, never loosen, the target rule.
 - **A string `User.id` needs its two foreign keys changed with it.** `User.id` may be `String` (uuid/cuid) instead of the scaffold's `Int` — the framework is id-type-agnostic and coerces accordingly (see [authentication.md](./authentication.md#using-a-string-uuid--cuid-userid)). But `Session.userId` and `UserRefreshToken.userId` must be switched to `String` in the same edit; leaving one as `Int` is a schema/relation mismatch Prisma will reject at migrate time. Change all three together.
 - **The config is validated at boot; a bad config stops the app.** A create condition that references a relation, or a required foreign key whose target lacks a `connect` rule for a role that can create, is a startup error (not a runtime one). This is deliberate — the alternative is a silent runtime `403`. The error message names exactly what to fix.

package/docs/permissions.md

@@ -42,7 +42,7 @@ Shape: `PermissionsConfig[Model][Role][action]`, where each `action` value is ei
 
 - **`'ALL'`** — unrestricted for that action, or
 - **`{ conditions: <where> }`** — an ABAC rule. `conditions` is Prisma `where`-syntax (`AND`/`OR`/`NOT`, relation filters `some`/`every`/`none`, operators `in`/`not`/`lt`/…). `$USER_ID` is substituted with the caller's id at query time.
-- Optionally with **`restrictedFields`** and/or **`setUserIdField`** (see below).
+- Optionally with **`set`** on a `create` / `update` rule — columns the server writes (see below).
 
 **Model and role keys are matched case-insensitively** against the model name and the caller's role string.
 
@@ -122,6 +122,8 @@ To keep configs compact, a missing action falls back:
 - **`findFirst` / `findUnique`-shape reads → `findMany`**.
 - **`createMany` → `create`**, **`updateMany` → `update`**, **`deleteMany` → `delete`** (a batch action inherits the singular rule).
 
+Both chains apply in the `RbacGuard` and in the proxy. A custom action (`@Permission('getTeam')`, `@Permission('findAllInvoices')`) never inherits a read rule — it needs its own entry.
+
 The `*Many` → singular fallback is **one-directional**: the singular is canonical. Declaring only `updateMany` does *not* enable `update`; declare `update` (or `create`/`delete`) and the `*Many` form is covered automatically. This holds in **both** the `RbacGuard` and the proxy.
 
 So a minimal USER config often needs just `findMany`, `create`, `update`, `delete`.
@@ -130,13 +132,19 @@ So a minimal USER config often needs just `findMany`, `create`, `update`, `delet
 
 - **`/// @Role(ADMIN)` on a schema column** — only listed roles can *read* that field. For everyone else the proxy omits it from results (it comes back `undefined`). `/// @Role(none)` hides it from all roles. Applies at every depth, including nested relation selections.
 - **`/// @NoWrite` on a schema column** — excludes the field from generated create/update DTOs (all roles). Use it for privileged columns (e.g. `role`) that should be set out-of-band, not through generic CRUD.
-- **`setUserIdField: 'ownerId'`** — the framework sets that field to the caller's id server-side on create (so a client can't forge ownership). **It does not exempt the field from the `connect` requirement**: `ownerId` is still a foreign key, and every relationship a write establishes is authorized. Declare a **relation-scoped** self-connect rather than a blanket rule on the target:
+- **`set: { ownerId: '$USER_ID' }`** on a `create` / `update` rule — values the server writes on every write that rule allows, overriding what the client sent (so a client can't forge ownership). Use it for the owner, audit columns (`updatedById`), or a value a role is forced to (`status: 'draft'`). It applies on every write path — generated CRUD, your services, nested creates. Pair the column with `/// @NoWrite` so the DTO doesn't accept it either.
+
+  Set values are authorized like any other: they must satisfy the rule's `conditions`, and **a set foreign key needs a `connect` rule** — the app refuses to boot without one. Declare a **relation-scoped** self-connect rather than a blanket rule on the target:
 
   ```ts
   Album: {
       USER: {
-          create: {setUserIdField: 'ownerId'},
-          relations: {owner: {connect: {conditions: {id: '$USER_ID'}}}},
+          create: {set: {ownerId: '$USER_ID'}},
+          updateMany: {conditions: {ownerId: '$USER_ID'}, set: {updatedById: '$USER_ID'}},
+          relations: {
+              owner: {connect: {conditions: {id: '$USER_ID'}}},
+              updatedBy: {connect: {conditions: {id: '$USER_ID'}}},
+          },
       },
   },
   ```
@@ -174,7 +182,8 @@ isEmailAvailable(@Query('email') email: string) { /* reads User unfiltered */ }
 ```
 
 - Sets **no action**, so `RbacGuard` demands no permission (a public / `GUEST` route works with no `GUEST` rule for the model).
-- The listed models **skip row and field filtering for that request only** (scoped via async context — it does not make the model globally readable).
+- On writes, an exposed model skips its own `create` rule, but a foreign key it sets is still authorized by the **target's** `connect` rule unless the target is exposed too.
+- The listed models **skip row filtering for that request only** — `@Role` field omission still applies (scoped via async context — it does not make the model globally readable).
 - Case-insensitive: `@ExposeModels('User')` and `@ExposeModels('user')` are equivalent.
 - Combine with `@Permission(...)` if you also want an action check — exposed models from both decorators are merged.
 - This is a deliberate **bypass**. Use it narrowly (e.g. registration pre-checks); prefer real ABAC rules where feasible.

package/docs/storage.md

@@ -0,0 +1,89 @@
+# File Uploads & Object Storage
+
+Accept file uploads over HTTP and store them in Amazon S3, Google Cloud Storage, or the local filesystem. One setup command wires the module; each upload endpoint declares its own size limit, MIME allowlist, and role access.
+
+---
+
+## Setup
+
+Run inside your project:
+
+```bash
+appx-core setup:fileupload
+```
+
+The wizard asks for the storage provider (`aws`, `gcp`, or `local`) and the first endpoint (path, max size in MB, file category and MIME types, single or multiple files, allowed roles). It then:
+
+- appends the provider's credentials to `.env`,
+- writes `src/config/file-upload.config.ts`,
+- registers the config in `app.module.ts` — `AppxCoreModule.forRoot(PermissionsConfig, fileUploadConfig)`.
+
+### Provider environment variables
+
+| Provider | Variables |
+|---|---|
+| `aws` | `AWS_BUCKET_NAME`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` — the key pair is optional; without it the AWS SDK's default credential chain applies |
+| `gcp` | `GCP_BUCKET_NAME`, `GCP_PROJECT_ID`, `GCP_KEY_FILE_PATH` (service-account key file) |
+| `local` | none — files are written to `./uploads/` in the project |
+
+---
+
+## Endpoints
+
+Each entry in `fileUploadConfig.endpoints` is an upload route. `POST` a `multipart/form-data` request with the file(s) in the `file` field:
+
+```bash
+curl -X POST https://api.example.com/upload/avatar -F "file=@avatar.png"
+```
+
+```ts
+import {FileUploadModuleOptions} from '@appxdigital/appx-core';
+
+export const fileUploadConfig: FileUploadModuleOptions = {
+    cloudProvider: 'aws',
+    endpoints: [
+        {
+            endpoint: '/upload/avatar',
+            aliases: [],
+            maxSize: 5 * 1024 * 1024, // bytes
+            allowedTypes: ['image/jpeg', 'image/png'],
+            multiple: false,
+            roles: ['USER', 'ADMIN'], // or ['ALL'] for unrestricted
+        },
+    ],
+};
+```
+
+Per request, the module enforces:
+
+- **Role** — the caller's role must be in `roles` (`403` otherwise, including unauthenticated callers). `['ALL']` skips the check.
+- **Size** — files above `maxSize` (bytes) are rejected.
+- **Type** — a MIME type outside `allowedTypes` returns `400`. `image/jpg` is treated as `image/jpeg`.
+- **Count** — `multiple: false` accepts one file; `true` accepts several under the same `file` field.
+
+To add another endpoint, add an entry to the `endpoints` array.
+
+### Response
+
+`{ "message": "File uploaded successfully", "data": … }`, where `data` holds the storage result per file:
+
+- `aws` — `{ key, location, … }`. The object key is the original filename, so uploading the same name overwrites the object; `location` is the bucket URL.
+- `gcp` — `{ fileUrl }`. Stored under the original filename (same overwrite behaviour).
+- `local` — `{ filePath, originalName, size, mimeType }`. Names are timestamp-prefixed, so repeated uploads never overwrite.
+
+---
+
+## Uploading from your own code
+
+Inject `FileUploadService` to store a file from a custom endpoint or business logic — it delegates to the configured provider:
+
+```ts
+import {FileUploadService} from '@appxdigital/appx-core';
+
+constructor(private fileUpload: FileUploadService) {}
+
+async importReport(file: Express.Multer.File) {
+    const stored = await this.fileUpload.uploadFile(file);
+    // stored: the provider result (see Response above)
+}
+```

package/docs/testing.md

@@ -0,0 +1,74 @@
+# Testing
+
+Every project created with `appx-core create` ships a ready-to-run test suite: `npm test` provisions a throwaway database container, boots the real `AppModule` with the production middleware stack, and drives it over HTTP. The database in `.env` is never touched — the only requirement is a running Docker.
+
+```bash
+npm test            # one-shot run
+npm run test:watch  # watch mode
+```
+
+What happens on each run: vitest's global setup starts a disposable MySQL or PostgreSQL container (matching your `DB_PROVIDER`), pushes the Prisma schema into it, and hands its URL to the specs. Every spec file boots the app against that database; the container is destroyed when the run ends.
+
+---
+
+## What ships with a new project
+
+| File | Covers |
+|---|---|
+| `test/app.spec.ts` | the app boots and answers on `/` |
+| `test/auth.spec.ts` | register (incl. unknown-field rejection), session login → `/auth/me`, JWT login → `/auth/refresh` — asserted at the database level |
+| `test/isolation.spec.ts` | **route sweep**: every route the app registers is probed as a guest; anything not in `PUBLIC_ROUTES` must deny. A new endpoint with no access rule turns this red the day it lands. |
+| `test/helpers/harness.ts` | the toolkit the specs are built on (below) |
+| `test/setup.ts`, `test/global-setup.ts`, `vitest.config.ts` | container lifecycle + runner config |
+
+The harness exports:
+
+- `startApp()` / `stopApp()` — boots `AppModule` once per spec file with the same session/passport/`setupCoreSecurity` stack as `src/main.ts`.
+- `api(actor?)` — a supertest agent; pass an actor to send its JWT bearer token, none for a guest.
+- `sessionAgent()` — a cookie-keeping agent for session flows (`POST /auth/login` → `/auth/me`).
+- `registerActor(email?, password?)` — mints a user over real HTTP (register + JWT login) and returns `{ id, email, password, token }`.
+- `prisma` — a **raw** Prisma client (no ABAC): create fixture rows and assert results with it.
+- `truncateAll()` — deletes every row, children before parents; extend it as your schema grows.
+
+---
+
+## Writing a spec
+
+The pattern, shown for a generated module (after `appx-core generate models`):
+
+```ts
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { api, prisma, registerActor, startApp, stopApp, truncateAll } from './helpers/harness';
+
+describe('projects', () => {
+  beforeAll(async () => {
+    await startApp();
+  });
+  afterAll(stopApp);
+  beforeEach(truncateAll);
+
+  it("a user cannot read another user's project", async () => {
+    const alice = await registerActor();
+    const bob = await registerActor();
+    const row = await prisma.project.create({ data: { title: 'p', ownerId: bob.id } });
+
+    const res = await api(alice).get(`/projects/${row.id}`);
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    // The database is the authority: the row is untouched.
+    expect(await prisma.project.count()).toBe(1);
+  });
+});
+```
+
+Conventions the shipped specs follow — keep them:
+
+- **Actors go through HTTP** (`registerActor`), **fixture rows go through raw `prisma`** — a broken permission rule can't quietly produce an empty fixture and fake a pass.
+- **Assert on the database**, not only the response body. ABAC-denied `updateMany`/`deleteMany` match zero rows and still return `200` — the row count is the authority on whether isolation held.
+- **Extend `truncateAll`** when you add models (children before parents).
+- **A new public route is a deliberate act**: add it to `PUBLIC_ROUTES` in `test/isolation.spec.ts`, one line, reviewed.
+
+---
+
+## Existing projects
+
+Projects created before the test scaffold existed can adopt it by copying the files from a fresh scaffold (or from this package's `cli/scaffold/` directory): `vitest.config.ts`, `test/`, the `test`/`test:watch` scripts, and the devDependencies listed in the [CHANGELOG](../CHANGELOG.md) migration note.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.128",
+    "version": "0.1.130",
     "description": "Appx Core is a library that provides a set of tools to help you build your application faster.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -30,6 +30,7 @@
         "url": "https://github.com/appxdigital/appx-core/issues"
     },
     "dependencies": {
+        "@adminjs/nestjs": "~7.0.0",
         "express": "^5.1.0"
     },
     "devDependencies": {
@@ -56,7 +57,6 @@
     "peerDependencies": {
         "@adminjs/express": "~6.1.1",
         "@adminjs/import-export": "~3.0.0",
-        "@adminjs/nestjs": "~7.0.0",
         "@adminjs/passwords": "~4.0.0",
         "@adminjs/prisma": "~5.0.4",
         "@apollo/server": "^4.11.3",