Merge pull request #20 from Arcoders/LASAGNA-090706/soft

Lasagna 090706/soft

Author: Arcoders

.github/workflows/ci.yml

@@ -2,11 +2,8 @@ name: CI
 
 on:
   push:
-    # TEMP (plugin-platform A→S→B→C branch review): run the full CI matrix on the
-    # crypto-satellite branch so the whole plugin-platform stack is exercised on the
-    # branch before merging. REVERT this extra branch entry (crypto-satellite) before
-    # merging to master. (The ws-ai-3 entry is a stale leftover from an earlier review.)
-    branches: [master, main, LASAGNA-020726/ws-ai-3-vector-store, LASAGNA-040726/crypto-satellite]
+    # TEMP: run CI on this branch while it bakes. Revert before merging.
+    branches: [master, main, LASAGNA-090706/soft]
   pull_request:
     branches: [master, main]
 
@@ -56,8 +53,8 @@ jobs:
       - name: Build (core)
         run: npm run build
 
-      - name: Build satellite packages (sso, billing, admin, backup, websockets, reporting, ai, crypto)
-        run: npm run build:sso && npm run build:billing && npm run build:admin && npm run build:backup && npm run build:websockets && npm run build:reporting && npm run build:ai && npm run build:crypto
+      - name: Build satellite packages (sso, billing, admin, backup, websockets, reporting, ai)
+        run: npm run build:sso && npm run build:billing && npm run build:admin && npm run build:backup && npm run build:websockets && npm run build:reporting && npm run build:ai
 
       # The dev-only satellite-test-kit is imported by core's bin/test.integration.ts
       # (and each satellite's), which core's tsconfig typechecks. Build it before the
@@ -204,7 +201,6 @@ jobs:
           npm run test:coverage --workspace @adonisjs-lasagna/websockets
           npm run test:coverage --workspace @adonisjs-lasagna/reporting
           npm run test:coverage --workspace @adonisjs-lasagna/ai
-          npm run test:coverage --workspace @adonisjs-lasagna/crypto
 
       # Satellite ABI compatibility (B5): the reference third-party satellite
       # is built + tested against the freshly-built core above. Its typecheck
@@ -216,6 +212,16 @@ jobs:
           npm run build:template
           npm run test --workspace @adonisjs-lasagna/satellite-template
 
+      # The starter scaffolder encodes the golden install path as data. Its unit
+      # suite pins that plan (peers configured before core, config/database.ts
+      # written after) and the two install defects the generated config closes.
+      # The suite never spawns a process, so it needs no database and no network;
+      # the win32 npm invocation is covered by injecting the platform instead.
+      - name: Build + test the starter scaffolder
+        run: |
+          npm run build:starter
+          npm run test --workspace create-lasagna-saas
+
       # The shared integration harness underwrites core + every satellite, so it
       # carries its own unit suite (the pure exit-code/glob/spec-import logic +
       # the boot-safety metatest) behind a self-contained coverage floor
@@ -296,14 +302,6 @@ jobs:
           path: coverage/.v8/ai-unit
           if-no-files-found: warn
 
-      - name: Upload raw satellite unit coverage (V8) — crypto
-        if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: c8-raw-crypto-unit
-          path: coverage/.v8/crypto-unit
-          if-no-files-found: warn
-
       # Full report (unused exports / orphaned files / deps) stays informational.
       - name: Knip (unused-code report)
         run: npm run knip
@@ -332,7 +330,7 @@ jobs:
       - name: Package contracts (publint + types resolution)
         run: |
           set -e
-          for pkg in core sso billing admin backup websockets reporting ai crypto; do
+          for pkg in core sso billing admin backup websockets reporting ai; do
             echo "== @adonisjs-lasagna/$pkg =="
             ( cd "packages/$pkg" \
               && npx -y publint@0.3.21 \
@@ -477,11 +475,11 @@ jobs:
       # with `default_transaction_read_only = on` so a write is denied by Postgres.
       PLUGIN_RO_DB_USER: plugin_ro
       PLUGIN_RO_DB_PASSWORD: plugin_ro
-      # This job HAS a real Postgres service, so the crypto/AI real-PG proofs are
+      # This job HAS a real Postgres service, so the AI real-PG proofs are
       # mandatory here: they must EXECUTE, never self-skip. The satellite real-PG
       # helpers read this flag and turn a would-be self-skip (PG unreachable, role
       # lacks CREATEDB) into a hard failure — the fail-loud twin of RLS_DB_USER,
-      # so a broken/hardened runner can't ship the crypto crown-jewel proofs green.
+      # so a broken/hardened runner can't ship those proofs green.
       REQUIRE_REAL_PG: '1'
 
     steps:
@@ -655,14 +653,6 @@ jobs:
       - name: Test (satellite integration) + coverage — ai
         run: npm run test:integration:coverage --workspace @adonisjs-lasagna/ai
 
-      # crypto's integration tier: the wrapped-DEK store + shred + WORM ledger + the
-      # @encrypted/@searchable decorators against real Postgres via the kit, across
-      # every placement (schema-pg, a real second database for database-pg, and the
-      # shared rowscope table with its RLS stub). The database-pg + rowscope specs
-      # self-skip if the CI role cannot CREATEDB / set the RLS GUC.
-      - name: Test (satellite integration) + coverage — crypto
-        run: npm run test:integration:coverage --workspace @adonisjs-lasagna/crypto
-
       # Consumer canary: boot the shared harness from a fresh satellite (the
       # reference template) against core's fixture. A kit change that breaks a
       # real consumer fails here on an isolated, fast signal instead of buried in
@@ -753,18 +743,6 @@ jobs:
           path: coverage/.v8/ai-integration
           if-no-files-found: warn
 
-      # crypto integration V8 (written by test:integration:coverage to
-      # coverage/.v8/crypto-integration in the "— crypto" step above). The
-      # coverage-report job merges this with crypto's unit V8 so
-      # check-satellite-coverage.mjs gates a real per-satellite MERGED number.
-      - name: Upload raw satellite integration coverage (V8) — crypto
-        if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: c8-raw-crypto-integration
-          path: coverage/.v8/crypto-integration
-          if-no-files-found: warn
-
   test-e2e-demo:
     name: E2E (demo app)
     runs-on: ubuntu-latest
@@ -830,7 +808,10 @@ jobs:
       # exempt loopback from the SSRF guard for the demo run. Off in production,
       # and even when on it only allows loopback (private/metadata stay blocked).
       WEBHOOKS_ALLOW_LOOPBACK_TARGETS: 'true'
-      DEMO_ADMIN_TOKEN: demo-admin-token-change-me
+      # The auth_realms e2e logs in as the hook-seeded per-tenant demo user,
+      # so tenant migrations must seed it here. Default-off everywhere else;
+      # the deploy smoke stack deliberately leaves it unset to prove that.
+      DEMO_SEED_TENANT_USERS: 'true'
       MAILCATCHER_HOST: 127.0.0.1
       MAILCATCHER_PORT: 1025
       MAIL_FROM_ADDRESS: demo@example.test
@@ -961,7 +942,6 @@ jobs:
       CACHE_REDIS_PORT: 56379
       CACHE_REDIS_DB: 2
       BACKUP_STORAGE_PATH: ./storage/backups
-      DEMO_ADMIN_TOKEN: demo-admin-token-change-me
       MAILCATCHER_HOST: 127.0.0.1
       MAILCATCHER_PORT: 1025
       MAIL_FROM_ADDRESS: demo@example.test
@@ -1024,6 +1004,69 @@ jobs:
           path: coverage/.v8/websockets-integration
           if-no-files-found: warn
 
+  # The only job that installs this package the way a stranger does: from the
+  # packed tarball, into an app scaffolded by `npm init adonisjs`. Every other
+  # gate resolves @adonisjs-lasagna/saas-tenancy through the workspace symlink,
+  # which hides a whole class of defect — a configure hook the root entry never
+  # exports, a stub that ships but cannot render, a stub calling an Application
+  # method that does not exist, a missing migration. All four shipped at once,
+  # with the other 46 gates green.
+  clean-install:
+    name: Clean install (packed tarball into a fresh app)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+      redis:
+        image: redis:7.0.5-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --include=optional
+
+      # The generated app runs `npm install` from the public registry, so this job
+      # needs network. It builds core, packs it, and drives the golden path from
+      # `configure` to a provisioned tenant schema.
+      - name: Clean-install smoke
+        env:
+          PG_HOST: 127.0.0.1
+          PG_PORT: 5432
+          PG_USER: postgres
+          PG_PASSWORD: postgres
+          PG_DATABASE: lasagna_clean_install
+          REDIS_HOST: 127.0.0.1
+          REDIS_PORT: 6379
+        run: bash scripts/clean-install-smoke.sh
+
   deploy-validate:
     name: Deploy assets (static validation)
     runs-on: ubuntu-latest
@@ -1180,12 +1223,6 @@ jobs:
           name: c8-raw-ai-integration
           path: coverage/.v8/all
 
-      - name: Download raw satellite integration coverage (V8) — crypto
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          name: c8-raw-crypto-integration
-          path: coverage/.v8/all
-
       # websockets integration V8 is produced by the test-e2e-websockets job (a
       # different job than test-integration above), now run under c8. This is why
       # test-e2e-websockets is in this job's needs:.
@@ -1241,12 +1278,6 @@ jobs:
           name: c8-raw-ai-unit
           path: coverage/.v8/all
 
-      - name: Download raw satellite unit coverage (V8) — crypto
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          name: c8-raw-crypto-unit
-          path: coverage/.v8/all
-
       - name: Aggregate coverage report (unit + integration, remapped to src)
         run: npm run coverage:report
 

.github/workflows/publish.yml

@@ -73,13 +73,15 @@ jobs:
             fi
           }
 
-          # Core first so satellites resolve a published peer.
+          # Core first so satellites resolve a published peer. Only the six
+          # publishable workspaces belong here: `admin` and `websockets` are
+          # `private: true` (npm refuses them with EPRIVATE, which under
+          # `set -euo pipefail` would abort this script mid-release), and the
+          # crypto satellite was removed from the repo. `check-publish-coverage.mjs`
+          # asserts every non-private package appears below.
           publish_pkg "packages/core"
           publish_pkg "packages/sso"
           publish_pkg "packages/billing"
-          publish_pkg "packages/admin"
           publish_pkg "packages/backup"
           publish_pkg "packages/reporting"
-          publish_pkg "packages/websockets"
           publish_pkg "packages/ai"
-          publish_pkg "packages/crypto"

.github/workflows/release.yml

@@ -31,9 +31,19 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
-    # `types: [completed]` fires on failure and cancellation too; this guard is
-    # the actual gate.
-    if: github.event.workflow_run.conclusion == 'success'
+    # `types: [completed]` fires on failure and cancellation too; the conclusion
+    # check is the CI gate.
+    #
+    # `PUBLISH_ENABLED` is the human gate, and it is OFF until the repository
+    # variable is set to 'true' (Settings → Secrets and variables → Actions →
+    # Variables). Without it, this workflow would publish to npm the moment CI
+    # goes green on master: with no changeset files pending, changesets/action
+    # skips the Version PR and runs the publish command straight away, shipping
+    # whatever versions the package.json files happen to carry. npm versions are
+    # immutable, so that is a one-way door taken by a merge, not by a decision.
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      vars.PUBLISH_ENABLED == 'true'
     steps:
       # Check out the exact commit CI validated, not the branch tip — if master
       # moved while CI ran, the tip's suite hasn't passed yet and its publish

.gitignore

@@ -18,7 +18,13 @@ benchmarks/results/
 
 # Temp dir for the docs code-fence import gate (scripts/check-docs-code.mjs)
 .docs-code-tmp/
-docs/.vitepress/
+
+# VitePress generated output only. The theme source under docs/.vitepress/theme/
+# IS tracked; a blanket `docs/.vitepress/` rule silently drops any NEW theme file
+# (existing ones survive only because git ignores untracked files, not tracked ones).
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+docs/.vitepress/*.timestamp-*.mjs
 
 # doc-coverage: the graph is generated, never committed (RFC §5). The cache is
 # keyed by a src+docs content hash and is always safe to delete.

README.md

@@ -16,7 +16,7 @@
 
 📖 **[Full documentation →](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/)** · [Quickstart](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/start/quickstart) · [Why Lasagna](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/start/why) · [Comparison vs stancl](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/comparison) · [Release notes](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/release-notes)
 
-> **Stability: release candidate.** The isolation core is feature complete and green in CI against real Postgres and Redis, but the `stable` label is withheld until an independent security review and production mileage close. The satellite **packages** (admin, SSO, billing, backup, websockets, reporting) are **release candidate** too; the opt-in in-core features (quotas, webhooks, metrics, audit logs, branding, feature flags, impersonation) are **experimental**. Full breakdown and the 1.x semver promise in the [stability matrix](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/stability).
+> **Stability: release candidate.** The isolation core is feature complete and green in CI against real Postgres and Redis, but the `stable` label and the `1.0.0` version are both withheld until an independent security review and production mileage close. It ships `0.3.0`, so semver promises nothing across a minor. The satellite **packages** (SSO, billing, backup, reporting, AI) ship `0.1.0` and are **experimental**, as are the opt-in in-core features (quotas, webhooks, metrics, audit logs, branding, feature flags, impersonation). Full breakdown in the [stability matrix](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/stability).
 
 I built this because the AdonisJS ecosystem deserved a proper multi
 tenancy foundation, and because every SaaS I touched eventually outgrew

benchmarks/fixture/app/models/tenant.ts

@@ -7,8 +7,8 @@ import type { TenantStatus } from '@adonisjs-lasagna/saas-tenancy/types'
 /**
  * Lean tenant registry model. The bench provisions tenant storage directly
  * (see src/harness/provision.ts), so this model carries only what the
- * repository, the tenant guard, and `request.tenant()` read — no install /
- * migrate / connection plumbing.
+ * repository, the tenant guard, and `request.tenant()` read, with none of the
+ * install, migrate, or connection plumbing.
  */
 export default class Tenant extends BackofficeBaseModel {
   @column({ isPrimary: true })

benchmarks/fixture/config/multitenancy.ts

@@ -35,7 +35,7 @@ export default {
   // the isolation tier swaps the id per request to prove cross-tenant queries are
   // contained. There is no authenticated principal in a benchmark, so the
   // membership gate is intentionally absent. Acknowledge it so the production-mode
-  // run boots (the WS-3 resolution-safety check hard-fails an unacknowledged
+  // run boots (the resolution-safety check hard-fails an unacknowledged
   // client-controlled strategy in production).
   acknowledgeNoMembershipGate: true,
   tenantHeaderKey: env.get('TENANT_HEADER_KEY'),
@@ -46,7 +46,7 @@ export default {
   isolation: {
     driver,
     // The template connection that schema-pg/database-pg clone per tenant.
-    // rowscope-pg ignores this — it shares `centralConnectionName` ('public')
+    // rowscope-pg ignores this: it shares `centralConnectionName` ('public')
     // since there is no per-tenant connection. `tenant` points at `public`, so
     // the same physical DB backs every driver under BENCH_DRIVER.
     templateConnectionName: 'tenant',
@@ -73,7 +73,7 @@ export default {
   },
 
   // The breaker fires on every guarded request, so the config must carry the
-  // block — values mirror examples/api (volumeThreshold high enough not to trip
+  // block. Values mirror examples/api (volumeThreshold high enough not to trip
   // under a healthy load run).
   circuitBreaker: {
     threshold: 50,

benchmarks/fixture/start/routes.ts

@@ -53,14 +53,14 @@ router
   .prefix('tenant')
   .use(middleware.tenantGuard())
 
-// Same read, guard removed — diff vs /tenant/notes prices the guard middleware.
+// Same read, guard removed. The diff vs /tenant/notes prices the guard middleware.
 router.get('/noguard/notes', async ({ request, response }) => {
   const tenant = await request.tenant()
   const notes = await readRecentNotes(tenant)
   return response.ok({ tenantId: tenant.id, notes })
 })
 
-// Same read, guard + rate-limit — diff vs /tenant/notes prices the rate-limit
+// Same read, guard + rate-limit. The diff vs /tenant/notes prices the rate-limit
 // Redis pipeline. Generous limit so the limiter never trips during a load run.
 router
   .get('/ratelimited/notes', async ({ request, response }) => {

benchmarks/src/db/index.ts

@@ -1,5 +1,5 @@
 /**
- * Tier 2 — DB per-driver query latency + connection churn. Boots the bench
+ * Tier 2: DB per-driver query latency + connection churn. Boots the bench
  * fixture headless (the drivers need a booted app), runs against real Postgres
  * for the driver selected by BENCH_DRIVER.
  *

benchmarks/src/harness/baseline.ts

@@ -1,6 +1,6 @@
 /**
- * `npm run bench:check` — compare the newest results against a committed
- * baseline and print a regression verdict.
+ * `npm run bench:check` compares the newest results against a committed
+ * baseline and prints a regression verdict.
  *
  *   --baseline=ci-ubuntu   (default; the gate baseline)
  *   --baseline=1.0.0       (the docs baseline; for a self-compare sanity check)
@@ -47,7 +47,7 @@ const latest = latestBySuiteDriver()
 
 // Correctness gate (always hard, independent of the throughput tolerance and of
 // BENCH_GATE_ENFORCE): any result whose meta carries a `*Check` field set to
-// 'FAIL' is a correctness regression — a cross-tenant leak, a broken fail
+// 'FAIL' is a correctness regression: a cross-tenant leak, a broken fail
 // policy, an unstable soak. These must never be merged, noisy runner or not.
 const correctnessFailures: string[] = []
 for (const [key, file] of latest) {