@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -1,158 +0,0 @@
-# Frontend: Routing Rules & Post-Generation Verification
-
-> Reference for step-05-frontend.md — routing rules and mandatory verification checks.
-
-## Routing Rules
-
-> ⚠️ **DEPRECATED PATTERN — v3.46+** : Domain-specific layouts (`SalesLayout`, `AdminLayout`, `BusinessLayout`, `UserLayout`, `HRLayout`) are REMOVED. There are now **only 4 layouts** : `AppLayout` (sole shell for authenticated app routes), `AuthLayout` (login/register), `PublicLayout` (public pages), `DocsLayout` (documentation). The "manual `<Route>` declaration" examples below are LEGACY ; on v3.46+ routes are resolved by `DynamicRouter` via `componentRegistry.generated.ts` (see Section 5b below + `references/smartstack-provider.md`). The examples are kept for projects on v3.6 and earlier.
-
-### Rule 1: Routes MUST be inside Layout wrappers
-
-**CRITICAL (legacy v3.6 only):** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation). On v3.46+, `AppLayout` is the SOLE shell.
-
-```tsx
-// CORRECT (v3.46+) - Inside AppLayout (shell renders: header + AvatarMenu + sidebar)
-<Route path="/sales" element={<AppLayout />}>
-  <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 (v3.46+ uses AppLayout)
-<Route path="/sales" element={<AppLayout />}>
-  <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 registered:
-- **v3.7+ (DynamicRouter):** PageRegistry.register() exists in componentRegistry.generated.ts
-- **Legacy:** inside Layout wrapper, nested, correct path convention
-- Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)
-
-### 5b. Route Wiring Check (BLOCKING)
-
-**v3.7+ (DynamicRouter):** Verify PageRegistry registration:
-
-1. Open `componentRegistry.generated.ts`
-2. Verify new pages have `PageRegistry.register()` calls with matching componentKeys
-3. Verify `main.tsx` imports `./extensions/componentRegistry.generated`
-4. DynamicRouter resolves routes automatically — no App.tsx wiring needed
-
-**Legacy:** Verify routes are wired into App.tsx (inside Layout wrapper + tenant block).
-
-Run validation:
-```
-Tool: mcp__smartstack__validate_frontend_routes
-Args:
-  scope: "routes"
-```
-
-If validation returns issues, fix 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 keys from `componentRegistry.generated.ts` (v3.7+) or App.tsx (`applicationRoutes` / `<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/init-parameter-detection.md

@@ -1,121 +0,0 @@
-# Initialization: Parameter Detection & Extraction
-
-> Referenced from `steps/step-00-init.md` — Parameter parsing and MCP validation.
-
----
-
-## Navigation Level Detection
-
-From user request, identify the level:
-
-| Hint in Request | → Level | Parent Required |
-|-----------------|---------|-----------------|
-| "application", "app", "nouvelle application" | application | No |
-| "module", "feature", "nouveau module" | module | Yes (application) |
-| "section", "tab", "nouvelle section" | section | Yes (application.module) |
-| "resource", "sous-section" | resource | Yes (application.module.section) |
-
----
-
-## Parameter Extraction
-
-Required parameters to extract:
-
-```yaml
-# Required
-level: application | module | section | resource
-code: kebab-case (e.g., "products", "order-management")
-labels:
-  fr: "Label français"
-  en: "English label"
-  it: "Etichetta italiana"
-  de: "Deutsche Bezeichnung"
-icon: Lucide icon name (e.g., "Package", "ShoppingCart")
-displayOrder: number
-
-# Conditional (required for module and section levels)
-parentPath: "application.module" or "application.module.section" (dot-separated)
-```
-
----
-
-## Project Type & Seeding Strategy
-
-Read `.smartstack/config.json` at the project root:
-
-| projectType | dbContext | Seeding Strategy |
-|-------------|----------|-----------------|
-| `core` | `core` | HasData() in Configuration files (existing pattern) |
-| `client` | `extensions` | IClientSeedDataProvider (runtime seeding) |
-
-**If file not found or projectType missing:** Default to `core` / `hasdata`.
-
-Store:
-```
-{project_type} = "core" or "client"
-{db_context} = "core" or "extensions"
-{seeding_strategy} = "hasdata" or "provider"
-```
-
----
-
-## Feature.json Context (Optional Enrichment)
-
-Search for a Business Analysis feature.json for the target module:
-
-```
-Glob: docs/business/*/{code}/business-analyse/v*/feature.json
-      .business-analyse/business/*/modules/{code}/features/*/feature.json
-```
-
-**If found (status = "handed-off" or "consolidated"):**
-
-Extract context for subsequent steps:
-
-| feature.json Section | Used In Step | Extracted Data |
-|----------------------|-------------|----------------|
-| `analysis.entities[]` | step-04 (backend) | Entity names, attributes, relationships, validations |
-| `specification.useCases[]` | step-04 (backend) | API endpoint definitions beyond basic CRUD |
-| `specification.permissionMatrix` | step-02 (permissions) | Custom permission paths and role assignments |
-| `specification.apiEndpoints[]` | step-04 (backend) | Exact HTTP methods, routes, DTOs |
-| `specification.navigation` | step-01 (navigation) | Navigation hierarchy with labels and icons |
-| `specification.i18nKeys` | step-05 (frontend) | Pre-defined translation keys |
-| `specification.validations[]` | step-04 (backend) | Field-level validation rules |
-| `specification.uiWireframes[]` | step-05 (frontend) | UI layout guidance |
-| `specification.seedDataCore` | step-01, step-02, step-03 | Pre-computed seeds |
-| `analysis.businessRules[]` | step-04, step-07 | Business rules for service logic and tests |
-| `specification.lifeCycles[]` | step-04 (backend) | Entity state machines |
-| `specification.dashboards` | step-05 (frontend) | Dashboard KPIs and chart specs |
-| `documentation` | step-08 | userDocRequired / techDocRequired flags |
-
-Store:
-```
-{feature_json_path} = "path/to/feature.json" or null
-{has_feature_context} = true or false
-{feature_data} = parsed feature.json object (if found)
-```
-
-**If NOT found or status not in ["handed-off", "consolidated"]:**
-```
-{has_feature_context} = false
-```
-
-Continue normally. All subsequent steps use their standard generation logic (generic CRUD).
-
-> **When `{has_feature_context} = true`**, subsequent steps SHOULD use the feature.json data
-> to generate more accurate code: entities with correct attributes and relationships, custom
-> permissions beyond basic CRUD, specific API routes, validation rules, and business logic
-> in services. This reduces post-generation manual corrections significantly.
-
----
-
-## MCP Prerequisite Check (BLOCKING)
-
-**CRITICAL:** This check is **BLOCKING** - the skill cannot proceed without MCP.
-
-Call: `mcp__smartstack__validate_conventions`
-Args: `{ checks: ["tables"] }`
-
-**On success:** Set `mcp_available = true`, continue.
-
-**On failure (STOP):** Display MCP installation instructions and halt.

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

@@ -1,88 +0,0 @@
-# Migration: Checklist & Troubleshooting
-
-> Referenced from `steps/step-06-migration.md` — Migration verification and common issues.
-
----
-
-## Pre-Migration Build Verification (BLOCKING)
-
-**CRITICAL:** The backend MUST build successfully before creating a migration.
-EF Core tools compile the project internally; a build failure produces confusing errors
-that do not point to the actual source file.
-
-```bash
-dotnet build {SolutionName}.sln --no-restore
-```
-
-**Common causes at this stage:**
-- Missing DbSet registration (should have been caught in step-04 Check 2)
-- Missing DI registration (should have been caught in step-04 Check 3)
-- Circular references between generated services
-- Missing package references (e.g., FluentValidation)
-- Frontend changes that modified shared files
-
-**After build succeeds:** Continue to migration name suggestion.
-
----
-
-## Migration Content Verification
-
-The migration should include:
-- Navigation entity (Application/Module/Section/Resource)
-- Navigation translations (4 languages)
-- Permissions (CRUD + wildcard)
-- RolePermissions (role assignments)
-- Domain entity table
-- Indexes and constraints
-- SQL Objects: applied automatically at startup (no migration injection needed)
-
----
-
-## SQL Objects
-
-SQL objects (TVFs, views, stored procedures) are applied **automatically at application startup** via `SqlObjectHelper.ApplyAllAsync()` in `SmartStackExtensions.InitializeSmartStackAsync()`. No injection into migrations is needed — just restart the application after modifying `.sql` files.
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| 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 |
-| i18n missing | Check locale files exist and are properly loaded |
-| EF Core compilation error | Check DbSet and DI registration |
-| FK constraint errors | Verify all entity references exist in seed data |
-
-### Quick Fixes
-
-```bash
-# Rebuild and restart
-dotnet build
-dotnet ef database update
-
-# Clear frontend cache
-cd web && rm -rf node_modules/.cache && npm run dev
-
-# Reset database (development only)
-dotnet ef database drop --context CoreDbContext --force
-dotnet ef database update --context CoreDbContext
-```
-
----
-
-## Final Checklist
-
-- [ ] Pre-migration build passed
-- [ ] Migration name suggested via MCP
-- [ ] Migration created with correct context
-- [ ] Migration includes navigation, permissions, and entity table
-- [ ] Migration applied successfully
-- [ ] Database updated without errors
-- [ ] DbSet registered in DbContext
-- [ ] DI registration in place
-- [ ] Application starts without errors

package/templates/skills/application/references/nav-fallback-procedure.md

@@ -1,198 +0,0 @@
-# Navigation: Fallback Procedure (When MCP Unavailable)
-
-> Reference for step-01-navigation.md — generates navigation seeds following SmartStack.app patterns.
-> Reference: `templates-seed.md` for code templates.
->
-> **Branch by Project Type:**
-> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below
-> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** in step file
-
-## F1. Read Existing Configuration Files
-
-**CRITICAL:** Before generating any code, read existing files to determine state:
-
-1. **Find the Navigation Configuration directory:**
-   ```
-   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
-   ```
-
-2. **Read NavigationTranslationConfiguration.cs** - Check existing translations:
-   ```
-   All translation IDs use Guid.NewGuid() — no sequence to track.
-   Just verify no duplicate EntityType+EntityId+LanguageCode combinations.
-   ```
-
-3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
-   ```
-   Read the Configuration for the target level (Application, Module, Section, Resource).
-   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
-   If yes: Read the corresponding SeedData class to find existing entries.
-   If no: You will need to add HasData() call.
-   ```
-
-4. **Read existing SeedData files** (if they exist):
-   ```
-   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
-   Check for existing entity IDs to avoid collisions.
-   ```
-
-## F2. Determine Parent GUID
-
-For non-application levels, find the parent entity GUID:
-
-| Level | Parent | Where to Find Parent GUID |
-|-------|--------|---------------------------|
-| application | (none — top level) | — |
-| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
-| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
-
-Read the parent SeedData class and find the GUID matching `{parent_path}`.
-
-## F3. Generate Navigation Entity GUID
-
-Generate a random GUID for the new navigation entity:
-
-```csharp
-// IMPORTANT: Use a stable GUID. Never change after the first seed.
-// Generate once with Guid.NewGuid(), then hardcode the result as a static field.
-public static readonly Guid MyEntityId = Guid.Parse("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
-```
-
-**Rules:**
-- Generate a GUID once with `Guid.NewGuid()`, then **hardcode it as a static readonly field**
-- NEVER call `Guid.NewGuid()` at runtime in seed data — each migration run would generate different IDs, breaking foreign keys
-- Idempotence is handled by EF Core HasData matching on the `Id` primary key
-- Store result as `{navigation_guid}`
-
-## F4. Write Navigation Entity Seed
-
-Based on `{level}`, write the seed entry.
-
-**Option A: Project uses SeedData classes (SmartStack.app pattern)**
-
-If `Navigation{Level}SeedData.cs` exists, add the new entity:
-
-```csharp
-// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
-
-// Add static GUID field
-public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");
-
-// Add to GetSeedData() return array
-new {
-    Id = {PascalCode}Id,
-    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
-    Code = "{code}",
-    Label = "{labels.en}",
-    Description = "{descriptions.en}",
-    Icon = "{icon}",
-    IconType = IconType.Lucide,
-    Route = "/{full_path_with_slashes}",
-    DisplayOrder = {display_order},
-    IsActive = true,
-    CreatedAt = SeedConstants.SeedDate
-}
-```
-
-**FK property by level:**
-
-| Level | FK Property | References |
-|-------|-------------|------------|
-| application | (none — top level) | — |
-| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
-| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
-
-**Option B: Project uses inline HasData**
-
-If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:
-
-```csharp
-// In Configure method, add:
-builder.HasData(new {
-    Id = Guid.Parse("{navigation_guid}"),
-    // ... same properties as Option A
-});
-```
-
-## F5. Write Translation Entries
-
-Add 4 translation entries to `NavigationTranslationConfiguration.cs`:
-
-1. Read the file to find the current highest `index` value
-2. Continue from `index + 1`
-3. Use the SAME `GenerateGuid` method already defined in the file:
-
-```csharp
-// In GetSeedData() method, add at the end before return:
-
-// {level}: {code} translations
-translations.Add(new {
-    Id = Guid.NewGuid(),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
-    LanguageCode = "fr",
-    Label = "{labels.fr}",
-    Description = "{descriptions.fr}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = Guid.NewGuid(),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "en",
-    Label = "{labels.en}",
-    Description = "{descriptions.en}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = Guid.NewGuid(),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "it",
-    Label = "{labels.it}",
-    Description = "{descriptions.it}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = Guid.NewGuid(),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "de",
-    Label = "{labels.de}",
-    Description = "{descriptions.de}",
-    CreatedAt = seedDate
-});
-```
-
-## F6. Store Result
-
-```
-{navigation_guid} = [generated GUID]
-{seed_method} = "fallback"  // Indicates MCP was not used
-```
-
-## F7. Validation Checklist
-
-Before proceeding, verify:
-- [ ] Random GUID generated via Guid.NewGuid()
-- [ ] 4 languages present (fr, en, it, de)
-- [ ] No duplicate EntityType+EntityId+LanguageCode combinations
-- [ ] Parent GUID correctly references existing entity
-- [ ] Route path matches `/{app}/{module}` pattern
-- [ ] DisplayOrder is consistent with existing entities
-- [ ] Code is WRITTEN to files, not just displayed
-
-## F8. Present Summary
-
-```markdown
-## Navigation Seeds Generated (Fallback)
-
-**Entity:** {level} - {code}
-**GUID:** {navigation_guid}
-**Path:** {full_path}
-
-### Files Updated
-
-1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
-2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
-```