@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/audit/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: audit
+description: Audit du code genere contre les conventions SmartStack (i18n, React, structure, routing dynamique, RBAC, securite)
+group: DEBUG
+allowed-tools: [Read, Glob, Grep]
+---
+
+# Skill: Audit — Detect convention violations in generated code
+
+## Role
+
+Tu es un agent d'audit. Tu scans le code du worktree client et detectes les violations
+des conventions SmartStack listees dans `CLAUDE.md`. Tu **corriges** automatiquement
+les violations mécaniques. Pour les violations ambigues, tu les **rapportes** avec une
+suggestion.
+
+## Scope
+
+### Frontend (`web/{appcode}-web/src/`)
+
+**i18n (CRITICAL)** :
+- [ ] **Aucune chaine FR/EN hardcodee** dans JSX/TSX. Chaque string visible user DOIT passer par `t('key')`.
+  - Regex de detection : `<\w+[^>]*>[A-Za-zÀ-ÿ][^<>{]{3,}</`
+  - Ignorer : icons, className, testid, `key=`, commentaires
+- [ ] **Chaque cle `t('x.y.z')` DOIT exister dans les 4 locales** : `fr.json`, `en.json`, `it.json`, `de.json`
+- [ ] **Pas de cle de validation reutilisee hors de son contexte** (ex: `lastNameRequired` pour un champ qui n'est pas lastName)
+
+**Dynamic Routing (CRITICAL — SmartStack architecture)** :
+- [ ] **Aucune route statique `<Route path="...">`** hors de `DynamicRouter` ou des fichiers fournis par `@atlashub/smartstack`. SmartStack est DB-driven.
+  - Regex de detection : `<Route\s+path=` dans `src/` (hors `App.tsx` si minimal) → violation
+- [ ] **`useParams<{ id: string }>()`** est le SEUL pattern accepte. Rejeter `useParams<{ userId: string }>()`, `:ticketId`, etc.
+  - Regex de detection : `useParams<\{\s*(?!id\s*:)` ou `:[\w]+Id\b` dans JSX
+- [ ] **`componentRegistry.generated.ts` OU `*Registry.ts`** importe dans `src/main.tsx` AVANT `createRoot(...)`.
+  - Grep : `grep -c "Registry" src/main.tsx` → doit etre >= 1
+- [ ] **Chaque page scaffoldee** a un `PageRegistry.register('{app}.{module}.{section}[.{view}]', Lazy)` dans son fichier Registry.
+  - Grep croise : extraire les clés du menu API + les clés registrées → diff doit etre vide dans un sens au moins (tolere les keys registrées sans entrée menu)
+- [ ] **`PageRegistry.register` + `lazyWithRetry(() => import(...))`** (ou legacy `lazy(`) : chaque entree doit etre lazy. Rejeter les imports directs synchrones pour les pages. Nouveau code DOIT utiliser `lazyWithRetry` (export `@atlashub/smartstack`) pour absorber les chunk-load races.
+- [ ] **ComponentKey dot-separated** : `{app}.{module}.{section}[.{view}]` avec chaque segment en kebab-case commencant par une lettre.
+  - Regex : `PageRegistry\.register\('([^']+)'` → chaque clé matche `/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*){1,3}$/`
+- [ ] **Pas d'import de `@/router/smartstackRoutes` ni de `mergeRoutes`** (deprecated, supprimes).
+- [ ] **Pas d'import de `navRoutes.generated.ts`** (supprime, utiliser `@atlashub/smartstack` menu API).
+
+**React** :
+- [ ] `useCallback` ne doit pas contenir dans ses deps des valeurs qui forcent un re-fetch
+- [ ] `useEffect` cleanup explicite quand on abonne a un event / timer
+- [ ] Props typees (pas de `any`)
+- [ ] `useParams` retour null-checke (pas `id!` sans garde au-dessus)
+
+**Structure** :
+- [ ] Composants pages : pas d'import direct `services/`
+- [ ] Composants UI : pas d'import de `services/` ni `stores/`
+- [ ] Logique metier : uniquement dans `business/`
+
+### Backend (`src/{AppCode}.*`)
+
+**Clean Architecture** :
+- [ ] Clean Architecture 4-layers : Domain ← Application ← Infrastructure → Api
+- [ ] Domain : ZERO `using` de `Application`/`Infrastructure`/`Api`
+- [ ] Controllers retournent `ActionResult<T>` ou `ActionResult` — pas `IActionResult` nu
+- [ ] Services enregistres dans DI via `AddScoped`/`AddSingleton`
+- [ ] Migrations EF Core : 1 par feature, 3 fichiers (`.cs`, `.Designer.cs`, `ModelSnapshot.cs`)
+
+**Tables & schemas** :
+- [ ] Tables prefixees par domaine : `auth_`, `nav_`, `usr_`, `wkf_`, `cfg_`, `ai_`, `entra_`, `ref_`, `support_`, `loc_`
+- [ ] Schema `core` via `SchemaConstants.Core` (pas de `ToTable("X", "auth")`)
+- [ ] Raw SQL uniquement via `SqlObjectHelper` + fichiers `.sql` embarques
+
+**RBAC / Permissions (CRITICAL)** :
+- [ ] Permissions format `{app}.{module}.{section}.{action}` strict.
+  - Regex : `"([a-z][a-z0-9-]*)(\.[a-z][a-z0-9-]*){3}"` pour les string literals de permissions
+- [ ] Actions dans le set : `access`, `read`, `create`, `update`, `delete`, `export`, `import`, `approve`, `reject`, `assign`, `execute`
+- [ ] `[RequirePermission(...)]` present sur chaque endpoint non-public
+- [ ] Permissions declarees dans `{Module}Permissions.cs` (pas hardcodees dans controller)
+- [ ] NavRoute sur controller match le componentKey frontend pour le meme endpoint
+
+**Security — GUIDs** :
+- [ ] Aucun GUID predictable dans les seed / tests / code :
+  - Rejeter : `00000000-0000-0000-0000-000000000001`
+  - Rejeter : `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee` (repete)
+  - Rejeter : suites sequentielles `00000001`, `00000002`, ...
+- [ ] Les GUIDs doivent etre `Guid.NewGuid()` (une fois en `static readonly` pour idempotence, ou a l'execution)
+- [ ] Regex de detection de GUIDs fixes dans les `.cs` : `Guid\s*\(\s*"([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"\s*\)` puis test heuristique (pattern repete, sequentiel)
+
+**Seed idempotence** :
+- [ ] Chaque bloc de seed check l'existence avant insert : `AnyAsync(x => x.Code == "..." && x.ApplicationId == ...)`
+- [ ] `ComponentKey` renseigne sur toutes les entites navigation (application/module/section/resource)
+- [ ] Roles seedes avec filtre `Code + ApplicationId` (pas juste Code — collision entre apps)
+- [ ] Permissions seedes avec filtre `Path + Action + SectionCode` (pas juste Path)
+
+### Scaffold residuals
+
+- [ ] **Pas de fichiers `.bak`** laisses par le Studio (a supprimer)
+- [ ] **Pas de `.orig`, `.rej`, `.tmp`** dans le repo
+- [ ] **Pas de `TODO: implement`** dans les tests generes
+- [ ] **Pas de `Assert.True(true, "TODO")`** ou `expect(true).toBe(true)` dans les tests
+- [ ] **Pas de `/* map dto fields */`** dans les controllers
+- [ ] **Pas de `Guid.NewGuid()` a la volee dans les seeds** (doit etre en `static readonly` au niveau classe)
+
+## Plan d'execution
+
+1. **Collect** : `grep` les patterns de detection sur tout le code
+2. **Classify** : chaque violation → auto-fixable vs ambigue vs critical
+3. **Auto-fix** : pour les mecaniques (remplacer string → t('key'), ajouter cles aux 4 locales, supprimer .bak)
+4. **Report** : pour les ambigues/critical, suggestion + chemin du fichier + ligne
+5. **Verify** : relancer les tests / TSC / build si possible
+
+## Output attendu
+
+```
+━━━ Audit report ━━━
+
+✓ i18n: 0 hardcoded strings in JSX
+⚠ i18n: 3 missing keys in de.json (fixed: directory.form.relations.title, ...)
+✗ i18n: 1 validation key reused outside context
+  - components/directory/ContactRelationsTab.tsx:142
+    uses `lastNameRequired` for field `target`
+    → Suggestion: create `targetContactRequired` + update
+
+✓ Dynamic Routing: componentRegistry imported in main.tsx
+✗ Dynamic Routing: 2 pages missing PageRegistry.register()
+  - src/pages/hrm/employees/EmployeeListPage.tsx exists but no entry for 'hrm.employees' in any Registry.ts
+  - Route menu API returns componentKey 'hrm.employees.detail' but registry has no match
+✗ Dynamic Routing: 1 static route found
+  - src/App.tsx:42 — <Route path="/hrm/custom" element={<Custom />} />
+    → DynamicRouter handles all routes; move to seed data + PageRegistry
+
+✓ RBAC: 28/28 permissions match format app.module.section.action
+✗ RBAC: 1 hardcoded permission string outside PermissionsClass
+  - src/Api/Controllers/Hrm/EmployeesController.cs:87 — "hrm.employees.approve"
+    → Move to HrmPermissions.Employees.Approve
+
+✓ React: useCallback deps clean
+⚠ React: 1 useEffect without cleanup
+  - components/contacts/ContactListPage.tsx:88
+    subscribes to `window.studio.onEvent` without offEvent
+
+✓ Structure: layer violations 0
+✗ Scaffold: 2 .bak files
+  - src/main.tsx.bak (auto-deleted)
+  - components/App.tsx.bak (auto-deleted)
+✗ Scaffold: 4 test files with `Assert.True(true, "TODO")`
+  - Tests/Hrm/Api/EmployeesControllerTests.cs (9 occurrences)
+    → Regenerate via skills/development/testing
+
+✓ GUIDs: no predictable patterns detected
+
+[exit 0 — 3 fixes applied, 4 issues to review]
+```
+
+## Rules
+
+- **Ne jamais** modifier le CLAUDE.md du projet
+- **Toujours** verifier les 4 locales (fr/en/it/de) quand on ajoute une cle
+- **Batch** : un commit par categorie de fix (i18n, routing, react, scaffold, rbac)
+- **Escalade** : si plus de 10 issues dans une categorie, stopper et demander validation
+- **Routing dynamique** : toute violation est CRITIQUE car elle produit des pages blanches sans erreur console — NE PAS auto-fixer, toujours rapporter pour revue humaine

package/templates/skills/development/audit/routing-dynamic/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: audit-routing-dynamic
+description: Audit READ-ONLY des skills de developpement SmartStack pour verifier leur conformite a l'architecture de routing dynamique DB-driven (PageRegistry + componentRegistry + DynamicRouter). Produit un rapport textuel sans modifier aucun skill.
+group: AUDIT
+allowed-tools: [Read, Glob, Grep]
+---
+
+# Skill: Audit Routing Dynamique — Skills de developpement SmartStack
+
+## Role
+
+Tu es un agent d'audit **read-only**. Tu inspectes les `SKILL.md` du repertoire
+`development/` et tu evalues si chaque skill documente correctement l'architecture
+de **routing dynamique DB-driven** de SmartStack.
+
+**Contrainte absolue** : tu ne modifies AUCUN fichier skill. Tu produits un rapport
+textuel avec des recommandations que l'utilisateur appliquera manuellement.
+
+## Input
+
+```
+audit-routing-dynamic [skill-path | all]
+```
+
+- Sans argument ou `all` : audit complet des 10 skills cibles
+- Avec un chemin (ex: `frontend/component`) : audit cible
+
+## Architecture de reference (source de verite)
+
+SmartStack est un SDK NPM/NuGet. Toute page React doit etre enregistree via
+`PageRegistry.register(componentKey, LazyComponent)`. `DynamicRouter` resout les
+routes a partir du menu API DB (`GET /api/navigation/menu`).
+
+**5 elements mandatory** :
+1. `componentRegistry.generated.ts` — registre des pages (importe dans `main.tsx`)
+2. `PageRegistry` — API de registration + resolution
+3. `DynamicRouter` — moteur de routing unique (remplace routes statiques)
+4. `ProtectedRoute` — guard API-driven (permissions + features)
+5. `useRouteConfig` — hook qui transforme menu API → routes React
+
+**24 IMPLICIT_SUFFIXES** (auto-generes par DynamicRouter) :
+```
+.detail  .edit  .create  .new  .duplicate  .settings  .configure
+.permissions  .members  .history  .logs  .analytics  .preview
+.versions  .comments  .attachments  .audit  .export  .notifications
+.schedule  .workflow  .summary  .test  .runs  .import
+```
+
+**Conventions obligatoires** :
+- `componentKey` dot-separated : `{app}.{module}.{section}[.{resource}]`
+- `useParams<{ id: string }>()` — TOUJOURS `:id`, jamais `:userId`/`:ticketId`
+- Lazy imports : `lazyWithRetry(() => import('./MyPage').then(m => ({ default: m.MyPage })))` (re-exporté depuis `@atlashub/smartstack` — wraps `React.lazy` avec retry exponentiel sur ChunkLoadError transitoires)
+- Seed `ComponentKey` backend = cle PageRegistry frontend
+- **Permission matching via `hasRouteAccess(permission, routeKey)`** — JAMAIS de bypass `hasFullAccess` ou de comparaison string brute. Regles :
+  - `*` matche tout (super-admin uniquement)
+  - `app.*` matche tout `app.module.action`
+  - `app.module.read` implique acces a `app.module` (action `read` est l'acces de base)
+  - Comparaison exacte sinon
+- **`IsOpen` (DB column `core.nav_Applications.IsOpen`)** est propriete domaine **uniquement sur Application** (PAS sur Module/Section/Resource). Bypasse la verification permission/feature au niveau Application (ex: `myspace.*` toujours accessible). Audit doit verifier que le seed positionne `IsOpen` au bon niveau.
+- **Menu API 4 niveaux DTO** : `ApplicationMenuDto > ModuleMenuDto > SectionMenuDto > ResourceMenuDto`. Chaque niveau porte son propre `ComponentKey` + `PermissionPath` (calcules au runtime depuis le chemin hierarchique). `IsOpen` n'existe que sur `ApplicationMenuDto`. `RequiredFeature` n'existe que sur `Application` et `Module` (2 niveaux, depuis `LicenseFeatureMapping`).
+- **`OUTLET_SECTIONS` config** (dans `DynamicRouter`) declare les sections qui rendent leurs sous-pages via React Router `<Outlet>` (tabs). Composants resolus depuis `PageRegistry` (pas hardcode). Anti-pattern : routes Outlet ecrites en dur dans le router.
+
+**Fichiers de reference dans SmartStack.app** (source de verite code) :
+- `web/smartstack-web/src/extensions/PageRegistry.tsx`
+- `web/smartstack-web/src/router/DynamicRouter.tsx` (IMPLICIT_SUFFIXES L86-119)
+- `web/smartstack-web/src/generated/componentRegistry.generated.ts`
+- `web/smartstack-web/src/hooks/useRouteConfig.ts`
+- `web/smartstack-web/src/components/routing/ProtectedRoute.tsx`
+
+## Skills cibles (10)
+
+| Priorite | Skill | Categorie |
+|----------|-------|-----------|
+| P0 | `frontend/component` | Pages React |
+| P0 | `frontend/structure` | Arborescence + main.tsx |
+| P0 | `audit` | Audit generaliste existant |
+| P1 | `backend/seed-data` | Seed Navigation |
+| P1 | `backend/controller` | NavRoute attribute |
+| P1 | `frontend/extension-config` | Slots |
+| P2 | `frontend/routes` | PageRegistry scaffolding |
+| P2 | `frontend/api-client` | getRoute() + React Query |
+| P2 | `testing` | Tests par layer |
+| P2 | `backend/structure` | Clean Architecture |
+
+## Criteres d'audit (10 regles A-J)
+
+Pour chaque skill, appliquer les criteres. `N/A` si hors scope du skill.
+
+| ID | Regle | Applicable a | Pattern de detection |
+|----|-------|--------------|----------------------|
+| A | Mentionne `PageRegistry.register()` | frontend/* | grep `PageRegistry.register` OR `componentRegistry.generated` |
+| B | Utilise `lazyWithRetry(() => import(...))` (ou legacy `lazy(`) | frontend/component, frontend/routes | grep `(lazy|lazyWithRetry)\(` avec `import(` |
+| C | Documente au moins 3 IMPLICIT_SUFFIXES | frontend/routes, frontend/component | grep `.detail`, `.edit`, `.create` |
+| D | Enforce `useParams<{ id: string }>()` | frontend/component | grep `useParams<{ id:` — anti-pattern si `userId`/`ticketId` |
+| E | Documente format ComponentKey dot-separated | frontend/routes, frontend/component, backend/seed-data | grep `componentKey.*\.` avec exemple `app.module` |
+| F | Aligne ComponentKey backend -> frontend | backend/seed-data | grep `ComponentKey` dans exemple de seed |
+| G | Mentionne `[NavRoute]` attribute | backend/controller | grep `NavRoute` |
+| H | Interdit routes statiques `<Route path=...>` | frontend/* | absence de `<Route path=` hors DynamicRouter |
+| I | _(removed — MCP validate_frontend_routes was deleted in v5)_ | — | — |
+| J | Documente integration NPM client (wiring `main.tsx`) | frontend/structure | grep `main.tsx` + `componentRegistry` |
+
+## Plan d'execution
+
+1. **Inventory** — Globber les `SKILL.md` cibles :
+   ```
+   templates/skills/development/**/SKILL.md
+   ```
+   Filtrer les 10 cibles ci-dessus.
+
+2. **Evaluate** — Pour chaque skill :
+   - `Read` le contenu complet
+   - Pour chaque critere A-J applicable : `Grep` le pattern
+   - Noter `OK` / `PARTIAL` / `MISSING` / `N/A` avec numero de ligne
+
+3. **Score** — `X/Y` par skill (Y = nombre de criteres applicables)
+
+4. **Report** — Afficher le rapport au format defini (section Output)
+
+**Regles strictes** :
+- JAMAIS d'`Edit` ou `Write` sur les fichiers skills
+- JAMAIS de modification directe des fichiers skills audites
+- Tools autorises : `Read`, `Grep`, `Glob`, `Bash` (ls uniquement)
+- Si l'utilisateur demande explicitement d'ecrire le rapport sur disque :
+  creer UN SEUL fichier `audit-routing-dynamic-report.md` dans le CWD (jamais dans le repertoire skills)
+
+## Output attendu
+
+```
+━━━ Audit Routing Dynamique — Rapport ━━━
+Date: 2026-04-19
+Skills audites: 10
+Conformite globale: 48/100
+
+## Top 3 gaps transversaux
+1. A. PageRegistry : 8/10 skills ne mentionnent jamais PageRegistry.register()
+2. J. Integration NPM : 0/10 skills documentent le wiring main.tsx
+3. C. IMPLICIT_SUFFIXES : 1/10 skill les documente
+
+## Top 3 skills critiques (P0)
+- frontend/component (6/10)
+- frontend/structure (4/10)
+- audit (2/10)
+
+## Detail par skill
+
+### frontend/component — 6/10
+Ce qu'il genere: Pages React (List/Detail/Form), i18n, Slot/Fill
+Criteres:
+  A. PageRegistry        MISSING   (0 occurrence dans SKILL.md)
+  B. Lazy imports        MISSING   (template utilise import direct)
+  C. IMPLICIT_SUFFIXES   MISSING
+  D. useParams id        PARTIAL   (L112 mentionne "key rules", pas :id explicite)
+  E. ComponentKey format MISSING
+  H. Routes statiques    OK        (aucun <Route> dans SKILL.md)
+  I. _(removed in v5)_         N/A
+Recommandations (a appliquer manuellement) :
+  1. Ajouter section "PageRegistry Registration" apres L24 avec exemple
+     lazyWithRetry() + register('app.module.section', Lazy)
+  2. Ajouter regle "TOUJOURS useParams<{ id: string }>()" — jamais :userId
+  3. Mentionner IMPLICIT_SUFFIXES (.detail/.edit/.create) avec liste complete
+
+### frontend/structure — 4/10
+[...meme format...]
+
+[... etc pour les 10 skills ...]
+
+━━━ Fin du rapport ━━━
+```
+
+## Format detaille d'une entree par skill
+
+Pour chaque skill, utiliser cette structure :
+
+```
+### {skill-path} — {X}/{Y}
+Ce qu'il genere : {1 phrase}
+Criteres :
+  A. {nom critere}       {OK|PARTIAL|MISSING|N/A}   [Line NN si applicable]
+  B. ...
+Recommandations (a appliquer manuellement) :
+  1. {action concrete + ligne a modifier + wording exact suggere}
+  2. ...
+  3. ...
+```
+
+Maximum 3 recommandations par skill (les plus impactantes).
+
+## Regles
+
+- **READ-ONLY absolu** : aucun Edit, aucun Write sur les skills. Violation = bug du skill.
+- **Citer numeros de ligne** quand possible (aide l'utilisateur a appliquer la recommandation)
+- **Pas de jugement de valeur** sur le code genere (on audite la documentation du skill, pas l'execution)
+- **N/A explicite** quand un critere ne s'applique pas (ex: G pour un skill frontend)
+- **Score transparent** : afficher le denominateur (X/Y) pour que l'utilisateur voie combien de criteres etaient applicables
+- **Pas de follow-up auto** : ce skill est read-only, ne pas modifier les fichiers audites
+- **Escalade** : si l'utilisateur demande des corrections apres l'audit, rediriger vers `/apex` ou creation manuelle — ce skill ne corrige pas