@atlashub/smartstack-cli 4.35.0 → 4.37.0

package/templates/skills/audit-route/steps/step-00-init.md

@@ -0,0 +1,128 @@
+---
+name: step-00-init
+description: Parse flags, detect project structure, resolve paths for routing audit
+next_step: steps/step-01-inventory.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES:
+- NEVER skip project detection
+- ALWAYS resolve actual filesystem paths before proceeding
+- YOU ARE AN INITIALIZER, not a scanner
+
+## YOUR TASK:
+Parse the flags, detect the SmartStack project structure, and resolve which directories to scan.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Input
+
+```
+Arguments from $ARGUMENTS:
+  --scope=frontend  -> {scope} = "frontend" (elements 1-4 only)
+  --scope=backend   -> {scope} = "backend" (element 5 only)
+  --scope=all       -> {scope} = "all" (default)
+  --strict          -> {strict} = true (default: false)
+
+No arguments -> {scope} = "all", {strict} = false
+```
+
+### 2. Detect Project Structure
+
+Use Glob and Bash to locate:
+
+```
+Frontend paths:
+  {web_root} = web/smartstack-web/src/
+  Verify: package.json exists in web/smartstack-web/
+  Verify: src/ directory exists
+
+Backend paths:
+  {api_root} = src/SmartStack.Api/
+  {app_root} = src/SmartStack.Application/
+  {infra_root} = src/SmartStack.Infrastructure/
+  Verify: SmartStack.sln exists at project root
+
+Key files to pre-locate (existence check only):
+  - componentRegistry: Glob for "**/componentRegistry*" in {web_root}
+  - ProtectedRoute: Glob for "**/ProtectedRoute*" in {web_root}
+  - DynamicRouter: Glob for "**/DynamicRouter*" in {web_root}
+  - useRouteConfig: Glob for "**/useRouteConfig*" in {web_root}
+  - Navigation controller: Glob for "**/Navigation*Controller*" in {api_root}
+```
+
+### 3. Validate Paths
+
+For each required path:
+- If missing: record as CRITICAL warning
+- If found: record path for next steps
+
+### 4. MCP Pre-scan (automated baseline)
+
+Use `ToolSearch` to fetch MCP tools, then call them to get an automated baseline:
+
+```
+Step 4a: Fetch MCP tools
+  ToolSearch query="select:mcp__smartstack__validate_frontend_routes,mcp__smartstack__validate_conventions"
+
+Step 4b: Call validate_frontend_routes (if available)
+  mcp__smartstack__validate_frontend_routes scope="all"
+  -> Store full result as {mcp_results.frontend_routes}
+  -> This gives: registry status, API client issues, component registry keys, missing keys, recommendations
+
+Step 4c: Call validate_conventions (if available)
+  mcp__smartstack__validate_conventions checks=["frontend-routes"]
+  -> Store result as {mcp_results.conventions}
+  -> This gives: seed data cross-reference, missing PageRegistry entries
+
+If MCP is unavailable: record as WARNING and continue without MCP baseline.
+The manual audit in steps 1-2 will still produce a complete report.
+```
+
+### 5. Show Summary and Proceed
+
+Display:
+
+```
+Routing Audit Configuration:
+
+| Setting | Value |
+|---------|-------|
+| Scope | {scope} |
+| Strict mode | {strict} |
+| Web root | {web_root} |
+| API root | {api_root} |
+| MCP available | {yes/no} |
+
+Pre-scan results:
+| Element | File Found |
+|---------|-----------|
+| componentRegistry | {path or MISSING} |
+| ProtectedRoute | {path or MISSING} |
+| DynamicRouter | {path or MISSING} |
+| useRouteConfig | {path or MISSING} |
+| Navigation API | {path or MISSING} |
+
+MCP baseline (if available):
+| Check | Result |
+|-------|--------|
+| validate_frontend_routes | {valid: true/false, issues: N} |
+| validate_conventions | {errors: N, warnings: N} |
+
+-> Proceeding to inventory...
+```
+
+---
+
+## SUCCESS METRICS:
+- Scope and flags correctly parsed
+- All filesystem paths resolved and validated
+- MCP pre-scan executed (or gracefully skipped if unavailable)
+- Pre-scan summary displayed with file existence status
+- Ready for detailed inventory in next step
+
+## NEXT STEP:
+After showing initialization summary, proceed directly to `./step-01-inventory.md`

package/templates/skills/audit-route/steps/step-01-inventory.md

@@ -0,0 +1,157 @@
+---
+name: step-01-inventory
+description: Locate and inventory all 5 mandatory routing elements in the codebase
+next_step: steps/step-02-conformity.md
+---
+
+# Step 1: Inventory
+
+## MANDATORY EXECUTION RULES:
+- Read EVERY file identified — do NOT guess from file names alone
+- Record exact file paths AND line numbers for each finding
+- If an element is ABSENT, search for alternative implementations before declaring missing
+- Use parallel tool calls where possible for speed
+
+## YOUR TASK:
+For each of the 5 mandatory elements, locate the implementation, read it, and record key characteristics.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. componentRegistry
+
+**Search strategy:**
+1. Glob: `**/componentRegistry*`, `**/pageRegistry*`, `**/PageRegistry*` in {web_root}
+2. If not found: Grep for `React.lazy` or `lazy(` across all `.ts`/`.tsx` files
+3. If not found: Grep for `import.*Page` to find eager imports pattern
+
+**Record:**
+- File path and total lines
+- Registration mechanism (PageRegistry.register, object literal, Map, etc.)
+- Import style: lazy (`React.lazy(() => import(...))`) vs eager (`import X from`)
+- Number of registered components
+- Key naming convention (dot-separated, slash-separated, flat)
+- Where it's imported/loaded (main.tsx, App.tsx, etc.)
+
+### 2. ProtectedRoute
+
+**Search strategy:**
+1. Glob: `**/ProtectedRoute*`, `**/RouteGuard*`, `**/AuthRoute*` in {web_root}
+2. If not found: Grep for `permissions.*check\|requiredPermission\|canAccess` in routing files
+3. If not found: Grep for `Navigate.*login\|redirect.*unauthorized` in route wrappers
+
+**Record:**
+- File path and total lines
+- How permissions are received (props, context, hook)
+- Where permission data comes from (API via hook, static constants, hardcoded)
+- What happens on unauthorized (redirect, 403 page, null render)
+- Whether it contains any hardcoded route or permission lists
+
+### 3. DynamicRouter
+
+**Search strategy:**
+1. Glob: `**/DynamicRouter*`, `**/AppRouter*`, `**/RouterConfig*` in {web_root}
+2. If not found: Grep for `<Route.*path=` to find where routes are defined
+3. Also check: `App.tsx` for inline route definitions
+
+**Record:**
+- File path and total lines
+- Route generation method (iterates API data, static JSX, hybrid)
+- How components are resolved (from registry, inline import, direct reference)
+- Whether ProtectedRoute wrapping is applied
+- Handling of nested routes / outlets
+- Loading state handling (Suspense, loader, etc.)
+- Any hardcoded routes within the file (count and list them)
+
+### 4. useRouteConfig
+
+**Search strategy:**
+1. Glob: `**/useRouteConfig*`, `**/useRoutes*`, `**/useNavigation*` in {web_root}
+2. If not found: Grep for `fetch.*navigation\|fetch.*routes\|fetch.*menu` in hooks
+3. If not found: Grep for `/api/navigation` or `/api/routes` in service files
+
+**Record:**
+- File path and total lines
+- API endpoint called
+- Data transformation (flat list, tree, maps)
+- Return shape (routes, permissions, loading, error)
+- Caching strategy (React Query, SWR, useState, context)
+- When it re-fetches (auth change, mount only, interval)
+
+### 5. Navigation API
+
+**Search strategy (backend):**
+1. Glob: `**/Navigation*Controller*` in {api_root}
+2. Grep for `[HttpGet].*menu\|[HttpGet].*route\|[HttpGet].*navigation` in controllers
+3. Also check: service files with Glob `**/NavigationService*` in {infra_root}
+
+**Search strategy (frontend, as consumer):**
+1. Grep for `/api/navigation` or `navigation/menu` in {web_root}/services/
+
+**Record:**
+- Controller file path, endpoint path, HTTP method
+- Service file path (business logic)
+- Response DTO structure (what fields are returned)
+- Whether response is filtered by user permissions/JWT
+- Whether ComponentKey is included in response
+- Whether PermissionPath is included in response
+- Feature gating support (RequiredFeature field)
+
+---
+
+### 6. Cross-reference with MCP Results
+
+If `{mcp_results}` is available from step-00:
+
+```
+For componentRegistry:
+  - Compare manual key count with MCP componentRegistry.registeredKeys.length
+  - Note any missingKeys reported by MCP
+  - Flag if MCP found issues not visible from manual inspection
+
+For Navigation API:
+  - Compare seed data routes (from MCP validate_conventions) with manual API analysis
+  - Note any backend routes with no frontend counterpart
+
+For API clients:
+  - Use MCP apiClients.issues to enrich anti-pattern detection later (step-02)
+  - Record hardcoded paths found by MCP
+```
+
+### 7. Compile Inventory Table
+
+After all 5 elements are investigated, compile:
+
+```
+## Element Inventory
+
+| # | Element | Status | File | Lines | Key Characteristics |
+|---|---------|--------|------|-------|-------------------|
+| 1 | componentRegistry | FOUND/ABSENT | {path} | {n} | {summary} |
+| 2 | ProtectedRoute | FOUND/ABSENT | {path} | {n} | {summary} |
+| 3 | DynamicRouter | FOUND/ABSENT | {path} | {n} | {summary} |
+| 4 | useRouteConfig | FOUND/ABSENT | {path} | {n} | {summary} |
+| 5 | Navigation API | FOUND/ABSENT | {path} | {n} | {summary} |
+
+MCP Cross-reference (if available):
+| MCP Check | Issues Found | Aligned with Manual |
+|-----------|-------------|-------------------|
+| componentRegistry keys | {N missing} | {yes/no + detail} |
+| API client paths | {N hardcoded} | {yes/no + detail} |
+| Seed data sync | {N missing} | {yes/no + detail} |
+
+-> Proceeding to conformity analysis...
+```
+
+---
+
+## SUCCESS METRICS:
+- All 5 elements searched with at least 2 search strategies each
+- Exact file paths and line numbers recorded
+- Key characteristics noted for each found element
+- ABSENT elements confirmed after exhaustive search
+- Inventory table displayed
+
+## NEXT STEP:
+After displaying inventory, proceed directly to `./step-02-conformity.md`

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