KIS-TOiR/generation/update-strategy.md

Update Strategy

When the DSL changes, regeneration must preserve the default auth-enabled runtime rather than falling back to CRUD-only output.

domain/*.dsl remains the single required source of truth for regeneration. DTOs, API contracts, and React Admin resources must be re-derived from it on every run. Optional overrides in overrides/api-overrides.dsl and overrides/ui-overrides.dsl may be applied after derivation, but they must never duplicate or redefine the domain model. Regeneration must not resurrect or depend on supplemental DTO/API/UI DSL inputs. Every derived layer must be recalculated from domain/*.dsl plus optional non-duplicating overrides only.

Required regeneration sequence

1. Regenerate prisma/schema.prisma.
2. Run npx prisma migrate dev.
3. Regenerate NestJS entity modules, DTOs, controllers, and services.
4. Regenerate backend auth infrastructure:
   • AuthModule
   • guards
   • decorators
   • typed authenticated principal
   • typed config validation
   • CRUD RBAC decorations
5. Regenerate React Admin resources.
6. Regenerate frontend auth infrastructure:
   • src/config/env.ts
   • src/auth/keycloak.ts
   • src/auth/authProvider.ts
   • authenticated dataProvider.ts
   • App.tsx auth wiring
   • main.tsx init-before-render flow
7. Regenerate backend and frontend .env.example files so the auth env contract stays in sync.
8. Regenerate root/package .gitignore files so local-only artifacts remain out of git after regeneration.
9. Regenerate the root-level Keycloak realm import artifact. The repository default example filename is toir-realm.json, but the generator must allow a project-specific equivalent.
10. Re-run post-generation validation, including:

• gitignore coverage for dependency, build, env, coverage, and tsbuildinfo artifacts
• auth dependency checks
• fail-fast env checks
• token-claim based identity with no loadUserProfile() / /account dependency
• /health public check
• unauthenticated protected route -> 401
• insufficient role -> 403
• natural-key _sort=id mapping checks
• realm-template validation

Guardrails

• Regeneration must not strip auth back out of the project.
• Auth remains outside the DSL grammar, but it is part of the default generated runtime.
• If a DSL change affects entities or routes, the generator must re-apply the default CRUD RBAC rules automatically.
• If a DSL change affects runtime topology or naming, the generator must keep backend/frontend env examples, CORS rules, and the generated realm import artifact aligned with the generated app.