@appxdigital/appx-core 0.1.121-beta.11 → 0.1.121-beta.5

package/CHANGELOG.md

@@ -1,123 +0,0 @@
-# Changelog
-
-All notable changes to `@appxdigital/appx-core` are documented here.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-This project follows the `MAJOR.MINOR.PATCH` scheme in `package.json`.
-
-## How to read this file
-
-- **This file is the collapsed, production changelog** — one section per version published to the `latest` dist-tag. Granular per-build notes for `alpha`/`beta` prereleases live in [`PRERELEASES.md`](./PRERELEASES.md); the release process is documented in [`RELEASING.md`](./RELEASING.md).
-- **Every released version has a section.** Newest first.
-- **Changes that require action in an existing project are listed under `### Migration`** — copy-paste ready, small enough to hand to an AI coding agent. Items outside that block are drop-in.
-- **Scaffold-only changes** (files under `cli/scaffold/`) affect *new* projects created with `appx-core create`. Existing projects own their copies of those files and apply the migration by hand.
-
----
-
-## [0.1.121] — 2026-07-14
-
-Hardening release: request validation, boot configuration, generated-CRUD DTOs, and data-access create enforcement.
-
-> ## ⚠️ REQUIRED migration — upgrading the dependency is NOT enough
->
-> **This is a security release, and its protections are INERT until you adapt your codebase.** Bumping `@appxdigital/appx-core` to `0.1.121` (including any `0.1.121-beta.x`) and doing nothing else leaves your app **vulnerable** — generated `POST`/`PUT` endpoints keep accepting arbitrary fields (mass-assignment), because the request-validation DTOs only take effect once you regenerate them **and** wire them into your controllers.
->
-> **You MUST complete every step in [Migration](#migration) below — this is not optional and must not be skipped.** In particular:
-> - **Step 4 (generated-CRUD DTOs) is mandatory**: run `npx appx generate`, then add the DTO-typed `create`/`update` overrides to *every* existing generated controller. Generation alone does nothing; the controllers must import and use the DTOs.
-> - Steps 1–3 (`main.ts` / `app.module.ts`) are required for the boot-time hardening (validation pipe, session secret, CORS, `NODE_ENV`) to apply.
-> - Step 5 is a behaviour change (create is now permission-checked) — review it before deploying.
->
-> **For AI agents:** do not report this upgrade as complete until steps 1–5 are applied and the app builds. If you only changed the version number, the task is unfinished.
-
-### Added
-
-- **`setupCoreSecurity(app, options?)`** — one call that applies baseline HTTP hardening: a global `ValidationPipe` (`{ transform: true, whitelist: true, forbidNonWhitelisted: true }`), CORS (`cors` option, default `{ origin: 'http://localhost:3000', credentials: true }`, throws if `origin: '*'` is combined with `credentials: true`), and **Helmet** security headers (on by default; `helmet` option to tune/disable). `helmet` is a new peer dependency.
-- **`buildCoreSessionOptions({ secret, store, cookieName?, ttlSeconds?, secure?, sameSite? })`** — builds hardened `express-session` options. Throws if `secret` is missing or `< 32` chars (no fallback); sets `cookie: { httpOnly, secure (prod), sameSite: 'lax', maxAge }`.
-- **`coreEnvFilePath()`** — returns `['.env.${NODE_ENV}', '.env']` (env-specific file wins, plain `.env` is a fallback) and throws if `NODE_ENV` is unset.
-- **Per-model DTO generation** (`appx generate`). Each model+action gets a `class-validator` DTO so generated controllers type their request body concretely and the whitelist pipe can strip unknown fields. Two files:
-  - `src/generated/dto/<model>/<action>-<model>.generated.dto.ts` — base class, **always overwritten**, under the gitignored `src/generated/`. Never hand-edit.
-  - `src/modules/<model>/dto/<action>-<model>.dto.ts` — a hand-owned subclass, generated **once**, for custom validation. The controller imports this.
-- **`/// @NoWrite` field annotation** — excludes a field from the generated create/update DTOs (all roles). Fields annotated `/// @Role(none)` are also treated as non-writable.
-- **Create-permission enforcement in the data-access proxy.** `create` / `createMany` validate that the incoming data satisfies the permission's `conditions` before insert (own-scalar fields against the data; relation conditions by looking up the referenced parent), and default-deny when the model/role has no `create` permission. A development-only warning fires when a created row would not satisfy the model's `find` conditions.
-- **`restrictedFields` on `create`** in `CoreController` (previously only `update`, which also read the wrong permission key so it never applied under `updateMany`).
-
-### Writable-field policy (generated DTOs)
-
-A scalar field is included unless it is: the primary key (`@id`), a server-managed timestamp (`@default(now())` / `@updatedAt`), `/// @NoWrite`, or `/// @Role(none)`. Relation navigation fields are excluded; their scalar foreign keys are kept. Enums map to `@IsEnum`, scalars to the matching `@IsString`/`@IsInt`/`@IsBoolean`/`@IsNumber`/`@IsDateString`; `Json`/`Bytes` use `@Allow()`.
-
-### Changed (scaffold — new projects only)
-
-- `main.ts` calls `setupCoreSecurity(app, { cors: { origin: corsOrigin, credentials: true } })`, builds session options via `buildCoreSessionOptions`, and reads `CORS_ORIGIN` from config.
-- `app.module.ts` uses `coreEnvFilePath()` for `envFilePath`.
-- Generated `package.json` adds `helmet`; the `start` script sets `NODE_ENV=development`.
-- `AuthController.getAllSessions` / `closeSpecificSession` use `@UseGuards(AuthenticatedGuard)`.
-
-### Migration
-
-> **Required for every existing project. All five steps must be applied** — the edits are to files you own (`main.ts` / `app.module.ts` / `package.json` / your generated controllers), so they are safe to hand to an AI coding agent, but they are **not optional**. The app is not secured until they are done and it builds.
-
-**1. Request validation & HTTP hardening — `src/main.ts`.**
-```ts
-import { setupCoreSecurity } from '@appxdigital/appx-core';
-// remove: app.useGlobalPipes(new ValidationPipe({ transform: true }));
-// remove: app.enableCors({ origin: 'http://localhost:3000', credentials: true });
-const corsOrigin = configService.get<string>('CORS_ORIGIN') ?? 'http://localhost:3000';
-setupCoreSecurity(app, { cors: { origin: corsOrigin, credentials: true } });
-```
-- Install Helmet: `npm install helmet@^8.0.0` (applied automatically by `setupCoreSecurity`; tune with `{ helmet: {...} }`, disable with `{ helmet: false }`).
-- If you register a `ValidationPipe` with custom options, pass them through: `setupCoreSecurity(app, { validationPipe: { /* overrides */ } })`.
-- With `whitelist` + `forbidNonWhitelisted`, body properties not declared on a `class-validator` DTO are rejected (`400`). Confirm every DTO declares every field it legitimately accepts before deploying.
-- Set `CORS_ORIGIN` to your real front-end origin in production. Do not combine `'*'` with credentials — the helper throws at boot. For a public credential-less API pass `{ cors: { origin: '*', credentials: false } }`.
-
-**2. Session secret & cookie flags — `src/main.ts`.**
-```ts
-import { buildCoreSessionOptions } from '@appxdigital/appx-core';
-// replace your inline session({ secret: … }) (drop any hardcoded fallback secret) with:
-app.use(session(buildCoreSessionOptions({
-  secret: configService.get<string>('SESSION_SECRET'),
-  cookieName: configService.get<string>('SESSION_COOKIE_NAME'),
-  ttlSeconds: configService.get<number>('SESSION_TTL') || 86400,
-  store: new CorePrismaSessionStore(prismaService, { ttl: sessionTTL }),
-})));
-```
-Ensure `SESSION_SECRET` is set (≥ 32 chars) in every environment — the app now refuses to boot without it.
-
-**3. Environment file & `NODE_ENV` — `src/app.module.ts`.**
-```ts
-import { coreEnvFilePath } from '@appxdigital/appx-core';
-// ConfigModule.forRoot({ … envFilePath: coreEnvFilePath() })
-```
-Set `NODE_ENV` explicitly (`production` / `development`) in every deploy and start script — boot fails if it is unset. If you use a bare `nest start`, change it to `cross-env NODE_ENV=development nest start`. (`coreEnvFilePath()` loads `.env.<NODE_ENV>` with `.env` as a fallback, so a plain `.env` still works.)
-
-**4. Generated-CRUD DTOs — MANDATORY (this is the mass-assignment fix; do not skip).**
-
-Without this step, your generated `POST`/`PUT` endpoints still accept arbitrary fields — the vulnerability this release closes stays open. Two parts, **both required**:
-
-(a) Regenerate:
-```bash
-npm install @appxdigital/appx-core@^0.1.121
-npx appx generate
-```
-(b) **Add the DTO-typed overrides to EVERY existing generated controller** (they are generated once and never overwritten, so `appx generate` will NOT add them for you — you must edit each controller by hand or delete and regenerate it):
-```ts
-import { Body, Param, Post, Put } from '@nestjs/common';
-import { Permission } from '@appxdigital/appx-core';
-import { Create<Model>Dto } from './dto/create-<model-kebab>.dto';
-import { Update<Model>Dto } from './dto/update-<model-kebab>.dto';
-
-@Post() @Permission('create')
-async create(@Body() data: Create<Model>Dto) { return super.create(data as any); }
-
-@Put(':id') @Permission('updateMany')
-async update(@Param('id') id: string, @Body() data: Update<Model>Dto) { return super.update(id, data as any); }
-```
-(Or delete an un-customized controller and re-run `appx generate` for the new template.) Add custom validation in the hand-owned `dto/*.dto.ts` subclasses — never in the `.generated.dto.ts` base. Lock sensitive columns with `/// @NoWrite` (all roles) or `restrictedFields` on the permission (per role), then regenerate. To drop a field from one endpoint's DTO, extend `OmitType(<Model>GeneratedDto, ['field'] as const)`. Full details in [`docs/dtos.md`](../docs/dtos.md).
-
-> **Nested relation writes are now an explicit, permission-gated allowlist — this is a behaviour restriction; a migrating agent MUST flag it to the developer.** Generated **create** DTOs accept only two nested operators, each authorized by ABAC: **`create`** (checked against the related model's `create` rule) and **`connect`** (checked against the related model's new dedicated **`connect`** permission — a `connect` rule is required; no rule ⇒ refused). Every other operator (`set`, `disconnect`, `update`, `upsert`, `delete`, …) is rejected (`400`). Nested writes are available on **`create` only** — `update` resolves to `updateMany`, whose payload is scalar-only. **Keep `forbidNonWhitelisted: true` on (fail loud); never `whitelist`-strip on writes.**
->
-> **For AI agents doing this migration on an existing project:** this can break existing behaviour. Before deploying, tell the developer explicitly that (a) any nested operator other than `create`/`connect` used through CRUD will now `400`, (b) every model that is nested-`connect`ed now needs a `connect` permission or the request fails, and (c) nested writes no longer work on update endpoints. Do not proceed silently. See [`docs/dtos.md`](../docs/dtos.md#relations--nested-writes) and [`docs/permissions.md`](../docs/permissions.md).
-
-**5. Create-permission enforcement (behaviour change — review before upgrading).**
-- Ensure every model/role that legitimately creates records has an explicit `create` permission (or `'ALL'`). Without one, create now returns `403` (previously unchecked). Internal framework flows (registration, sessions, tokens) are unaffected.
-- If you supplied arbitrary values for a field a `create` condition constrains (e.g. an owner id), those requests now return `403` unless the value matches — use `setUserIdField` to have the framework set it.
-- **`restrictedFields` under `updateMany` now applies** (it was a no-op before). Fields listed there are stripped on `PUT`. Remove any field that should remain writable.

package/PRERELEASES.md

@@ -1,151 +0,0 @@
-# Prerelease log
-
-> ## ⚠️ Every `0.1.121-beta.x` is part of a SECURITY-hardening release — a required migration applies
->
-> Adopting any `0.1.121` beta from `0.1.120` (or earlier) requires the **mandatory migration in [`CHANGELOG.md`](./CHANGELOG.md) under `[0.1.121]`** — most importantly **regenerating the per-model DTOs and wiring them into your controllers** (`npx appx generate` + adding the DTO-typed `create`/`update` overrides to every generated controller). **Bumping the version without doing this leaves generated `POST`/`PUT` endpoints accepting arbitrary fields.**
->
-> The per-build notes below are **incremental deltas relative to the previous beta**. When an entry says "no code change" or "regenerate not required", it means *nothing new to do versus the prior beta* — it does **not** waive the `[0.1.121]` migration you owe when coming from `0.1.120`.
->
-> **AI agents:** do not report a `0.1.121` upgrade as done until the `CHANGELOG.md [0.1.121]` migration steps 1–5 are applied and the project builds.
-
-Granular notes for **alpha / beta** builds of both packages —
-`@appxdigital/appx-core` (library) and `@appxdigital/appx-core-cli` (CLI) —
-newest first. Entries are labelled by package. These are the builds you install
-to test a change in a real project before it ships:
-
-```bash
-npm install @appxdigital/appx-core@beta            # library, latest beta
-npm install @appxdigital/appx-core@0.1.121-beta.0  # a specific library build
-npx  @appxdigital/appx-core-cli@beta create        # CLI, latest beta
-```
-
-Each prerelease gets its own entry here with fine-grained notes. When a version
-is promoted to production it is **collapsed** into a single curated section in
-[`CHANGELOG.md`](./CHANGELOG.md) with aggregated changes and consolidated
-migration steps — that public changelog is the one an upgrading project reads.
-Nothing here is a substitute for it.
-
-Prereleases are excluded from normal semver range resolution, so a project on
-`^0.1.x` never pulls one by accident — you always opt in via the `@beta` /
-`@alpha` tag or an exact version.
-
----
-
-## [0.1.121-beta.11] — unreleased
-
-**Docs.** No code change. Documented that nested writes over HTTP CRUD are
-**one level deep** (a nested `create` DTO exposes the related model's scalars +
-`connect`, not its own relations, to avoid circular DTOs). The proxy's
-authorization is recursive; the DTO surface is the cap — deeper nesting `400`s,
-and multi-level nested writes belong in an explicit endpoint. See `docs/dtos.md`
-and `docs/limitations.md`.
-
-## [0.1.121-beta.10] — unreleased
-
-**Library.** **Nested relation writes on generated CRUD are now an explicit,
-permission-gated allowlist.** A `create` body may nest **`create`** and
-**`connect`** on its relations; both are authorized by ABAC (`create` → the
-related model's `create` rule, recursively; `connect` → the related model's new
-dedicated **`connect`** permission — a `connect` rule is required, because being
-able to *read* a record does not authorize associating it). Every other nested
-operator (`set` / `disconnect` / `update` / `upsert` / `delete` / …) is rejected
-at both the DTO layer (not emitted → `400`) and the proxy (throws). Nested
-writes are available on **`create` only** (`update` resolves to `updateMany`,
-which is scalar-only).
-
-- **Behaviour restriction — review on upgrade.** If a project used other nested
-  operators through CRUD, or connected models without a `connect` rule, those
-  requests now fail. Add `connect` rules where needed; move unsupported nested
-  writes to explicit endpoints. Keep `forbidNonWhitelisted: true` (fail loud).
-
-## [0.1.121-beta.9] — unreleased
-
-**Docs / packaging.** No code change.
-
-- Added a **`docs/` folder** (now shipped inside the npm package) — the
-  framework's source-of-truth guide: `permissions.md` (RBAC config +
-  `@Permission`/`@ExposeModels`), `data-access.md` (the Prisma proxy, ABAC
-  enforcement, single-record method contract, relations, transactions) and
-  `limitations.md` (not-ready features incl. `aggregate`/GraphQL, and caveats).
-- **Clarified the `[0.1.121]` migration in `CHANGELOG.md`.** It is now explicit
-  that regenerating the per-model DTOs and wiring them into every controller is
-  **mandatory** (it is the mass-assignment fix), and that a version bump without
-  it leaves `POST`/`PUT` endpoints accepting arbitrary fields.
-
-## [0.1.121-beta.8] — unreleased
-
-**Library.**
-
-- **Single-record data-access methods now have an honest typed contract.**
-  `prisma.model.*` re-aliases the methods that can't carry ABAC conditions, in
-  both the types and the runtime dispatch: `findUnique`→`findFirst`,
-  `findUniqueOrThrow`→`findFirstOrThrow`, `update`→`updateMany`,
-  `delete`→`deleteMany`. A mismatched call now fails at compile time instead of
-  the old runtime throw. **Breaking (types only):** `update()`/`delete()` return
-  `{ count }` and `findUnique()` takes a non-unique `where` with a nullable
-  return — adjust the call sites the compiler flags. A `*Many` permission action
-  now inherits its singular rule (`updateMany`→`update`, `deleteMany`→`delete`,
-  `createMany`→`create`), so a config can declare just `update`/`delete`/`create`.
-- **`@ExposeModels(...models)`** — expose models on a route WITHOUT a permission
-  action, for public / GUEST endpoints that must read an otherwise-restricted
-  model without adding a `GUEST` rule for it. `@Permission(action, models)` keeps
-  working unchanged. Exposed-model matching is case-insensitive.
-
-## [0.1.121-beta.7] — unreleased
-
-**Library.** `createMany` now inherits the `create` permission when not declared
-explicitly — in both the data-access proxy and the `RbacGuard`. A
-`permissions.config.ts` can declare a single `create` rule and have it cover
-`createMany` too (mirrors the existing `findMany → count/findFirst` fallback).
-One-directional: declaring only `createMany` does **not** enable `create`.
-
-- If you previously duplicated `create` and `createMany`, the `createMany` entry
-  is now redundant (harmless to keep). No action required.
-
-## [0.1.121-beta.6] — unreleased
-
-**Packaging.** The npm tarball now ships `CHANGELOG.md`, `PRERELEASES.md`, and
-`RELEASING.md` (previously only `dist/` + `README.md`). Migration steps are now
-readable from inside an installed `node_modules/@appxdigital/appx-core`, so an
-upgrading project (or an AI agent) can apply them without cloning the repo. No
-code change.
-
-## [0.1.121-beta.5] — unreleased
-
-**Library.** Field-level access control (`/// @Role(...)`) now applies to
-**nested** relation selections, not just top-level fields. Previously a query
-that selected a restricted field *through* a relation
-(`select: { relation: { select: { restrictedField: true } } }`) received that
-field; the data-access proxy now omits it at every depth, for both `select` and
-`include`, while preserving any `where` / `orderBy` you set on the relation.
-
-- Exercise reads that pull fields through relations (nested `select` / `include`,
-  including multi-level) and confirm the values you expect still come back — a
-  field annotated `@Role(<roles>)` should be absent for roles not listed.
-- No API change; regenerate is not required.
-
-## [0.1.121-beta.0] — unreleased
-
-First prerelease of the `0.1.121` hardening set. Testing target before this is
-promoted to `latest`. Full aggregated notes and migration live under
-`[0.1.121]` in `CHANGELOG.md`; the highlights to exercise in a project:
-
-- **`setupCoreSecurity(app, options?)`** — one call for the global
-  `ValidationPipe` (whitelist + `forbidNonWhitelisted`), CORS, and Helmet.
-  Verify existing DTOs still accept every field they legitimately take (the
-  whitelist rejects undeclared body properties with `400`).
-- **`buildCoreSessionOptions(...)`** — requires a session secret ≥ 32 chars and
-  sets hardened cookie flags. Confirm your env provides the secret.
-- **`coreEnvFilePath()`** — `['.env.${NODE_ENV}', '.env']`; throws if
-  `NODE_ENV` is unset. Confirm boot scripts set `NODE_ENV`.
-- **Per-model generated DTOs** — regenerate (`appx generate`) and check the
-  generated controllers compile and accept your writable fields.
-- **Create-permission enforcement in the data-access proxy** — `create` /
-  `createMany` now validate incoming data against the permission conditions and
-  default-deny when a model/role has no `create` permission. Exercise every
-  create path in the consuming app and confirm intended creates still succeed;
-  set explicit `create` permissions (or `ALL`) where needed.
-
-> How to try it: bump this package to `0.1.121-beta.0` in the project under
-> test (`npm install @appxdigital/appx-core@beta`), run the app's own suite,
-> and smoke-test create/update flows and boot. Report back before promotion.

package/RELEASING.md

@@ -1,168 +0,0 @@
-# Releasing
-
-This repo publishes **two independent packages**, each versioned on its own:
-
-- **`@appxdigital/appx-core`** — the runtime library (root `package.json`),
-  released via **`v*`** tags (`release.yml`).
-- **`@appxdigital/appx-core-cli`** — the `appx-core` CLI (`cli/package.json`),
-  released via **`cli-v*`** tags (`release-cli.yml`).
-
-Both follow the same posture: publishing is deliberate — **it only happens when
-you push a git tag** — and production (`latest`) pauses for a human approval
-before it goes live.
-
-## Channels
-
-Library (`v*` tags):
-
-| You push tag       | npm dist-tag | Consumers install with            | Gated?          |
-| ------------------ | ------------ | --------------------------------- | --------------- |
-| `v1.2.3-alpha.N`   | `alpha`      | `…/appx-core@alpha`               | no              |
-| `v1.2.3-beta.N`    | `beta`       | `…/appx-core@beta`                | no              |
-| `v1.2.3-rc.N`      | `next`       | `…/appx-core@next`                | no              |
-| `v1.2.3`           | `latest`     | `…/appx-core` (default)           | **yes** — approval |
-
-CLI (`cli-v*` tags) — identical channels for `@appxdigital/appx-core-cli`:
-
-| You push tag         | npm dist-tag | Consumers install with          | Gated?          |
-| -------------------- | ------------ | ------------------------------- | --------------- |
-| `cli-v1.2.3-beta.N`  | `beta`       | `…/appx-core-cli@beta`          | no              |
-| `cli-v1.2.3`         | `latest`     | `…/appx-core-cli` (default)     | **yes** — approval |
-
-Prereleases are excluded from `^1.2.x` range resolution, so a project on a caret
-range never pulls one by accident — testers opt in via the tag or an exact
-version. Merging to `main` **never** publishes; it only runs CI (library build +
-tests on mysql and postgres, plus a CLI smoke check).
-
-## Two files, two audiences
-
-- **`PRERELEASES.md`** — granular, one entry per alpha/beta build. What a tester
-  reads.
-- **`CHANGELOG.md`** — collapsed, one section per production release with
-  aggregated changes and consolidated migration steps. What an upgrading project
-  reads. When you promote a version, distil its prerelease entries into a single
-  `CHANGELOG.md` section.
-
-## One-time setup (before the first publish)
-
-1. **npm Trusted Publisher (OIDC) — one per package.** On npmjs.com → the
-   package → *Settings* → *Trusted Publisher* → GitHub Actions. Add **two**,
-   both owner `appxdigital`, repo `appx-core`:
-   - `@appxdigital/appx-core` → workflow `release.yml`
-   - `@appxdigital/appx-core-cli` → workflow `release-cli.yml`
-
-   This lets CI mint a short-lived publish token per run — **no `NPM_TOKEN`
-   secret is stored anywhere**, and every publish carries supply-chain
-   provenance.
-
-2. **GitHub `production` environment (the approval gate).** Repo → *Settings* →
-   *Environments* → *New environment* → name it exactly `production` → enable
-   *Required reviewers* and add yourself (and/or the team). The
-   `publish-production` job targets this environment, so a clean tag will wait
-   for a click before publishing to `latest`.
-
-## Cutting a release
-
-The tag must match `package.json`'s version exactly, or the release job fails
-fast (a guard against mistagging). Convenience scripts keep them in lockstep and
-create the tag for you — they **do not push**, so pushing stays a deliberate
-step:
-
-There are two per package — a **test build** and a **production release**:
-
-| Script                          | What it does                          | Tag             | Goes to           |
-| ------------------------------- | ------------------------------------- | --------------- | ----------------- |
-| `npm run release:beta`          | library test build (`…-beta.N`)       | `v…-beta.N`     | `beta` channel    |
-| `npm run release:production`    | promote library to everyone           | `vX.Y.Z`        | `latest` (gated)  |
-| `npm run release:cli:beta`      | CLI test build (`…-beta.N`)           | `cli-v…-beta.N` | `beta` channel    |
-| `npm run release:cli:production`| promote CLI to everyone               | `cli-vX.Y.Z`    | `latest` (gated)  |
-
-`release:beta` publishes only to people who opt in with `@beta`; `release:production`
-is what everyone gets by default, and it pauses for your approval before going
-live. Each command bumps the version, commits, and creates the tag, then prints
-the exact `git push origin HEAD --follow-tags` for you to run when ready — they
-never push on their own.
-
-Rarer cases go through the underlying script directly:
-`node scripts/release.mjs lib alpha` (alpha channel), `… lib minor` (a feature
-bump), or `… lib X.Y.Z-beta.0` (an explicit version — e.g. the first beta of a
-version already sitting in `package.json`).
-
-The manual steps below show what those scripts do under the hood.
-
-### Beta (test in projects first)
-
-```bash
-# set the version + create the matching tag + commit, without auto-pushing
-npm version 0.1.121-beta.0 --message "release: %s"
-git push origin main --follow-tags
-```
-
-The `Release` workflow builds, tests, and publishes to the `beta` dist-tag.
-Then, in a project you want to test against:
-
-```bash
-npm install @appxdigital/appx-core@beta
-```
-
-Iterate with `npm version prerelease --preid beta` (→ `-beta.1`, `-beta.2`, …),
-each push publishing a new granular `PRERELEASES.md` entry.
-
-### Promote to production (`latest`)
-
-When the beta is validated in real projects:
-
-```bash
-# drop the prerelease suffix -> clean version
-npm version 0.1.121 --message "release: %s"
-git push origin main --follow-tags
-```
-
-The workflow builds and tests, then **pauses** on the `production` environment.
-Approve it in the repo's *Actions* tab → the running release → *Review
-deployments* → *Approve and deploy*. It then publishes to `latest`.
-
-> Alternatively, promotion can be a pure retag without republishing:
-> `npm dist-tag add @appxdigital/appx-core@0.1.121-beta.N latest`. The
-> tag-driven workflow above is preferred because it re-runs tests and records
-> provenance for the exact `latest` artifact.
-
-### Alpha (rough, one or two projects)
-
-```bash
-npm version 0.1.122-alpha.0 --message "release: %s"
-git push origin main --follow-tags
-# in the project:  npm install @appxdigital/appx-core@alpha
-```
-
-### CLI (`@appxdigital/appx-core-cli`)
-
-Same flow, but bump `cli/package.json` and use the `cli-v` tag prefix. The tag
-must match `cli/package.json`'s version.
-
-```bash
-# beta:
-npm --prefix cli version 1.0.21-beta.0 --message "release cli: %s"
-git commit -am "release cli: 1.0.21-beta.0"   # npm version --prefix does not commit
-git tag cli-v1.0.21-beta.0
-git push origin main --follow-tags
-#   test:  npx @appxdigital/appx-core-cli@beta create …
-
-# production (gated — approve in the Actions tab):
-npm --prefix cli version 1.0.21 --message "release cli: %s"
-git commit -am "release cli: 1.0.21"
-git tag cli-v1.0.21
-git push origin main --follow-tags
-```
-
-> `npm version --prefix cli` bumps `cli/package.json` but does not create the
-> git commit/tag (that only happens when run in the repo root). Commit and tag
-> explicitly with the `cli-v` prefix as shown.
-
-## Manual fallback
-
-If CI is unavailable, you can still publish by hand: `rimraf dist && npm run
-build && npm publish --tag <dist-tag> --access public` for the library, and
-`cd cli && npm publish --tag <dist-tag> --access public` for the CLI. This
-bypasses the tests, the approval gate, and provenance, so prefer the tag-driven
-flow.

package/docs/README.md

@@ -1,21 +0,0 @@
-# AppX Core — Documentation
-
-Authoritative usage documentation for `@appxdigital/appx-core`. **This folder is the source of truth** for how the framework behaves — humans and AI agents should read it here rather than inferring patterns from source code. If code and these docs disagree, that is a bug in one of them; fix it, don't guess.
-
-## Contents
-
-- **[permissions.md](./permissions.md)** — the authorization model: the `@Permission` and `@ExposeModels` decorators, the `permissions.config.ts` shape, roles/actions, row-level `conditions`, field-level control, action fallbacks, and the `GUEST` (unauthenticated) flow.
-- **[dtos.md](./dtos.md)** — the generated CRUD validation DTOs: their two-file structure, **how to remove a field** (`OmitType` / `@NoWrite` / `restrictedFields`), how to add validation, and why nested relation writes don't belong on generic CRUD.
-- **[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.
-- **[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.
-
-## The one-paragraph mental model
-
-AppX Core wraps the Prisma client in a proxy that enforces **attribute-based access control (ABAC)** on every database call. You declare row-level and field-level rules once in `permissions.config.ts`; the proxy injects them into each query automatically based on the current request's user role. Controllers/resolvers are generated from your Prisma schema. The rules of the road: **go through the proxy** (`prismaService.model.*`) so ABAC applies, **declare a permission for every model/role/action** you want to allow (everything else is default-denied), and **check [limitations.md](./limitations.md)** before using a method.
-
-## Conventions used in these docs
-
-- `$USER_ID` refers to `PermissionPlaceholder.USER_ID` — a placeholder replaced with the current user's id at query time.
-- "the proxy" means the `PrismaService` client returned by `prismaService.model` (and the `prisma.user` / `prisma.session` / `prisma.userRefreshToken` accessors).
-- "default-deny" means: if no rule matches, the request is refused (a `403` at the guard, or a thrown `HttpException` at the proxy) — never silently allowed.

package/docs/data-access.md

@@ -1,108 +0,0 @@
-# Data Access & ABAC Enforcement
-
-How you read and write the database, and exactly what the proxy does to every call. Pair this with [permissions.md](./permissions.md) (which defines the rules) and [limitations.md](./limitations.md) (what not to use yet).
-
----
-
-## Always go through the proxy
-
-Inject `PrismaService` and use `prismaService.model.*`:
-
-```ts
-const projects = await this.prisma.model.project.findMany({ where: { status: 'active' } });
-```
-
-`prismaService.model` returns a proxied Prisma client. **Only calls through this proxy get ABAC.** If you reach the raw Prisma client directly (a second `PrismaClient`, raw SQL, `$queryRaw`), you bypass all filtering and field omission. There is **no defence-in-depth at the controller layer** for row rules — the proxy is the single enforcement point.
-
-There are also three narrow typed accessors — `prismaService.user`, `prismaService.session`, `prismaService.userRefreshToken` — which are the proxied delegates for those framework models (used by auth flows, often with the bypass options below).
-
-Model names are **case-insensitive** at the proxy (`prisma.model.project` / `prisma.model.Project` resolve the same delegate and the same config).
-
----
-
-## What the proxy does on every call
-
-For each `prisma.model.<model>.<method>(args, options?)`:
-
-1. **Field omission** (reads only) — removes columns the role may not read (`/// @Role(...)`), recursing into nested `select`/`include` at every depth.
-2. **Condition injection** — looks up `PermissionsConfig[model][role][action]`; if `'ALL'`, no filter; if `{ conditions }`, `AND`-merges them into your `where` (so your filter and the permission filter both apply); if nothing (after fallbacks), throws `403`.
-3. **Executes** the (possibly rewritten) query.
-
-The role comes from the current request's user (`GUEST` if unauthenticated). Requests run inside an async context established by the framework's middleware/interceptor.
-
----
-
-## Method contract (important)
-
-The proxy can only enforce ABAC on methods that accept a `where` it can inject conditions into. Single-record methods keyed on a unique id cannot, so they are **re-aliased** — in both the TypeScript types and at runtime:
-
-| You call | Actually runs | Params / return you get |
-|---|---|---|
-| `findUnique()` | `findFirst()` | non-unique `where`, nullable result |
-| `findUniqueOrThrow()` | `findFirstOrThrow()` | non-unique `where` |
-| `update()` | `updateMany()` | `{ where, data }`, returns `{ count }` |
-| `delete()` | `deleteMany()` | `{ where }`, returns `{ count }` |
-
-**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.
-
-Use `findMany` / `findFirst` / `findFirstOrThrow` / `updateMany` / `deleteMany` directly if you prefer the explicit names.
-
----
-
-## Field omission (`@Role`)
-
-A column annotated `/// @Role(ADMIN)` is returned only to roles in the list; for others the proxy drops it from the `select` so it comes back `undefined`. `/// @Role(none)` hides it from everyone (e.g. `password`).
-
-- Omission applies to nested relations too: `include: { owner: true }` won't leak `owner`'s `@Role`-restricted fields to an unauthorized role.
-
----
-
-## Relations in conditions and includes
-
-- **Row conditions** may traverse relations to any depth: `{ conditions: { task: { project: { ownerId: $UID } } } }`. Both `belongsTo` (to-one) and `hasMany` / M:N (`some`/`every`/`none`) are supported. Note Prisma semantics: `every` is **true on an empty list**.
-- **Including a to-one relation is inner-join filtered.** When you `include`/`select` a `belongsTo` relation, the related model's read rules are merged into the **parent** row's `where`:
-  - 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).
-
----
-
-## Bypass hatches
-
-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).
-- **`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`.
-
----
-
-## Creates
-
-`create` / `createMany` can't push conditions into a `WHERE`, so the proxy **validates the incoming data against the create rule's `conditions` before insert**:
-
-- 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.
-- 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).
-
----
-
-## Transactions
-
-Set `USE_TRANSACTION=true` (env) to wrap each request handler in a Prisma `$transaction`; per-endpoint control via the transaction metadata. The framework commits the transaction **before** sending the HTTP response, so a read-after-write in a dependent request can't miss the write. Inside a transaction the proxy uses the request's transaction client automatically.
-
----
-
-## Blocked / redirected methods — quick reference
-
-- `findUnique` / `findUniqueOrThrow` → run as `findFirst` / `findFirstOrThrow` (see contract above).
-- `update` / `delete` → run as `updateMany` / `deleteMany`.
-- Raw client access, `$queryRaw`, a second `PrismaClient` → **not proxied, no ABAC**. Don't use them for user-scoped data.
-- `aggregate` → see [limitations.md](./limitations.md) (not ready).