@atlashub/smartstack-cli 3.39.0 → 3.41.0

package/templates/skills/application/references/frontend-verification.md

@@ -1,156 +1,156 @@
-# Frontend: Routing Rules & Post-Generation Verification
-
-> Reference for step-05-frontend.md — routing rules and mandatory verification checks.
-
-## Routing Rules
-
-### Rule 1: Routes MUST be inside Layout wrappers
-
-**CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
-
-```tsx
-// CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
-<Route path="/sales" element={<SalesLayout />}>
-  <Route path="products" element={<ProductsPage />} />
-</Route>
-
-// FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
-<Route path="/sales/products" element={<ProductsPage />} />
-```
-
-### Rule 2: Use nested routes (not flat)
-
-**CRITICAL:** SmartStack requires NESTED routes within the layout:
-
-```tsx
-// CORRECT - Nested routes inside layout
-<Route path="/sales" element={<SalesLayout />}>
-  <Route path="products">
-    <Route index element={<Navigate to="products" replace />} />
-    <Route path="products" element={<ProductsPage />} />
-    <Route path="orders" element={<OrdersPage />} />
-  </Route>
-</Route>
-
-// FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
-<Route path="/sales/products" element={<Navigate to="products" />} />
-<Route path="/sales/products" element={<ProductsPage />} />
-```
-
-## Post-Generation Verification (MANDATORY)
-
-**Before proceeding to step-06, run these checks on ALL generated frontend files:**
-
-### 1. CSS Variables Check (BLOCKING)
-
-Scan all generated `.tsx` files for hardcoded Tailwind colors:
-
-```
-FORBIDDEN patterns: bg-blue-, bg-red-, bg-green-, bg-gray-, bg-amber-,
-                    text-blue-, text-red-, text-green-, text-gray-, text-amber-,
-                    border-blue-, border-red-, border-green-, border-gray-
-```
-
-If ANY hardcoded color is found → **FIX IT** using CSS variables from style-guide.md before continuing.
-
-### 2. API Client Check (BLOCKING)
-
-Verify all API service files use the configured client:
-- **CORRECT:** `import { api } from '@/services/api/apiClient'` or `import api from '../api'`
-- **FORBIDDEN:** `import axios from 'axios'`
-
-### 3. EntityCard Check
-
-If a grid/card view is generated, verify it uses `EntityCard` component (not custom divs).
-
-### 4. i18n Check (BLOCKING)
-
-Verify exactly **4 language files** exist with identical key structures:
-- `fr/{entityCode}.json`
-- `en/{entityCode}.json`
-- `it/{entityCode}.json`
-- `de/{entityCode}.json`
-
-### 5. Route Check (BLOCKING)
-
-Verify routes are:
-- **INSIDE** the AppLayout wrapper
-- **NESTED** (not flat)
-- Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)
-
-### 5b. Route Wiring Check (BLOCKING)
-
-Verify routes are actually wired into App.tsx (not just generated in standalone files):
-
-1. Open `App.tsx` (or `main.tsx`)
-2. Verify the new route path appears **inside** the correct Layout wrapper
-3. Verify the route also appears inside the **tenant-prefixed** block (`/t/:slug/...`)
-4. Verify the page component is imported (lazy-loaded) at the top of the file
-
-**If routes are only in `clientRoutes.generated.tsx` or `routes/index.tsx` but NOT in App.tsx, the routes will NOT work at runtime — page will be BLANK.**
-
-Run validation:
-```
-Tool: mcp__smartstack__validate_frontend_routes
-Args:
-  scope: "routes"
-```
-
-If `appWiring.issues` is not empty, fix the wiring before proceeding.
-
-### 5c. Route Kebab-Case Check (BLOCKING)
-
-Scan App.tsx route paths for non-kebab-case segments:
-
-**FORBIDDEN** — concatenated multi-word segments without hyphens:
-- `humanresources`, `timemanagement`, `mymodule` (when representing multi-word names)
-
-**REQUIRED** — proper kebab-case for multi-word segments:
-- `human-resources`, `time-management`
-
-**Verification steps:**
-
-1. Extract all route path strings from App.tsx (both `applicationRoutes` and `<Route path="...">`)
-2. For each multi-word path segment, verify it uses hyphens (kebab-case)
-3. Cross-reference route paths with navigation seed data routes to ensure exact match
-4. Single-word segments are fine as-is (e.g., `employees`, `products`)
-
-**Grep check** — verify no multi-word segments without hyphens in route paths:
-```bash
-# Should return NO matches for multi-word segments without hyphens
-grep -E "path:\s*['\"]([a-z]+[A-Z]|[a-z]{2,}[a-z]{2,}/)" App.tsx
-```
-
-If ANY non-kebab-case multi-word route segment is found → **FIX IT** before continuing.
-
-### 6. States Check
-
-Verify the list page includes:
-- Loading state (spinner)
-- Error state (icon + message + retry button)
-- Empty state (icon + message)
-
-### 7. TypeScript Build Check (BLOCKING)
-
-Run the frontend type check to verify all generated files compile:
-
-```bash
-cd web && npx tsc --noEmit 2>&1 | head -50
-```
-
-OR if the project uses a build script:
-
-```bash
-cd web && npm run build 2>&1 | head -80
-```
-
-IF type errors exist **in generated files**: Fix them before proceeding.
-Common issues: missing imports, wrong interface names, incorrect prop types, missing hook return types.
-
-IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.
-
-**Focus only on errors in files generated by this step:**
-- `pages/{application}/{module}/*.tsx`
-- `services/api/{entityCode}Api.ts`
-- `types/{entityName}.types.ts`
-- `hooks/use{EntityName}*.ts`
+# Frontend: Routing Rules & Post-Generation Verification
+
+> Reference for step-05-frontend.md — routing rules and mandatory verification checks.
+
+## Routing Rules
+
+### Rule 1: Routes MUST be inside Layout wrappers
+
+**CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
+
+```tsx
+// CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/sales" element={<SalesLayout />}>
+  <Route path="products" element={<ProductsPage />} />
+</Route>
+
+// FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
+<Route path="/sales/products" element={<ProductsPage />} />
+```
+
+### Rule 2: Use nested routes (not flat)
+
+**CRITICAL:** SmartStack requires NESTED routes within the layout:
+
+```tsx
+// CORRECT - Nested routes inside layout
+<Route path="/sales" element={<SalesLayout />}>
+  <Route path="products">
+    <Route index element={<Navigate to="products" replace />} />
+    <Route path="products" element={<ProductsPage />} />
+    <Route path="orders" element={<OrdersPage />} />
+  </Route>
+</Route>
+
+// FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
+<Route path="/sales/products" element={<Navigate to="products" />} />
+<Route path="/sales/products" element={<ProductsPage />} />
+```
+
+## Post-Generation Verification (MANDATORY)
+
+**Before proceeding to step-06, run these checks on ALL generated frontend files:**
+
+### 1. CSS Variables Check (BLOCKING)
+
+Scan all generated `.tsx` files for hardcoded Tailwind colors:
+
+```
+FORBIDDEN patterns: bg-blue-, bg-red-, bg-green-, bg-gray-, bg-amber-,
+                    text-blue-, text-red-, text-green-, text-gray-, text-amber-,
+                    border-blue-, border-red-, border-green-, border-gray-
+```
+
+If ANY hardcoded color is found → **FIX IT** using CSS variables from style-guide.md before continuing.
+
+### 2. API Client Check (BLOCKING)
+
+Verify all API service files use the configured client:
+- **CORRECT:** `import { api } from '@/services/api/apiClient'` or `import api from '../api'`
+- **FORBIDDEN:** `import axios from 'axios'`
+
+### 3. EntityCard Check
+
+If a grid/card view is generated, verify it uses `EntityCard` component (not custom divs).
+
+### 4. i18n Check (BLOCKING)
+
+Verify exactly **4 language files** exist with identical key structures:
+- `fr/{entityCode}.json`
+- `en/{entityCode}.json`
+- `it/{entityCode}.json`
+- `de/{entityCode}.json`
+
+### 5. Route Check (BLOCKING)
+
+Verify routes are:
+- **INSIDE** the AppLayout wrapper
+- **NESTED** (not flat)
+- Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)
+
+### 5b. Route Wiring Check (BLOCKING)
+
+Verify routes are actually wired into App.tsx (not just generated in standalone files):
+
+1. Open `App.tsx` (or `main.tsx`)
+2. Verify the new route path appears **inside** the correct Layout wrapper
+3. Verify the route also appears inside the **tenant-prefixed** block (`/t/:slug/...`)
+4. Verify the page component is imported (lazy-loaded) at the top of the file
+
+**If routes are only in `clientRoutes.generated.tsx` or `routes/index.tsx` but NOT in App.tsx, the routes will NOT work at runtime — page will be BLANK.**
+
+Run validation:
+```
+Tool: mcp__smartstack__validate_frontend_routes
+Args:
+  scope: "routes"
+```
+
+If `appWiring.issues` is not empty, fix the wiring before proceeding.
+
+### 5c. Route Kebab-Case Check (BLOCKING)
+
+Scan App.tsx route paths for non-kebab-case segments:
+
+**FORBIDDEN** — concatenated multi-word segments without hyphens:
+- `humanresources`, `timemanagement`, `mymodule` (when representing multi-word names)
+
+**REQUIRED** — proper kebab-case for multi-word segments:
+- `human-resources`, `time-management`
+
+**Verification steps:**
+
+1. Extract all route path strings from App.tsx (both `applicationRoutes` and `<Route path="...">`)
+2. For each multi-word path segment, verify it uses hyphens (kebab-case)
+3. Cross-reference route paths with navigation seed data routes to ensure exact match
+4. Single-word segments are fine as-is (e.g., `employees`, `products`)
+
+**Grep check** — verify no multi-word segments without hyphens in route paths:
+```bash
+# Should return NO matches for multi-word segments without hyphens
+grep -E "path:\s*['\"]([a-z]+[A-Z]|[a-z]{2,}[a-z]{2,}/)" App.tsx
+```
+
+If ANY non-kebab-case multi-word route segment is found → **FIX IT** before continuing.
+
+### 6. States Check
+
+Verify the list page includes:
+- Loading state (spinner)
+- Error state (icon + message + retry button)
+- Empty state (icon + message)
+
+### 7. TypeScript Build Check (BLOCKING)
+
+Run the frontend type check to verify all generated files compile:
+
+```bash
+cd web && npx tsc --noEmit 2>&1 | head -50
+```
+
+OR if the project uses a build script:
+
+```bash
+cd web && npm run build 2>&1 | head -80
+```
+
+IF type errors exist **in generated files**: Fix them before proceeding.
+Common issues: missing imports, wrong interface names, incorrect prop types, missing hook return types.
+
+IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.
+
+**Focus only on errors in files generated by this step:**
+- `pages/{application}/{module}/*.tsx`
+- `services/api/{entityCode}Api.ts`
+- `types/{entityName}.types.ts`
+- `hooks/use{EntityName}*.ts`

package/templates/skills/application/references/migration-checklist-troubleshooting.md

@@ -61,7 +61,7 @@ This ensures SQL functions/views are re-applied with each migration (`CREATE OR
 
 | Issue | Solution |
 |-------|----------|
-| Migration conflicts | Run `/efcore:conflicts` to analyze |
+| Migration conflicts | Run `/efcore conflicts` to analyze |
 | Permission 403 errors | Verify Permissions.cs and PermissionConfiguration.cs are in sync |
 | Navigation not visible | Check user role has appropriate permissions |
 | Route not found | Verify nested route structure in routes.tsx |