@atlashub/smartstack-cli 4.34.0 → 4.36.0

package/templates/skills/audit-route/steps/step-02-conformity.md

@@ -0,0 +1,193 @@
+---
+name: step-02-conformity
+description: Evaluate conformity of each element and scan for anti-patterns
+next_step: steps/step-03-report.md
+---
+
+# Step 2: Conformity Analysis
+
+## MANDATORY EXECUTION RULES:
+- Load `references/routing-pattern.md` FIRST for the reference pattern
+- Read each element's FULL source code before evaluating
+- NEVER judge developers — analyze code objectively
+- Distinguish errors from conscious architectural choices
+- If a deviation has a valid technical justification, say so explicitly
+- Cross-reference manual findings with MCP results from `{mcp_results}` (step-00)
+
+## YOUR TASK:
+For each of the 5 elements found in Step 1, evaluate conformity against the reference pattern. Then scan the entire codebase for anti-patterns.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### Phase A: Conformity Evaluation (per element)
+
+For each of the 5 elements, read the full source file and evaluate:
+
+#### Rating Scale:
+| Rating | Symbol | Meaning |
+|--------|--------|---------|
+| Conforme | ✅ | Implementation matches the pattern |
+| Partiellement conforme | ⚠️ | Intent is correct but execution deviates |
+| Non conforme | ❌ | Implementation contradicts the pattern |
+| Absent | 🔴 | Element does not exist |
+
+#### For each element, record:
+
+**If ✅ Conforme:**
+- Brief confirmation of what makes it compliant
+- Any notable strengths or best practices observed
+
+**If ⚠️ Partiellement conforme, ❌ Non conforme, or 🔴 Absent — answer ALL 5 questions:**
+
+**a) Qu'est-ce qui a ete fait a la place ?**
+Describe precisely the alternative implementation found in the code.
+Include specific file paths and line numbers.
+
+**b) Pourquoi est-ce que ca ne respecte pas le pattern ?**
+Technical explanation of the deviation:
+- Tight coupling (front depends on route structure)
+- Static routes (hardcoded in JSX instead of API-driven)
+- Missing guard (no permission check at route level)
+- Non-lazy imports (eager loading bloats bundle)
+- Incomplete implementation (partial API usage)
+
+**c) Pourquoi le developpeur a probablement fait ca ?**
+Formulate a benevolent hypothesis:
+- Pattern unknown at development time?
+- Technical constraint (bundler, framework limitation)?
+- Deliberate MVP simplification?
+- Misunderstanding of front/back responsibility separation?
+- Legacy architecture inheritance?
+- Confusion between static protected routes and dynamic routes?
+- Migration in progress (intentional intermediate state)?
+
+**d) Quelle est la consequence concrete de cette deviation ?**
+Concrete impact:
+- DB/front coupling (routes changes require front deploy)
+- Potential security flaw (permission bypass)
+- Rigidity (adding a route requires code change + deploy)
+- Technical debt (maintenance burden)
+- Bundle size impact (non-lazy loading)
+- User experience (flash of wrong page, etc.)
+
+**e) Comment migrer vers le pattern cible ?**
+Concrete migration steps considering existing code:
+- DO NOT propose a complete rewrite if a targeted refactor suffices
+- Number the steps in priority order
+- Estimate scope: small (1-2 files), medium (3-5 files), large (6+ files)
+- Note any prerequisites or dependencies between migration steps
+
+---
+
+### Phase B: Anti-Pattern Scan
+
+Scan the ENTIRE codebase (not just routing files) for these anti-patterns:
+
+#### B1. Hardcoded Routes in JSX
+```
+Grep patterns (in {web_root}):
+  - <Route\s+path=      (outside DynamicRouter)
+  - path:\s*['"/]       (in non-config files)
+  - navigate\(['"]\/    (hardcoded navigation targets)
+  - to=['"]\/           (Link/NavLink with hardcoded paths)
+  - href=['"]\/(?!http) (internal links with hardcoded paths)
+```
+
+**IMPORTANT**: Exclude legitimate cases:
+- DynamicRouter.tsx itself (it generates routes dynamically)
+- Test files
+- Constants files that define route patterns for DynamicRouter consumption
+- Documentation files
+
+#### B2. Hardcoded Permissions in Components
+```
+Grep patterns (in {web_root}):
+  - hasPermission\(['"]   (string literal permission checks)
+  - permission.*===       (direct comparison)
+  - role.*===.*['"]admin  (role-based instead of permission-based)
+  - canAccess\(['"]       (string literal access checks)
+```
+
+**Distinguish**: Permission checks using API-provided data (OK) vs hardcoded permission strings (anti-pattern).
+
+**NOTE**: Components checking `permissionPath` from the menu API or from `useRouteConfig` data are CONFORMING — this is defense in depth, not hardcoding.
+
+#### B2bis. MCP-detected Hardcoded Paths (cross-reference)
+```
+If {mcp_results.frontend_routes} is available:
+  - Merge MCP apiClients.issues (type: 'invalid-path') with manual B1 findings
+  - Add any MCP-detected hardcoded navigate()/Link paths not found by manual grep
+  - Deduplicate: same file:line from both sources counts as ONE finding
+  - Mark source: [MANUAL], [MCP], or [BOTH] for each finding
+```
+
+#### B3. Non-Lazy Imports in Registry
+```
+Grep patterns (in componentRegistry files):
+  - ^import .* from      (eager imports of page components)
+  - require\(             (CommonJS require of pages)
+```
+
+**Expected pattern**: `lazy(() => import(...))`
+
+#### B4. Missing Suspense Boundaries
+```
+Grep patterns (in {web_root}):
+  - Check DynamicRouter and App.tsx for <Suspense> wrapping
+  - Check if lazy components are rendered without Suspense parent
+```
+
+#### B5. Route/Permission Path Misalignment
+```
+Cross-reference:
+  - Backend: permission paths in navigation seed data
+  - Frontend: permission checks in components
+  - Look for mismatches between API-provided paths and frontend expectations
+```
+
+#### B6. Duplicate Route Definitions
+```
+Check for routes defined in multiple places:
+  - DynamicRouter + another router file
+  - Static route config + dynamic route config
+  - Multiple files registering the same path
+```
+
+---
+
+### Phase C: Compile Conformity Summary
+
+```
+## Conformity Results
+
+| # | Element | Rating | Key Finding |
+|---|---------|--------|-------------|
+| 1 | componentRegistry | ✅/⚠️/❌/🔴 | {one-line summary} |
+| 2 | ProtectedRoute | ✅/⚠️/❌/🔴 | {one-line summary} |
+| 3 | DynamicRouter | ✅/⚠️/❌/🔴 | {one-line summary} |
+| 4 | useRouteConfig | ✅/⚠️/❌/🔴 | {one-line summary} |
+| 5 | Navigation API | ✅/⚠️/❌/🔴 | {one-line summary} |
+
+## Anti-Patterns Detected: {count}
+
+| # | Anti-Pattern | File:Line | Severity | Description |
+|---|-------------|-----------|----------|-------------|
+| 1 | {type} | {file}:{line} | HIGH/MED/LOW | {description} |
+| ... | | | | |
+
+-> Proceeding to final report...
+```
+
+---
+
+## SUCCESS METRICS:
+- Each element rated with justification
+- All 5 causal questions answered for every deviation
+- Anti-pattern scan covers entire web_root (not just routing files)
+- False positives excluded (legitimate uses identified)
+- Conformity summary table complete
+
+## NEXT STEP:
+After displaying conformity results, proceed directly to `./step-03-report.md`

package/templates/skills/audit-route/steps/step-03-report.md

@@ -0,0 +1,201 @@
+---
+name: step-03-report
+description: Generate the final structured audit report with migration plan
+---
+
+# Step 3: Final Report
+
+## MANDATORY EXECUTION RULES:
+- Use ALL data collected from steps 0-2
+- Follow the EXACT output structure below
+- Prioritize migration steps by impact (critical > important > nice-to-have)
+- Include file:line references for every finding
+- Keep executive summary to 3 lines maximum
+
+## YOUR TASK:
+Generate the complete structured audit report.
+
+---
+
+## OUTPUT STRUCTURE:
+
+Generate the following report EXACTLY in this format:
+
+```markdown
+---
+
+# Audit Dynamic Routing — {project_name}
+
+**Date**: {current_date}
+**Branch**: {current_branch}
+**Scope**: {scope}
+**Strict mode**: {strict}
+
+---
+
+## Resume executif
+
+**Score global : {X}/5 elements conformes — Statut : {OK / A corriger / Critique}**
+
+{Line 1: Overall architecture state in one sentence}
+{Line 2: Most critical finding or strength}
+{Line 3: Recommended immediate action (if any)}
+
+---
+
+## 1. componentRegistry
+**Statut** : {✅ / ⚠️ / ❌ / 🔴}
+**Fichier** : {path:line or ABSENT}
+
+{If deviation: full 5-question causal analysis (a through e)}
+{If conforme: brief confirmation with notable strengths}
+
+---
+
+## 2. ProtectedRoute
+**Statut** : {✅ / ⚠️ / ❌ / 🔴}
+**Fichier** : {path:line or ABSENT}
+
+{If deviation: full 5-question causal analysis}
+{If conforme: brief confirmation}
+
+---
+
+## 3. DynamicRouter
+**Statut** : {✅ / ⚠️ / ❌ / 🔴}
+**Fichier** : {path:line or ABSENT}
+
+{If deviation: full 5-question causal analysis}
+{If conforme: brief confirmation}
+
+---
+
+## 4. useRouteConfig (hook de fetch)
+**Statut** : {✅ / ⚠️ / ❌ / 🔴}
+**Fichier** : {path:line or ABSENT}
+
+{If deviation: full 5-question causal analysis}
+{If conforme: brief confirmation}
+
+---
+
+## 5. API Navigation
+**Statut** : {✅ / ⚠️ / ❌ / 🔴}
+**Endpoint** : {method path or ABSENT}
+
+{If deviation: full 5-question causal analysis}
+{If conforme: brief confirmation}
+
+---
+
+## Validation MCP (baseline automatique)
+
+{If MCP unavailable: "MCP non disponible — audit base sur l'analyse manuelle uniquement."}
+
+{If MCP available:}
+
+### validate_frontend_routes
+| Metrique | Valeur |
+|----------|--------|
+| Valid | {yes/no} |
+| Registry exists | {yes/no} |
+| Registered keys | {N} |
+| Missing keys | {N} |
+| API client issues | {N} |
+| Recommendations | {list} |
+
+### validate_conventions (frontend-routes)
+| Metrique | Valeur |
+|----------|--------|
+| Errors | {N} |
+| Warnings | {N} |
+| Seed data routes checked | {N} |
+
+### Divergences MCP vs analyse manuelle
+{List any differences between MCP automated results and manual analysis.
+If both agree, state: "Aucune divergence — MCP et analyse manuelle sont alignes."}
+
+---
+
+## Anti-patterns detectes
+
+{If none: "Aucun anti-pattern detecte."}
+
+{If found, list ALL with file:line references:}
+
+| # | Type | Fichier:Ligne | Severite | Description |
+|---|------|--------------|----------|-------------|
+| 1 | {type} | {file}:{line} | {CRITIQUE/IMPORTANT/MINEUR} | {description} |
+
+### Detail par anti-pattern
+
+#### AP-{n}: {title}
+- **Localisation** : {file}:{line}
+- **Code concerne** :
+  ```tsx
+  {relevant code snippet, max 5 lines}
+  ```
+- **Probleme** : {why this is an anti-pattern}
+- **Impact** : {concrete consequence}
+- **Correction** : {specific fix}
+
+---
+
+## Plan de migration priorise
+
+{If no migration needed: "Aucune migration necessaire — l'architecture est conforme au pattern cible."}
+
+{If migration needed:}
+
+### Critique (bloquer toute PR)
+{numbered list of critical fixes with file references and estimated scope}
+
+### Important (a planifier dans le sprint)
+{numbered list of important fixes}
+
+### Nice-to-have (backlog)
+{numbered list of improvements}
+
+### Ordre de migration recommande
+{If multiple fixes, specify dependency order:}
+1. {First fix — prerequisite for others}
+2. {Second fix — depends on #1}
+3. ...
+
+---
+
+## Metriques
+
+| Metrique | Valeur |
+|----------|--------|
+| Elements conformes | {X}/5 |
+| Elements partiellement conformes | {Y}/5 |
+| Elements non conformes | {Z}/5 |
+| Elements absents | {W}/5 |
+| Anti-patterns detectes | {count} |
+| Anti-patterns critiques | {count} |
+| Fichiers a modifier | {count} |
+| Estimation effort migration | {Faible/Moyen/Eleve} |
+| MCP baseline disponible | {Oui/Non} |
+| Divergences MCP vs manuel | {count} |
+
+---
+```
+
+---
+
+## REPORT QUALITY RULES:
+
+1. **Every finding has evidence** — file:line or code snippet
+2. **No vague statements** — "some routes are hardcoded" -> "3 routes hardcoded in TicketListView.tsx:42, UserPage.tsx:18, AdminDashboard.tsx:7"
+3. **Migration steps are actionable** — not "refactor the routing" but "Move Route definition from App.tsx:34-56 to DynamicRouter, add componentKey 'admin.dashboard' to PageRegistry"
+4. **Distinguish SmartStack-specific patterns** — Some deviations from the generic pattern may be correct for SmartStack SDK architecture. Flag these as "SmartStack-specific: conforming to SDK pattern" rather than as deviations
+5. **Be honest about ambiguity** — If you cannot determine whether a deviation is intentional, say "Intention ambigue" and present both interpretations
+
+## SUCCESS METRICS:
+- Report follows exact structure above
+- All sections populated with data from steps 0-2
+- Executive summary is exactly 3 lines
+- Migration plan is prioritized and actionable
+- Metrics table is complete and accurate
+- Every finding has a file:line reference

package/templates/skills/cli-app-sync/SKILL.md

@@ -113,7 +113,7 @@ COMPARISON POINTS: {total}
   [OK]    index.css — @custom-variant dark present
   [OK]    DependencyInjection.Application — MediatR warning present
   [OK]    DependencyInjection.Infrastructure — SQL Server pattern matches
-  [SKIP]  App.tsx — Intentionally different (client uses mergeRoutes legacy or PageRegistry+DynamicRouter)
+  [SKIP]  App.tsx — Intentionally different (client uses PageRegistry+DynamicRouter v3.7+)
   [SKIP]  ExtensionsDbContext — Intentionally simplified
 
 --------------------------------------------------------------------------------
@@ -161,7 +161,7 @@ These differences are **by design** and should always be marked `[SKIP]`:
 
 | File/Pattern | Reason |
 |---|---|
-| `App.tsx` — routing pattern (`mergeRoutes` legacy or `PageRegistry`+`DynamicRouter` v3.7+) | Client projects use their own routing entry point, not platform routing |
+| `App.tsx` — routing pattern (`PageRegistry`+`DynamicRouter` v3.7+) | Client projects use their own routing entry point, not platform routing |
 | `ExtensionsDbContext` | Intentionally simplified vs `CoreDbContext` — different architectural role |
 | `api.ts` | Re-exports SmartStack client — wrapper pattern is correct |
 | `DependencyInjection.Infrastructure.cs` | SQL Server connection pattern identical by design |

package/templates/skills/cli-app-sync/references/comparison-map.md

@@ -208,7 +208,7 @@ These comparisons should **always** return `[SKIP]` — differences are by desig
 
 | Item | Reason |
 |---|---|
-| `App.tsx` | Client uses `mergeRoutes` (legacy) or `PageRegistry`+`DynamicRouter` (v3.7+); app uses direct routing |
+| `App.tsx` | Client uses `PageRegistry`+`DynamicRouter` (v3.7+); app uses DynamicRouter exclusively (mergeRoutes removed in v3.7) |
 | `api.ts` | Client re-exports SmartStack client — wrapper pattern is correct |
 | `ExtensionsDbContext` | Intentionally simplified vs `CoreDbContext` |
 | `GlobalUsings.cs` | App has platform-wide usings; client has minimal set |

package/templates/skills/dev-start/SKILL.md

@@ -180,12 +180,22 @@ Use `Bash(run_in_background=true)` so it runs in background.
 2. If `--reset` OR no stored password:
    a. If backend was just launched, wait for it to be UP first:
       ```bash
-      # Poll up to 30 seconds (10 attempts x 3s)
+      # Phase 1: Wait for port to be bound (up to 30s)
       for i in $(seq 1 10); do
         netstat.exe -ano | grep ":${API_PORT} .*LISTENING" && break
         sleep 3
       done
       ```
+      ```bash
+      # Phase 2: Wait for API to actually respond to HTTP requests (up to 30s)
+      # Kestrel binds the port BEFORE the app is fully initialized.
+      # We must confirm the API actually responds before resetting the password.
+      for i in $(seq 1 10); do
+        curl -s -o /dev/null -w "%{http_code}" "http://localhost:${API_PORT}/scalar" 2>/dev/null | grep -q "200" && break
+        sleep 3
+      done
+      ```
+      If `/scalar` does not return 200 after 30s, warn the user and attempt the reset anyway.
    b. Run: `smartstack admin reset --force --json`
    c. Parse JSON output to extract email and password
    d. Write `.claude/dev-session.json`:
@@ -224,7 +234,7 @@ Use `Bash(run_in_background=true)` so it runs in background.
 
 <important_notes>
 
-1. **Backend must be UP before admin reset** - Poll the port (2-3s intervals, max 30s) before attempting password reset
+1. **Backend must be READY before admin reset** - First poll the port (netstat), then poll the `/health` endpoint (HTTP 200) to confirm the API is fully initialized. Kestrel binds the port before the app finishes starting, so port-only checks are insufficient.
 2. **Cross-worktree support** - Detect the correct API directory regardless of which worktree we're in
 3. **No MCP required** - This skill only uses bash commands and the `smartstack` CLI
 4. **Config coherence is critical** - Mismatched ports between backend/frontend is the #1 cause of "it doesn't work" issues

package/templates/skills/documentation/steps/step-03-validate.md

@@ -25,8 +25,7 @@ Validate that generated documentation is complete and accurate, then integrate i
 - [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
 - [ ] Every Mock UI section has `Annotation` components explaining each visual element
 - [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
-- [ ] Route added as **child** of `/docs/business` group (not standalone) in App.tsx
-- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] Route added as **child** of `/docs/business` group (not standalone) in DynamicRouter.tsx
 - [ ] DocsLayout sidebar updated (if applicable)
 - [ ] Module appears in UserIndexPage.tsx (if applicable)
 - [ ] DocPanelContext.tsx mapping updated for all module routes
@@ -38,8 +37,7 @@ Validate that generated documentation is complete and accurate, then integrate i
 - [ ] i18n JSON uses root key matching namespace
 - [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
 - [ ] doc-data.ts contains structured data (~50 lines)
-- [ ] Route added as **child** of `/system/docs` group (not standalone) in App.tsx
-- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] Route added as **child** of `/system/docs` group (not standalone) in DynamicRouter.tsx
 - [ ] DocsLayout sidebar updated (if applicable)
 
 #### For `update` Type
@@ -113,7 +111,7 @@ detects tenant-prefixed routes (`/t/:slug/...`), and builds lookup keys as `{app
 - `/support/tickets/123` → tries `support/tickets/123`, then `support/tickets`
 - `/t/my-company/administration/users` → strips tenant prefix, then tries `administration/users`
 
-#### App.tsx Routing
+#### DynamicRouter.tsx Routing
 
 Documentation pages use a **separate routing system** from business pages. They render inside `DocsLayout` (sidebar navigation), NOT `AppLayout`. There are two route groups:
 
@@ -122,10 +120,10 @@ Documentation pages use a **separate routing system** from business pages. They
 
 > **Note:** The `<Suspense fallback={<PageLoader />}>` is already in place at the global level (wrapping the entire Routes tree). Do NOT add per-route `<Suspense>` wrappers.
 
-**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group:
+**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group in `DynamicRouter.tsx`:
 
 ```tsx
-// 1. Add lazy import at top of App.tsx
+// 1. Add lazy import at top of DynamicRouter.tsx
 const {Module}DocPage = lazy(() =>
   import('@/pages/docs/business/{application}/{module}')
 );
@@ -138,10 +136,10 @@ const {Module}DocPage = lazy(() =>
 </Route>
 ```
 
-**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group:
+**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group in `DynamicRouter.tsx`:
 
 ```tsx
-// 1. Add lazy import at top of App.tsx
+// 1. Add lazy import at top of DynamicRouter.tsx
 const {Tool}DocPage = lazy(() =>
   import('@/pages/docs/{category}/{tool}')
 );
@@ -154,9 +152,9 @@ const {Tool}DocPage = lazy(() =>
 </Route>
 ```
 
-#### smartstackRoutes.tsx Registration
+#### DynamicRouter Documentation Routes
 
-**MANDATORY** for all doc types: Add the route in `smartstackRoutes.tsx` under the corresponding group (`/docs/business` or `/system/docs`). Documentation routes are part of `LOCKED_PREFIXES` and cannot be overridden by client extensions.
+Documentation routes are statically defined in `DynamicRouter.tsx` (not dynamically generated from the navigation API). When adding new documentation pages, add the lazy import and `<Route>` entry in the documentation section of `DynamicRouter.tsx`.
 
 #### DocsLayout Sidebar Update
 
@@ -164,7 +162,7 @@ If the new documentation page should appear in the sidebar navigation, update th
 
 #### Important Notes
 
-- Documentation routes do **NOT** use `AppLayout`, `RouteGuard`, or `LicenseGuard`
+- Documentation routes do **NOT** use `AppLayout`, `ProtectedRoute`, or `LicenseGuard`
 - Documentation routes have **no tenant prefix** (`/t/:slug/...`) — they are globally accessible
 - Documentation routes require **no specific permission** to access
 
@@ -259,8 +257,8 @@ Add or update entry with metadata:
 - [x] Mock UI faithfully reproduces the real page interface (user type)
 - [x] Every Mock UI section has `Annotation` components (user type)
 - [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
-- [x] Route added as child of correct DocsLayout group in App.tsx
-- [x] Route registered in smartstackRoutes.tsx (locked routes)
+- [x] Route added as child of correct DocsLayout group in DynamicRouter.tsx
+- [x] Route added in DynamicRouter.tsx documentation section
 - [x] DocsLayout sidebar updated (if applicable)
 - [x] docs-manifest.json updated
 - [x] i18n/config.ts updated with new namespace