Feature/version 8

.github/workflows/ci-merge.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [22.x]
     steps:
       - uses: actions/checkout@v2
       - name: Enable Corepack
@@ -33,9 +33,9 @@ jobs:
       - name: Process Test Results
         uses: dorny/test-reporter@v1
         with:
-          name: Jest Tests
+          name: Unit Tests
           path: "junit.xml"
-          reporter: jest-junit
+          reporter: java-junit
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v2
         with:

.github/workflows/ci-pr-report.yml

@@ -16,9 +16,9 @@ jobs:
         uses: dorny/test-reporter@v1
         with:
           artifact: test-results
-          name: Jest Tests
+          name: Unit Tests
           path: 'junit.xml'
-          reporter: jest-junit
+          reporter: java-junit
   coverage-report:
     runs-on: ubuntu-latest
     steps:

.github/workflows/ci-pr-test.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [22.x]
 
     steps:
       - uses: actions/checkout@v2

.gitignore

@@ -22,6 +22,9 @@ lib-cov
 coverage
 *.lcov
 
+# Vitest junit reporter output (yarn test:ci)
+junit.xml
+
 # nyc test coverage
 .nyc_output
 
@@ -111,4 +114,5 @@ dist
 /docs
 
 # .yarn meta
-.yarn
+.yarn
+.claude/settings.local.json

README.md

@@ -20,6 +20,9 @@ Rapid Enterprise Development Toolkit
 A collection of NestJS modules
 that were created for the rapid development of enterpise level APIs.
 
+The v8 line is schema-first — native Zod v4 / Standard Schema validation,
+serialization, and OpenAPI — on NestJS 12, ESM-only, Node >= 22.
+
 All reasonable efforts have been made to provide loosely coupled interfaces,
 overridable services, and sane default implementations.
 
@@ -33,21 +36,18 @@ once we have finalized our Contributor License Agreement.
 
 ## Modules
 
-| Module                                                                                                                           | Summary                                                                                                                                     |
-| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| [nestjs-access-control](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-access-control 'nestjs-access-control') | Advanced access control guard for NestJS with optional per-request filtering.                                                               |
-| [nestjs-auth-github](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-auth-github 'nestjs-auth-github')          | Authenticate requests using GitHub oAuth2 sign-on.                                                                                          |
-| [nestjs-auth-jwt](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-auth-jwt 'nestjs-auth-jwt')                   | Authenticate requests using JWT tokens passed via the request (headers, cookies, body, query, etc).                                         |
-| [nestjs-auth-local](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-auth-local 'nestjs-auth-local')             | Authenticate requests using username/email and password against a local or remote data source.                                              |
-| [nestjs-auth-refresh](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-auth-refresh 'nestjs-auth-refresh')       | Authenticate requests using JWT refresh tokens passed via the request (headers, cookies, body, query, etc).                                 |
-| [nestjs-authentication](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-authentication 'nestjs-authentication') | Authenticate requests using one or more strategies (local, jwt, etc).                                                                       |
-| [nestjs-common](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-common 'nestjs-common')                         | The common module is a dependency of all Rockets modules.                                                                                   |
-| [nestjs-crud](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-crud 'nestjs-crud')                               | Extremely powerful CRUD module that is an extension/wrapper of the popular @nestjsx/crud module.                                            |
-| [nestjs-email](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-email 'nestjs-email')                            | Email deliver module that supports most popular transports, as well as template based email bodies using handlebars syntax.                 |
-| [nestjs-event](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-event 'nestjs-event')                            | Advanced class based event dispatch/listener module.                                                                                        |
-| [nestjs-jwt](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-jwt 'nestjs-jwt')                                  | A flexible JWT utilities module for signing and validating tokens.                                                                          |
-| [nestjs-logger](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-logger 'nestjs-logger')                         | Drop-in replacement for the core NestJS logger that provides additonal support for pushing log data to external log providers.              |
-| [nestjs-password](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-password 'nestjs-password')                   | A flexible Password utilities module that provides services for password strength, creation and storage.                                    |
-| [nestjs-swagger-ui](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-swagger-ui 'nestjs-swagger-ui')             | Expose your OpenApi spec on your API using the powerful Swagger UI interface.                                                               |
-| [nestjs-typeorm-ext](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-typeorm-ext 'nestjs-typeorm-ext')          | Extension of the NestJS TypeOrm module that allows your dynamic modules to accept drop-in replacements of custom entities and repositories. |
-| [nestjs-user](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-user 'nestjs-user')                               | A module for managing a basic User entity, including controller with full CRUD, DTOs, sample data factory and seeder.                       |
+| Module                                                                                                                                           | Summary                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [nestjs-core](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-core 'nestjs-core')                                               | Core framework module providing the app context system, DDD base classes, and shared utilities for Rockets modules.  |
+| [nestjs-repository](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-repository 'nestjs-repository')                             | Abstract repository adapter layer with transaction management, federation, and repository hook support.              |
+| [nestjs-repository-typeorm](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-repository-typeorm 'nestjs-repository-typeorm')     | TypeORM driver for nestjs-repository with entity base classes and where-clause translation.                          |
+| [nestjs-crud](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-crud 'nestjs-crud')                                               | Powerful CRUD module with full DDD/CQRS integration, configurable operations, and optional OpenAPI documentation.    |
+| [nestjs-cache](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-cache 'nestjs-cache')                                             | Cache management module using DDD/CQRS patterns with pluggable storage and HTTP CRUD gateway.                        |
+| [nestjs-otp](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-otp 'nestjs-otp')                                                   | One-time password module supporting multiple OTP categories with rate limiting and expiry management.                |
+| [nestjs-role](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-role 'nestjs-role')                                               | Role and role-assignment management module with DDD/CQRS and HTTP CRUD gateway.                                      |
+| [nestjs-password](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-password 'nestjs-password')                                   | Password utilities module providing strength validation, hashing, and storage via configurable policy services.      |
+| [nestjs-user](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-user 'nestjs-user')                                               | User entity management module with DDD/CQRS, password integration, and optional HTTP CRUD gateway.                   |
+| [nestjs-invitation](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-invitation 'nestjs-invitation')                             | Invitation workflow module handling token generation, delivery, acceptance, and revocation via DDD/CQRS.             |
+| [nestjs-federated](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-federated 'nestjs-federated')                                 | Federated (OAuth) identity linking module that maps external provider identities to local user accounts.             |
+| [nestjs-authentication](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-authentication 'nestjs-authentication')                 | Full-featured authentication module (JWT, local, refresh, recovery, verify, OAuth router) using DDD and CQRS.       |
+| [nestjs-access-control](https://github.com/conceptadev/rockets/tree/main/packages/nestjs-access-control 'nestjs-access-control')                 | Advanced access control guard with role-based grants and optional per-request response attribute filtering.          |

TODOs.md

@@ -0,0 +1,37 @@
+# Current scope
+  * `@concepta/nestjs-common` is deprecated — reverted to v7 line (`7.0.0-alpha.10`) and excluded from the v8 workspace. Its remaining v8-only symbols were merged into nestjs-core. Run `npm deprecate @concepta/nestjs-common@8.0.0-alpha.6` at publish time.
+  * Non-v8 packages are excluded from the Yarn workspace (see `workspaces` in root `package.json`) until they are migrated to the DDD pattern and NestJS 12: nestjs-email, nestjs-event, nestjs-logger, nestjs-auth-github, nestjs-org, nestjs-swagger-ui, nestjs-auth-google, nestjs-logger-coralogix, nestjs-logger-sentry, nestjs-file, nestjs-auth-apple, nestjs-report, nestjs-samples. Also removed `@concepta/nestjs-email` from devDependencies in nestjs-invitation and nestjs-authentication (only used in e2e tests — restore when nestjs-email is migrated).
+
+# Ranked backlog
+
+Single priority order across everything below (Fable review, 2026-08-30), ranked by
+(impact of leaving it undone) vs (effort × blast radius) — not grouped by the old
+Critical/High/Nice-To-Have labels, which were rough guesses and sometimes wrong. Effort
+tags: S/M/L. Completed items are removed from this list rather than marked done — see
+git history for what shipped.
+
+  1. **[S] Add an ESLint `import/extensions` rule** — belt-and-suspenders guard for the
+     `nodenext` `.js`-extension requirement on relative imports (`eslint-plugin-import`
+     is already a configured dependency, no conflicting rule exists). Not essential —
+     `tsc` itself already makes a missing extension a hard `TS2835` compile error. Do
+     opportunistically.
+
+  2. **[needs research first] Optional exports patterns are different across the
+      modules** — user confirmed no canonical pattern has been chosen yet; needs research
+      into the existing per-module variations before a target shape can even be proposed.
+      Not a quick win.
+
+  3. **Tutorial Topics** — Support of the minimum interface; Provider Overrides. Docs
+      work; sequence after the API stabilizes.
+
+  4. **When non-v8 packages are migrated to NestJS 12** — not actionable until triggered.
+      Full restore checklist per package:
+      1. Root `package.json` `workspaces` array — add dir (or revert to glob `packages/*`
+         when all are migrated)
+      2. Root `tsconfig.json` `references` — add `{ "path": "packages/<pkg>" }` (this
+         alone drives both the `tsc -b` ESM build and the type-check gate — the build is
+         solution-file-driven)
+      3. `vitest.config.ts` `test.include` — add `"packages/<pkg>/**/*.spec.ts"`
+      4. `vitest.config-e2e.ts` `test.include` — add `"packages/<pkg>/**/*.e2e-spec.ts"`
+      5. Restore `@concepta/nestjs-email` to nestjs-authentication and nestjs-invitation
+         devDependencies once nestjs-email is migrated.

eslint.config.mjs

@@ -5,6 +5,28 @@ import importPlugin from 'eslint-plugin-import';
 import tsdocPlugin from 'eslint-plugin-tsdoc';
 import jsdocPlugin from 'eslint-plugin-jsdoc';
 
+// The 13 packages migrated to v8 (nodenext, DDD) — same set as root
+// tsconfig.json's `references` and tsconfig.eslint.json's `include`. Only
+// these get type-aware linting; older packages predate the migration and
+// aren't part of the tsconfig project-reference graph the parser resolves
+// against, so linting them with a `project` would fail to find the file.
+const v8Packages = [
+  'nestjs-core',
+  'nestjs-repository',
+  'nestjs-repository-typeorm',
+  'nestjs-crud',
+  'nestjs-cache',
+  'nestjs-otp',
+  'nestjs-role',
+  'nestjs-password',
+  'nestjs-user',
+  'nestjs-invitation',
+  'nestjs-federated',
+  'nestjs-authentication',
+  'nestjs-access-control',
+];
+const v8Files = v8Packages.map((name) => `packages/${name}/src/**/*.ts`);
+
 export default tseslint.config(
   // Ignore patterns
   {
@@ -19,14 +41,13 @@ export default tseslint.config(
     ],
   },
 
-  // Extend @concepta/eslint-config/nest (filter out undefined configs)
-  ...conceptaConfig.filter(config => config !== undefined),
-
-  // JSDoc recommended config
-  jsdocPlugin.configs['flat/recommended-typescript'],
-
-  // Project-specific overrides
+  // Type-aware rules, scoped to the migrated v8 packages
   {
+    files: v8Files,
+    extends: [
+      ...conceptaConfig.filter((config) => config !== undefined),
+      jsdocPlugin.configs['flat/recommended-typescript'],
+    ],
     languageOptions: {
       parserOptions: {
         project: './tsconfig.eslint.json',
@@ -82,14 +103,16 @@ export default tseslint.config(
 
       // JSDoc/TSDoc rules
       'jsdoc/tag-lines': ['error', 'any', { startLines: 1 }],
+      // Disable nested param checking since TSDoc doesn't support dot notation
+      'jsdoc/check-param-names': ['warn', { checkDestructured: false }],
       'tsdoc/syntax': 'error',
-    },
-  },
 
-  // TypeScript files override
-  {
-    files: ['**/*.ts'],
-    rules: {
+      // ESM tree-shaking: enforce `import type` for type-only imports
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
+      ],
+
       'jsdoc/require-jsdoc': 'off',
       'jsdoc/require-param': 'off',
       'jsdoc/require-returns': 'off',
@@ -98,12 +121,35 @@ export default tseslint.config(
 
   // Spec and fixture files override
   {
-    files: ['**/*.spec.ts', '**/*.fixture.ts'],
+    files: v8Packages.flatMap((name) => [
+      `packages/${name}/src/**/*.spec.ts`,
+      `packages/${name}/src/**/*.fixture.ts`,
+    ]),
     rules: {
       '@darraghor/nestjs-typed/controllers-should-supply-api-tags': 'off',
       '@darraghor/nestjs-typed/api-method-should-specify-api-response': 'off',
       'jsdoc/tag-lines': 'off',
       'tsdoc/syntax': 'off',
     },
   },
+
+  // `causal-context` is framework-agnostic by design — forbid framework
+  // imports here so the boundary can't silently erode.
+  {
+    files: ['packages/nestjs-core/src/domain/events/causal-context/**/*.ts'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['@nestjs/*', '@nestjs/**', '@concepta/*', '@concepta/**'],
+              message:
+                'causal-context is framework-agnostic — framework imports belong in the adapter layer (domain/events/*.ts, infrastructure/context/*.ts), not here.',
+            },
+          ],
+        },
+      ],
+    },
+  },
 );