@atlashub/smartstack-cli 4.34.0 → 4.36.0

package/templates/skills/audit-route/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: audit-route
+description: |
+  Audit dynamic routing architecture against the DB-driven pattern.
+  Use this skill when:
+  - Verifying routing is fully database-driven (no hardcoded routes)
+  - Checking the 5 mandatory elements (componentRegistry, ProtectedRoute, DynamicRouter, useRouteConfig, API)
+  - Validating route/permission alignment
+  - Detecting anti-patterns (static routes, hardcoded permissions, non-lazy imports)
+argument-hint: "[--strict] [--scope=frontend|backend|all]"
+model: sonnet
+allowed-tools: "Read, Grep, Glob, Bash, Agent, ToolSearch"
+entry_point: steps/step-00-init.md
+---
+
+<objective>
+Audit the dynamic routing implementation against the SmartStack DB-driven routing pattern. The architecture requires that navigation and permissions are **entirely driven by the database** — the React frontend must contain **zero hardcoded routes**.
+
+The audit validates 5 mandatory elements:
+1. **componentRegistry** — static mapping `string -> lazy(component)`, only allowed static file
+2. **ProtectedRoute** — front-end guard that validates permissions from the API (defense in depth)
+3. **DynamicRouter** — rendering engine that generates `<Route>` from API config
+4. **useRouteConfig** — hook that fetches route config + permissions from the API at mount
+5. **Navigation API** — endpoint returning routes **already filtered** by JWT/session
+
+For each element: inventory, conformity check, causal analysis of deviations, and migration plan.
+</objective>
+
+<quick_start>
+
+```bash
+/audit-route                     # Full audit (frontend + backend)
+/audit-route --scope=frontend    # Frontend only (React routing)
+/audit-route --scope=backend     # Backend only (API + navigation)
+/audit-route --strict            # Fail on any partial conformity (treat warnings as errors)
+```
+
+</quick_start>
+
+<parameters>
+
+<flags>
+| Flag | Description |
+|------|-------------|
+| `--scope=all` | Audit both frontend and backend (default) |
+| `--scope=frontend` | Audit React routing only (elements 1-4) |
+| `--scope=backend` | Audit API navigation only (element 5) |
+| `--strict` | Treat partial conformity (warning) as non-conformity (error) |
+</flags>
+
+</parameters>
+
+<workflow>
+1. **Initialize** — Detect project structure, resolve paths, parse flags
+2. **MCP Pre-scan** — Call `validate_frontend_routes` and `validate_conventions` for automated baseline
+3. **Inventory** — Locate each of the 5 mandatory elements in the codebase
+4. **Conformity** — Evaluate each element against the reference pattern, cross-reference with MCP findings
+5. **Anti-patterns** — Scan for hardcoded routes, static permissions, non-lazy imports
+6. **Report** — Generate structured audit report with causal analysis and migration plan
+</workflow>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{scope}` | string | frontend, backend, or all |
+| `{strict}` | boolean | Treat warnings as errors |
+| `{web_root}` | string | Path to web/smartstack-web/src/ |
+| `{api_root}` | string | Path to src/SmartStack.Api/ |
+| `{elements}` | object[] | Inventory of the 5 mandatory elements |
+| `{conformity}` | object[] | Conformity status per element |
+| `{anti_patterns}` | object[] | Detected anti-patterns with file:line |
+| `{mcp_results}` | object | Results from MCP validate_frontend_routes + validate_conventions |
+| `{score}` | string | X/5 conformity score |
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+</entry_point>
+
+<step_files>
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `steps/step-00-init.md` | Parse flags, detect project structure, resolve paths |
+| 01 | `steps/step-01-inventory.md` | Locate all 5 mandatory elements in the codebase |
+| 02 | `steps/step-02-conformity.md` | Evaluate conformity, causal analysis, anti-pattern scan |
+| 03 | `steps/step-03-report.md` | Generate structured audit report with migration plan |
+</step_files>
+
+<execution_rules>
+- **Read-only** — This skill NEVER modifies code
+- **Non-judgmental** — Analyze code, not developers. Distinguish errors from conscious choices
+- **Comprehensive** — Check ALL files, not a sample. Grep entire codebase for anti-patterns
+- **Evidence-based** — Every finding must reference a specific file:line
+- **Causal** — Every deviation must include: what was done instead, why it deviates, probable reason, consequence, and migration path
+- **SmartStack-aware** — Respect SmartStack SDK architecture (PageRegistry, DynamicRouter, menu API)
+</execution_rules>
+
+<success_criteria>
+- All 5 elements inventoried with exact file paths and line numbers
+- Each element rated: Conforme / Partiellement conforme / Non conforme / Absent
+- Anti-patterns detected across entire codebase (not just routing files)
+- Causal analysis for every deviation (5 questions answered)
+- Prioritized migration plan (critical > important > nice-to-have)
+- Executive summary with X/5 score and 3-line architecture status
+</success_criteria>

package/templates/skills/audit-route/references/routing-pattern.md

@@ -0,0 +1,129 @@
+# Dynamic Routing Reference Pattern
+
+## Architecture Principle
+
+Navigation and permissions are **entirely driven by the database**. The React frontend contains **zero hardcoded routes**. The backend API returns routes already filtered by the user's JWT/session.
+
+## 5 Mandatory Elements
+
+### 1. componentRegistry
+
+**Role**: Static mapping `string -> lazy(component)`. The ONLY allowed static file.
+
+**Requirements**:
+- All page imports MUST be lazy (`React.lazy(() => import(...))`)
+- Keys are string identifiers (dot-separated hierarchical recommended)
+- No business logic in the registry — pure mapping only
+- Must be loaded at app startup (imported in main.tsx or App.tsx)
+- New pages are registered here and ONLY here
+
+**SmartStack specifics**:
+- File: `componentRegistry.generated.ts`
+- Registration via `PageRegistry.register()` (v3.7+)
+- `PAGE_KEYS` constant for type-safe key references
+- Generated by MCP `scaffold_routes` tool
+
+### 2. ProtectedRoute
+
+**Role**: Front-end guard that validates permissions received from the API (defense in depth).
+
+**Requirements**:
+- Receives permission requirements from route config (NOT hardcoded)
+- Checks user permissions against route requirements
+- Redirects unauthorized users (to login or forbidden page)
+- Does NOT contain a list of routes or paths
+- Permissions come from the API, not from static constants
+
+**SmartStack specifics**:
+- File: `ProtectedRoute.tsx`
+- Replaced the old `RouteGuard.tsx` (which had hardcoded lists)
+- Uses `permissionPath` from menu API DTOs
+
+### 3. DynamicRouter
+
+**Role**: Rendering engine that generates `<Route>` elements from the API configuration.
+
+**Requirements**:
+- Iterates over API route config to create React Router `<Route>` elements
+- Resolves components from componentRegistry by key
+- Wraps routes with ProtectedRoute for permission checking
+- Handles nested routes (outlets, tabs)
+- Supports loading states (shows loader while config is being fetched)
+- No hardcoded route paths in the router itself
+
+**SmartStack specifics**:
+- File: `DynamicRouter.tsx`
+- Sole routing engine — App.tsx reduced to providers + DynamicRouter
+- Handles: dynamic app routes, feature gating, auto-redirects, outlet tab routes, doc routes
+- `OUTLET_SECTIONS` config for tab-based pages
+- `getStaticAppRoutes()` for per-app legacy redirects (migration period only)
+
+### 4. useRouteConfig
+
+**Role**: Hook that fetches route configuration + permissions from the API at mount.
+
+**Requirements**:
+- Calls navigation API on mount (or auth change)
+- Returns structured route config with components, paths, and permissions
+- Provides loading/error states
+- Caches appropriately (invalidates on auth change)
+- Flattens hierarchical menu into usable route entries
+
+**SmartStack specifics**:
+- File: `useRouteConfig.ts`
+- Flattens menu API response into `RouteConfigEntry[]`
+- Provides `byKey` and `byApplication` maps
+- Used by DynamicRouter to build routes
+
+### 5. Navigation API
+
+**Role**: Endpoint returning routes already filtered by JWT/session.
+
+**Requirements**:
+- Returns routes with: path, componentKey, permissions, children
+- Filters routes based on authenticated user's permissions
+- Hierarchical structure (Application > Module > Section > Resource)
+- Includes permission paths for front-end guard
+- Supports feature gating (license-based)
+
+**SmartStack specifics**:
+- Endpoint: `GET /api/navigation/menu`
+- Returns enriched DTOs at 4 levels (Application, Module, Section, Resource)
+- `ComponentKey` and `PermissionPath` on all 4 DTO levels
+- `RequiredFeature` for license-based feature gating
+- Built by `NavigationService.BuildApplicationMenu/BuildModuleMenu/BuildSectionMenu/BuildResourceMenu`
+
+## Expected API Response Structure
+
+```json
+{
+  "routes": [
+    {
+      "path": "/administration/users",
+      "componentKey": "administration.users.list",
+      "permissionPath": "administration.users",
+      "permissions": ["administration.users.access", "administration.users.read"],
+      "children": [
+        {
+          "path": ":id",
+          "componentKey": "administration.users.detail",
+          "permissions": ["administration.users.read"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Description | Risk |
+|-------------|-------------|------|
+| Hardcoded routes in JSX | `<Route path="/admin" ...>` outside DynamicRouter | Routes drift from DB, permissions bypassed |
+| Static permission lists | `const ADMIN_PERMS = [...]` in components | Permissions out of sync with API |
+| Non-lazy imports in registry | `import Page from './Page'` (eager) | Bundle bloat, slow initial load |
+| Missing Suspense boundary | No `<Suspense>` around lazy components | Crashes on slow loads |
+| Route paths in components | `navigate('/admin/users')` with hardcoded paths | Tight coupling, breaks if DB paths change |
+| Permission checks without API | `if (user.role === 'admin')` | Bypasses permission system |
+| Duplicate route definitions | Routes in both DynamicRouter and static config | Conflicts, unpredictable behavior |
+| Missing loading state | No loader while route config is fetching | Flash of "not found" page |

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`