@appxdigital/appx-core 0.1.128 → 0.1.129

package/CHANGELOG.md

@@ -14,6 +14,31 @@ This project follows the `MAJOR.MINOR.PATCH` scheme in `package.json`.
 
 ---
 
+## [0.1.129] — 2026-08-17
+
+### Added
+
+- **Every new project ships a ready-to-run test suite.** `appx-core create` now scaffolds `vitest.config.ts` and `test/` (Vitest + SWC), with `npm test` / `npm run test:watch` scripts and the needed devDependencies. A run provisions a **throwaway database container** via Testcontainers (matching `DB_PROVIDER` — the database in `.env` is never touched; Docker is the only requirement), pushes the Prisma schema, and boots the real `AppModule` with the production middleware stack (session store, passport, `setupCoreSecurity`). Shipped specs: app boot, register (unknown-field rejection included), session login → `/auth/me`, JWT login → `/auth/refresh` — all asserted at the database level — plus a **route sweep** that probes every registered route as a guest and fails on anything non-public that answers `2xx`. See [docs/testing.md](./docs/testing.md).
+
+- **Every new project ships an agent guide.** `appx-core create` drops an `AGENTS.md` at the project root (plus a `CLAUDE.md` pointer) — the rules of the road for coding agents working in the project: proxy-only data access, default-deny permissions, generated-code ownership, read/write surfaces, test conventions, and the pre-production checklist (including removing the Hello-World placeholder). It points at `node_modules/@appxdigital/appx-core/docs/` as the source of truth instead of duplicating it.
+
+### Fixed
+
+- **`POST /auth/refresh` now works under a default-deny permissions config.** The refresh-token user lookup runs as a framework auth flow (like login and JWT population). Previously, a permissions config with no `GUEST` read rule on `User` — including the scaffold default — returned `403` for every refresh.
+- **AdminJS is loaded lazily.** The backoffice no longer imports `adminjs` at module load time; it resolves through the same dynamic-import path as the other AdminJS packages. Drop-in — enables importing the package under CommonJS test runners and on Node < 20.19.
+
+### Migration
+
+> Drop-in for existing projects. To adopt the test suite in a project created before this version:
+
+1. Copy `vitest.config.ts` and the `test/` directory from a freshly created project (or from this package's `cli/scaffold/`).
+2. Add the scripts: `"test": "vitest run"`, `"test:watch": "vitest"`.
+3. `npm install -D vitest unplugin-swc @swc/core supertest @types/supertest @nestjs/testing @testcontainers/mysql @testcontainers/postgresql dotenv`.
+4. Run `npm test` (requires Docker). Extend `test/helpers/harness.ts`'s `truncateAll` and `test/isolation.spec.ts`'s `PUBLIC_ROUTES` as your schema and routes grow.
+5. Optionally copy `AGENTS.md` (and the `CLAUDE.md` pointer) from `cli/scaffold/`, replacing `{{PROJECT_NAME}}` with your project's name.
+
+---
+
 ## [0.1.128] — 2026-08-04
 
 Read-only GraphQL, reworked into a **namespaced, opt-in-per-module** API.

package/README.md

@@ -86,6 +86,8 @@ AppX Core puts **security and data-access control first**, while keeping develop
   - Namespaced, **opt-in per model**: `model { find get count }`
   - **Native pagination** (`take` / `skip` / `cursor`), nested relations, and several models per request — prefer it over the CRUD list endpoint for reads/filtering, and enable it on your main queryable models
   - Same ABAC as REST (row / field / nested-record filtering; filter & sort limited to readable fields)
+- **Tests out of the box**
+  - `npm test` provisions a throwaway database container (Docker) and drives the real app over HTTP — register/login/refresh flows plus a route-sweep that denies guests everywhere non-public
 - **Developer-friendly extension points**
   - Add custom endpoints with `@Permission(...)`
   - Use services for business logic, controllers as transport layer
@@ -160,7 +162,7 @@ appx-core create --yes \
   --db-user root --db-password secret --db-name my_app_db
 ```
 
-Flags: `--name`, `--db-provider mysql|postgresql`, `--db-host`, `--db-port`, `--db-user`, `--db-password`, `--db-name`, `--show-output`. File upload isn't configured on this path — run `appx-core setup:fileupload` inside the project afterwards.
+Flags: `--name`, `--db-provider mysql|postgresql`, `--db-host`, `--db-port`, `--db-user`, `--db-password`, `--db-name`, `--show-output`. File upload isn't configured on this path — run `appx-core setup:fileupload` inside the project afterwards (see [docs/storage.md](./docs/storage.md)).
 
 ### 3) Configure Environment
 
@@ -487,7 +489,7 @@ model User {
 }
 ```
 
-Use `/// @NoWrite` to exclude a field for **all** roles. For **per-role** control (e.g. only ADMIN may set `role`), use `restrictedFields` on the permission instead of `@NoWrite`.
+A field is either CRUD-writable or it isn't — there is no per-role write control on a generated endpoint. For a privileged field (e.g. `role`), annotate it `/// @NoWrite` and set it through a dedicated endpoint. See [docs/dtos.md](./docs/dtos.md).
 
 ---
 
@@ -558,7 +560,7 @@ export const PermissionsConfig = {
 };
 ```
 
-Service (Prisma query remains straightforward; ABAC filtering is applied by the core):
+Service (ABAC filtering is applied by the core):
 
 ```ts
 async getMyProfile() {
@@ -603,22 +605,27 @@ This pattern should be used sparingly and intentionally.
 
 ## Limitations
 
-### Prisma method restrictions (permission safety)
+### Single-record methods are aliases
 
-Avoid these Prisma methods because they can bypass or complicate granular permission filtering:
+The single-record Prisma methods are aliases to their filter-compatible equivalents — in the TypeScript types and at runtime — and take that method's arguments and return its result. ABAC applies to every call.
 
-- `findUnique` → use `findFirst`
-- `delete` → use `deleteMany` with a single-item filter
-- `update` → use `updateMany` with a single-item filter
+- `findUnique()` / `findUniqueOrThrow()` run `findFirst()` / `findFirstOrThrow()`
+- `update()` runs `updateMany()` — returns `{ count }`, not the record
+- `delete()` runs `deleteMany()` — returns `{ count }`
 
-Operational guidance:
+They act on **all** matching rows, so pass a restrictive `where` when you intend a single record; a call reaching outside your permissions affects `{ count: 0 }`. Full contract in [docs/data-access.md](./docs/data-access.md#method-contract-important).
 
-- Prefer `findMany`, `findFirst`, `updateMany`, and `deleteMany`.
-- When you intend a single-record operation, use a restrictive `where` clause.
+### GraphQL
 
-### GraphQL status
+GraphQL exposes a **read-only** API — `find` / `get` / `count`, namespaced per model and **opt-in per module** (one line) — that runs through the same ABAC proxy as REST: row filtering, field omission, nested-relation filtering, and filter/sort limited to fields the role can read all apply. It supports nested selections and native pagination (`take`/`skip`/`cursor`), so it's the recommended surface for querying/filtering/paginating reads. See **[docs/graphql.md](./docs/graphql.md)**.
 
-GraphQL exposes a **read-only** API — `find` / `get` / `count`, namespaced per model and **opt-in per module** (one line) — that runs through the same ABAC proxy as REST: row filtering, field omission, nested-relation filtering, and filter/sort limited to fields the role can read all apply. It supports nested selections and native pagination (`take`/`skip`/`cursor`), so it's the recommended surface for querying/filtering/paginating reads. See **[docs/graphql.md](./docs/graphql.md)**. Not yet: mutations and full aggregates — REST CRUD + AdminJS remain the write surfaces.
+Aggregations are not yet available (on the roadmap); `count` and nested `_count` cover the common cases today.
+
+---
+
+## Testing
+
+Every new project ships a ready-to-run suite: `npm test` starts a disposable database container matching your `DB_PROVIDER`, pushes the schema, boots the real `AppModule` with the production middleware stack, and runs HTTP-level specs — auth flows asserted at the database level, and a route sweep that probes every registered route as a guest. Docker is the only requirement; the database in `.env` is never touched. See **[docs/testing.md](./docs/testing.md)** for the harness API and how to write specs for your modules.
 
 ---
 
@@ -636,15 +643,11 @@ No. Generated NestJS modules are **editable** and intended to be extended.
 
 Planned and under consideration:
 
-- Production-ready GraphQL
-- Object storage patterns (S3-friendly out-of-the-box support)
+- GraphQL aggregations
 - Forgot-password flow
 - Email templates + sending primitives
 - Push notifications primitives
 - WebSockets support
-- Stronger testing baseline (unit tests scaffolding and patterns)
-- “Agent-ready” development guidance (`agents.txt`, conventions for coding agents)
-- Optional AI-assisted project scaffolding
 
 ---
 

package/dist/backoffice/appx-core-admin.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appx-core-admin.module.d.ts","sourceRoot":"","sources":["../../src/backoffice/appx-core-admin.module.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAO7D,OAAO,EAAC,eAAe,EAAC,MAAM,kCAAkC,CAAC;AAIjE,OAAO,EAAC,qBAAqB,EAAC,MAAM,yCAAyC,CAAC;AAE9E,qBAEa,mBAAmB;IAC5B,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;CAG3G"}
+{"version":3,"file":"appx-core-admin.module.d.ts","sourceRoot":"","sources":["../../src/backoffice/appx-core-admin.module.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAM7D,OAAO,EAAC,eAAe,EAAC,MAAM,kCAAkC,CAAC;AAIjE,OAAO,EAAC,qBAAqB,EAAC,MAAM,yCAAyC,CAAC;AAE9E,qBAEa,mBAAmB;IAC5B,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;CAG3G"}

package/dist/backoffice/appx-core-admin.module.js

@@ -37,7 +37,6 @@ const common_1 = require("@nestjs/common");
 const utils_1 = require("./utils");
 const utils_2 = require("../config/utils");
 const nestjs_request_context_1 = require("nestjs-request-context");
-const adminjs_1 = require("adminjs");
 const argon2 = __importStar(require("argon2"));
 const prisma_service_1 = require("../prisma/prisma.service");
 let AppxCoreAdminModule = exports.AppxCoreAdminModule = class AppxCoreAdminModule {
@@ -54,7 +53,7 @@ function lowerCase(name) {
 }
 async function createAdminJsModule(adminConfig, permissionConfig) {
     // Due to AdminJS only allowing ESM now, we need to use dynamic imports to load the modules, this function can be found within src/backoffice/utils.ts
-    const { default: AdminJS } = await (0, utils_1.dynamicImport)('adminjs');
+    const { default: AdminJS, BaseRecord } = await (0, utils_1.dynamicImport)('adminjs');
     const { Database, Resource, convertParam } = await (0, utils_1.dynamicImport)('@adminjs/prisma');
     const { AdminModule } = await (0, utils_1.dynamicImport)('@adminjs/nestjs');
     const { default: importExportFeature } = await (0, utils_1.dynamicImport)('@adminjs/import-export');
@@ -106,7 +105,7 @@ async function createAdminJsModule(adminConfig, permissionConfig) {
                 });
                 if (!result)
                     return null;
-                return new adminjs_1.BaseRecord(this.prepareReturnValues(result), this);
+                return new BaseRecord(this.prepareReturnValues(result), this);
             }
             async update(pk, params = {}) {
                 const idProperty = this.properties().find((property) => property.isId());

package/dist/modules/auth/refresh-token.strategy.d.ts

@@ -2,15 +2,13 @@ import { Strategy } from 'passport-jwt';
 import { ConfigService } from '@nestjs/config';
 import { Request } from 'express';
 import { PrismaService } from '../../prisma/prisma.service';
-import { UserService } from '../user/user.service';
 declare const RefreshTokenStrategy_base: new (...args: [opt: import("passport-jwt").StrategyOptionsWithRequest] | [opt: import("passport-jwt").StrategyOptionsWithoutRequest]) => Strategy & {
     validate(...args: any[]): unknown;
 };
 export declare class RefreshTokenStrategy extends RefreshTokenStrategy_base {
     private readonly configService;
     private readonly prisma;
-    private readonly userService;
-    constructor(configService: ConfigService, prisma: PrismaService, userService: UserService);
+    constructor(configService: ConfigService, prisma: PrismaService);
     validate(req: Request, payload: any): Promise<any>;
 }
 export {};

package/dist/modules/auth/refresh-token.strategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refresh-token.strategy.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/refresh-token.strategy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,QAAQ,EAAC,MAAM,cAAc,CAAC;AAClD,OAAO,EAAC,aAAa,EAAC,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAC,OAAO,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAC,WAAW,EAAC,MAAM,sBAAsB,CAAC;;;;AAEjD,qBACa,oBAAqB,SAAQ,yBAAyC;IAE3E,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAFX,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,WAAW;IAcvC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG;CAmC5C"}
+{"version":3,"file":"refresh-token.strategy.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/refresh-token.strategy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,QAAQ,EAAC,MAAM,cAAc,CAAC;AAClD,OAAO,EAAC,aAAa,EAAC,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAC,OAAO,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;;;;AAE1D,qBACa,oBAAqB,SAAQ,yBAAyC;IAE3E,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,aAAa;IAcpC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG;CA0C5C"}

package/dist/modules/auth/refresh-token.strategy.js

@@ -15,9 +15,8 @@ const passport_1 = require("@nestjs/passport");
 const passport_jwt_1 = require("passport-jwt");
 const config_1 = require("@nestjs/config");
 const prisma_service_1 = require("../../prisma/prisma.service");
-const user_service_1 = require("../user/user.service");
 let RefreshTokenStrategy = exports.RefreshTokenStrategy = class RefreshTokenStrategy extends (0, passport_1.PassportStrategy)(passport_jwt_1.Strategy, 'jwt-refresh') {
-    constructor(configService, prisma, userService) {
+    constructor(configService, prisma) {
         const refreshSecret = configService.get('JWT_REFRESH_SECRET');
         if (!refreshSecret) {
             throw new Error('JWT_REFRESH_SECRET is not defined in environment variables!');
@@ -29,13 +28,18 @@ let RefreshTokenStrategy = exports.RefreshTokenStrategy = class RefreshTokenStra
         });
         this.configService = configService;
         this.prisma = prisma;
-        this.userService = userService;
     }
     async validate(req, payload) {
         const refreshToken = req.body.refreshToken;
         if (!refreshToken)
             throw new common_1.UnauthorizedException('Refresh token not found');
-        const user = await this.userService.findByField("id", payload.sub);
+        // Auth-flow lookup: the refresh request is unauthenticated (GUEST), so
+        // this must bypass ABAC like every other auth lookup in this module.
+        const user = await this.prisma.user.findFirst({
+            where: { id: payload.sub },
+        }, {
+            BYPASS_FILTERING: true,
+        });
         if (!user) {
             throw new common_1.UnauthorizedException('User not found');
         }
@@ -65,6 +69,5 @@ let RefreshTokenStrategy = exports.RefreshTokenStrategy = class RefreshTokenStra
 exports.RefreshTokenStrategy = RefreshTokenStrategy = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [config_1.ConfigService,
-        prisma_service_1.PrismaService,
-        user_service_1.UserService])
+        prisma_service_1.PrismaService])
 ], RefreshTokenStrategy);

package/docs/README.md

@@ -10,7 +10,9 @@ Authoritative usage documentation for `@appxdigital/appx-core`. **This folder is
 - **[data-access.md](./data-access.md)** — how you talk to the database: the Prisma proxy (`prisma.model.*`), how ABAC filtering and field omission are enforced on every call, the redirected single-record methods, relation behaviour, bypass hatches, and transactions.
 - **[authentication.md](./authentication.md)** — the built-in `/auth` surface, and **how to override framework internals** (extend the exported `AuthController`/`AuthService`/`RegisterDto`/Passport strategies and register your own at the same prefix via `AuthModule.forRoot({ controller: false })`) — e.g. adding `name` to registration.
 - **[graphql.md](./graphql.md)** — the **read-only** GraphQL API generated from your schema: queries, nested selections, and how ABAC filters them.
-- **[limitations.md](./limitations.md)** — **known limitations and features that are NOT ready for use** (e.g. `aggregate`, GraphQL writes). Read this before relying on any method not covered in the guides above.
+- **[testing.md](./testing.md)** — the test suite every new project ships with: `npm test` on a throwaway DB container, the HTTP harness (`api(actor)`, `registerActor`, raw `prisma`), and the route-sweep backstop.
+- **[storage.md](./storage.md)** — file uploads & object storage: the `setup:fileupload` wizard, per-endpoint size/MIME/role rules, and the S3 / GCS / local providers.
+- **[limitations.md](./limitations.md)** — **known limitations and features that are NOT ready for use** (e.g. `aggregate`). Read this before relying on any method not covered in the guides above.
 
 ## The one-paragraph mental model
 

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.
 

package/docs/dtos.md

@@ -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.
 

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 **`setUserIdField`** (see below).
 
 **Model and role keys are matched case-insensitively** against the model name and the caller's role string.
 

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.129",
     "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",