emilsoftware-utilities 2.0.0-dev.71 → 2.0.0-dev.73

package/docs/accessi-openapi-breaking-allowlist.json

@@ -0,0 +1 @@
+[]

package/docs/adr/0001-split-package.md

@@ -0,0 +1,79 @@
+# ADR 0001 — Split in pacchetti separati: contracts, client, resource-server, server
+
+- **Stato:** accettato
+- **Data:** 2026-10-30
+- **Issue:** #9
+- **Ambito:** packaging e rilascio di `emilsoftware-utilities`
+
+## Contesto
+
+Il package espone gia entry point separati (`accessi/server`, `accessi/resource-server`,
+`accessi/client` con gli scope `public`/`admin`/`service`, `accessi/contracts`, `accessi/openapi`,
+`accessi/console`, `accessi/ui`). Hanno però un unico `package.json`, un unico numero di versione e
+un unico ciclo di rilascio, mentre i consumer reali hanno esigenze diverse:
+
+- i frontend usano solo `contracts` e `client/public` e non devono scaricare Nest, Firebird o SMTP;
+- i backend fratelli usano `resource-server` e `client/service`;
+- solo il backend proprietario usa `server` (database, migrazioni, console).
+
+Oggi il tarball contiene tutto (~950 KB) e una modifica server-side obbliga un bump che i frontend
+devono comunque recepire. Lo split è però un cambio invasivo per i consumer e per la release.
+
+## Opzioni valutate
+
+| Opzione | Pro | Contro |
+| --- | --- | --- |
+| **A. Pacchetto singolo con entry point per scope (attuale)** | Zero migrazioni; un solo `npm ci`; types condivisi per costruzione; release unica e semplice; il tree-shaking elimina il codice non importato | Il tarball contiene dipendenze server anche per i frontend; versione unica per domini diversi |
+| **B. Monorepo npm workspaces con 4 pacchetti** | Versioning indipendente; dipendenze minime per pacchetto; build/publish selettivi | Richiede cambiare toolchain, CI e release; 4 tarball da pubblicare; gestione versioni incrociate (`contracts` → `client`); migrazione dei consumer |
+| **C. Pacchetti in repository separati** | Massima indipendenza | Frammentazione, PR incrociate, release coordinate manualmente, overhead alto per un team piccolo |
+
+## Decisione
+
+Si adotta **l'opzione A** nel breve periodo, rafforzata dagli entry point per scope introdotti
+nell'issue #7 e verificati dal test `npm run test:pack`.
+
+Motivazioni:
+
+1. **Nessuna regressione:** gli import esistenti (`emilsoftware-utilities`,
+   `.../accessi/client`, ...) restano identici; una migrazione forzata avrebbe costo alto e
+   beneficio non dimostrato.
+2. **Tipi condivisi per costruzione:** un solo set di modelli generati da OpenAPI evita divergenze
+   tra client e contracts, che con pacchetti separati andrebbero versionati insieme.
+3. **Bundle:** i consumer browser usano `accessi/client/public` e `accessi/contracts`; con
+   `sideEffects` limitato ai soli moduli con effetti, i bundler eliminano il resto.
+4. **Release riproducibile:** `npm ci && npm run build && npm run test:pack` produce e verifica lo
+   stesso tarball; semantic-release pubblica un solo artefatto.
+
+Lo split resta un'opzione futura, non un rifiuto: le soglie che lo giustificherebbero sono elencate
+sotto.
+
+## Quando rivalutare
+
+Riaprire la decisione (ADR successivo) se si verifica almeno una di queste condizioni:
+
+- i frontend richiedono un rilascio di `contracts`/`client` indipendente da `server`;
+- il peso delle dipendenze server nel bundle browser diventa un problema non risolvibile con il
+  tree-shaking (es. consumer senza bundler);
+- il team cresce al punto da avere cicli di rilascio separati per server e client;
+- si rende necessario pubblicare su registry diversi o con licenze diverse.
+
+## Piano di migrazione (se e quando)
+
+1. Introdurre i workspace (`npm workspaces`) mantenendo i path pubblici attuali come facade.
+2. Estrarre per primo `contracts` (zero dipendenze runtime), poi `client`, poi `resource-server`,
+   infine `server`.
+3. Ogni pacchetto facade re-esporta dal nuovo package, così `accessi/client`, `accessi/contracts`,
+   ecc. continuano a funzionare senza modifiche ai consumer.
+4. Aggiungere una test matrix che installa i tarball di tutti i pacchetti insieme e verifica i path
+   legacy.
+5. Deprecare i facade solo in una major successiva, con guida di migrazione.
+
+## Conseguenze
+
+- **Versioning:** unico, gestito da semantic-release sul branch `dev` → `main`.
+- **Compatibilita:** garantita dall'export map e dallo smoke test del tarball
+  (`scripts/pack-smoke-consumer.cjs`) che copre ogni subpath e gli scope client.
+- **Build/publish riproducibili:** build dichiarativa (`npm run build`), configurazione npm
+  isolata nello smoke test, nessun passaggio manuale oltre al merge.
+- **Debito accettato:** il tarball include dipendenze server anche per i consumer frontend; è un
+  costo noto e monitorato, non un bug.

package/integration-prompt.md

@@ -41,7 +41,10 @@ Se per ora Accessi e montato dentro Backend A, va bene: Backend A e il proprieta
 |---|---|
 | `emilsoftware-utilities/accessi/server` | Backend che ospita Accessi: `AccessiModule`, `initializeAccessiModule`, updater DB, migrazioni, console. |
 | `emilsoftware-utilities/accessi/resource-server` | Backend fratello: middleware Express, guard Nest, verifica JWT e introspection. |
-| `emilsoftware-utilities/accessi/client` | Client OpenAPI generato per chiamare Accessi Service. |
+| `emilsoftware-utilities/accessi/client` | Client OpenAPI completo, con configurazione globale o per istanza (`createAccessiClient`). |
+| `emilsoftware-utilities/accessi/client/public` | Solo API pubbliche (login, refresh, 2FA, reset password, ticket console): da preferire nei frontend. |
+| `emilsoftware-utilities/accessi/client/admin` | Solo API amministrative (utenti, ruoli, menu, filtri, provider federati, schema): console e tool admin. |
+| `emilsoftware-utilities/accessi/client/service` | Solo API service-to-service (service token e introspezione): backend fratelli e job. |
 | `emilsoftware-utilities/accessi/contracts` | Tipi, enum e helper puri browser-safe. |
 | `emilsoftware-utilities/accessi/contracts/dtos` | DTO Nest con `class-validator` e decoratori OpenAPI. Solo backend. |
 | `emilsoftware-utilities/accessi/openapi` | `setupOpenApi`, `mergeOpenApiDocuments`. |
@@ -628,6 +631,7 @@ I componenti sono frameworkless e ricevono i dati via proprieta; non fanno chiam
 - `accessi/contracts`: tipi/enum/helper puri, adatti anche al browser.
 - `accessi/contracts/dtos`: DTO Nest con decoratori; non usarli in bundle frontend leggeri.
 - `accessi/client`: tipi generati dall'OpenAPI e funzioni HTTP; e la fonte consigliata per frontend e backend fratelli.
+- `accessi/client/public` / `admin` / `service`: stessi tipi e funzioni, filtrati per scope. Il client pubblico non espone operazioni amministrative; usare `createAccessiPublicClient`, `createAccessiAdminClient` o `createAccessiServiceClient` per isolare base URL e token per istanza.
 
 Non usare i DTO server come contratto pubblico se il frontend non ha `class-validator`, `class-transformer` e `reflect-metadata`.
 
@@ -755,7 +759,7 @@ Checklist:
 
 ### Per un frontend
 
-> Usa `emilsoftware-utilities/accessi/client`: chiama `configureAccessiClient({ baseUrl, token })` dopo il login e `getToken` se il token cambia. Il login, il refresh, il 2FA e il reset password passano da Accessi Service. Verso i backend usa `Authorization: Bearer <access-token>`. Non incorporare il database o il server Accessi. Per la console usa `buildAccessiConsoleUrl` con il ticket monouso restituito da `POST /api/accessi/console/entry`; non mettere mai il JWT nell'URL. Per i componenti UI usa gli asset di `accessi/ui`. Gestisci gli errori 401 (`AUTH_TOKEN_INVALID`) portando l'utente al login e 403 (`AUTH_INSUFFICIENT_PERMISSIONS`) mostrando un messaggio di permessi insufficienti.
+> Usa `emilsoftware-utilities/accessi/client/public` nei frontend (mai il client admin) e `createAccessiClient`/`createAccessiPublicClient` se parli con piu Accessi Service o tenant: chiama `configureAccessiClient({ baseUrl, token })` dopo il login e `getToken` se il token cambia. Il login, il refresh, il 2FA e il reset password passano da Accessi Service. Verso i backend usa `Authorization: Bearer <access-token>`. Non incorporare il database o il server Accessi. Per la console usa `buildAccessiConsoleUrl` con il ticket monouso restituito da `POST /api/accessi/console/entry`; non mettere mai il JWT nell'URL. Per i componenti UI usa gli asset di `accessi/ui`. Gestisci gli errori 401 (`AUTH_TOKEN_INVALID`) portando l'utente al login e 403 (`AUTH_INSUFFICIENT_PERMISSIONS`) mostrando un messaggio di permessi insufficienti.
 
 ### Per un agente AI
 

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "emilsoftware-utilities",
-  "version": "2.0.0-dev.71",
+  "version": "2.0.0-dev.73",
   "description": "Utilities for EmilSoftware",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "accessi/*": [
+        "dist/accessi/*"
+      ]
+    }
+  },
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/firebird-compat.js",
+    "./dist/accessi-module/Console/console.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -60,6 +72,24 @@
       "import": "./dist/accessi/client/index.js",
       "default": "./dist/accessi/client/index.js"
     },
+    "./accessi/client/public": {
+      "types": "./dist/accessi/client/public/index.d.ts",
+      "require": "./dist/accessi/client/public/index.js",
+      "import": "./dist/accessi/client/public/index.js",
+      "default": "./dist/accessi/client/public/index.js"
+    },
+    "./accessi/client/admin": {
+      "types": "./dist/accessi/client/admin/index.d.ts",
+      "require": "./dist/accessi/client/admin/index.js",
+      "import": "./dist/accessi/client/admin/index.js",
+      "default": "./dist/accessi/client/admin/index.js"
+    },
+    "./accessi/client/service": {
+      "types": "./dist/accessi/client/service/index.d.ts",
+      "require": "./dist/accessi/client/service/index.js",
+      "import": "./dist/accessi/client/service/index.js",
+      "default": "./dist/accessi/client/service/index.js"
+    },
     "./accessi/openapi": {
       "types": "./dist/accessi/openapi/index.d.ts",
       "require": "./dist/accessi/openapi/index.js",
@@ -87,9 +117,11 @@
   },
   "scripts": {
     "release": "semantic-release",
-    "build": "npm run generate:accessi-openapi && npm run check:accessi-openapi && npm run generate:accessi-client && npm run generate:accessi-wiki && tsc && tsc -p tsconfig.console.json --noEmit && npm run build:accessi-console && npm run copy-views",
+    "build": "npm run generate:accessi-openapi && npm run check:accessi-openapi && npm run check:accessi-openapi-diff && npm run generate:accessi-client && npm run generate:accessi-wiki && tsc && tsc -p tsconfig.console.json --noEmit && npm run build:accessi-console && npm run copy-views",
     "check:accessi-openapi": "node scripts/check-accessi-openapi.cjs",
     "accessi:update-openapi-fingerprint": "node scripts/check-accessi-openapi.cjs --update",
+    "check:accessi-openapi-diff": "node scripts/openapi-semantic-diff.cjs",
+    "accessi:update-openapi-baseline": "node scripts/openapi-semantic-diff.cjs --update",
     "generate:accessi-openapi": "ts-node --transpile-only src/scripts/generateAccessiOpenApi.ts",
     "generate:accessi-client": "orval --config orval.config.ts",
     "generate:accessi-wiki": "ts-node --transpile-only src/scripts/generateAccessiWiki.ts",
@@ -106,8 +138,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "node scripts/lint.cjs",
     "test": "npm run typecheck && npm run lint && npm run test:unit",
-    "test:unit": "node --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs",
-    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=50 --test-coverage-functions=60 --test-coverage-branches=60 --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs",
+    "test:unit": "node --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs test/accessi-client-scopes.cjs test/openapi-semantic-diff.cjs",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=50 --test-coverage-functions=60 --test-coverage-branches=60 --test test/angular-components.cjs test/menus-catalog.mjs test/menu-scopes.cjs test/accessi-regressions.cjs test/password-reset-regressions.cjs test/two-factor.cjs test/accessi-schema.cjs test/utilities-regressions.cjs test/service-token-regressions.cjs test/accessi-email-config.cjs test/accessi-catalog-scripts.cjs test/openapi-config.cjs test/resource-server.cjs test/accessi-security-standards.cjs test/accessi-service.cjs test/refresh-token.cjs test/token-revocation.cjs test/accessi-client.cjs test/accessi-client-scopes.cjs test/openapi-semantic-diff.cjs",
     "test:accessi": "npm run test:unit",
     "test:all": "npm test && npm run test:integration && npm run test:integration:redis",
     "test:integration": "node test/integration/run-firebird.cjs 5",
@@ -116,6 +148,7 @@
     "test:integration:fb3": "node test/integration/run-firebird.cjs 3",
     "test:integration:fb25": "node test/integration/run-firebird.cjs 2.5",
     "test:accessi-console": "npm run build && node test/console-two-factor.cjs",
+    "test:pack": "node scripts/pack-smoke-test.cjs",
     "accessi:seed-admin": "node scripts/seed-accessi-admin.cjs",
     "accessi:console": "node scripts/run-accessi-console.cjs",
     "test:accessi-schema": "node --test test/accessi-schema.cjs",