@atlashub/smartstack-cli 4.81.0 → 5.0.0

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

@@ -1,107 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
-# 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
-- `IMPLICIT_SUFFIXES` (24 suffixes : `.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`) auto-generate child routes (e.g. `/users/:id` for `.detail`) without seeding them in the menu
-- **`mergeRoutes()` and `getStaticAppRoutes()` REMOVED in v3.7+** — clients must register pages via `PageRegistry.register()` only. Legacy migration helpers no longer exist.
-- API-driven `isOpen` flag on each application bypasses permission checks (replaces hardcoded OPEN_APPS list). DTO field on `ApplicationMenuDto`.
-
-### 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

@@ -1,128 +0,0 @@
----
-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

@@ -1,157 +0,0 @@
----
-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`