@atlashub/smartstack-cli 2.5.3 → 2.6.1

package/templates/skills/application/steps/step-03b-provider.md

@@ -0,0 +1,251 @@
+---
+name: step-03b-provider
+description: Generate IClientSeedDataProvider implementation for client projects
+prev_step: steps/step-03-roles.md
+next_step: steps/step-04-backend.md
+---
+
+# Step 3b: Client Seed Data Provider (Client Projects Only)
+
+## CONDITION D'EXECUTION
+
+> This step executes ONLY if `{seeding_strategy}` = "provider" (client project).
+> If `{seeding_strategy}` = "hasdata", skip directly to step-04-backend.md.
+
+## MANDATORY EXECUTION RULES
+
+- ONLY execute for client projects (`{seeding_strategy}` = "provider")
+- ALWAYS use factory methods (`NavigationModule.Create(...)`, etc.) - NEVER `new Entity()`
+- ALWAYS implement idempotence (check existence before inserting)
+- ALWAYS register the provider in DI
+- ALWAYS consume the SeedData classes created in steps 01-03
+
+## YOUR TASK
+
+Generate the `IClientSeedDataProvider` implementation that wires the SeedData files
+created in steps 01, 02, 03 into the SmartStack Core seeding pipeline.
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{level}` | context, application, module, or section |
+| `{code}` | kebab-case identifier |
+| `{full_path}` | Complete navigation path |
+| `{labels}` | Object with fr, en, it, de |
+| `{descriptions}` | Object with fr, en, it, de |
+| `{icon}` | Lucide icon name |
+| `{display_order}` | Numeric display order |
+| `{navigation_guid}` | GUID of the navigation entity |
+| `{permission_guids}` | GUIDs for generated permissions |
+| `{project_type}` | "client" (guaranteed at this step) |
+| `{seeding_strategy}` | "provider" (guaranteed at this step) |
+
+---
+
+## FILES TO GENERATE
+
+### 1. The Provider Class
+
+**Location:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
+
+Where `{AppPascalName}` is derived from the application code (e.g., `free-bike` -> `FreeBike`).
+
+**Pattern:**
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using SmartStack.Application.Common.Interfaces;
+using SmartStack.Domain.Navigation;
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
+
+/// <summary>
+/// Seeds {AppLabel} navigation, permissions, and role-permission data
+/// into the SmartStack Core schema at application startup.
+/// Implements <see cref="IClientSeedDataProvider"/> for runtime seeding
+/// (no Core migrations required).
+/// </summary>
+public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
+{
+    public int Order => 100;
+
+    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.NavigationApplications
+            .AnyAsync(a => a.Code == "{app_code}", ct);
+        if (exists) return;
+
+        // 1. Retrieve the parent context ("business", "platform", etc.)
+        var parentContext = await context.NavigationContexts
+            .FirstAsync(c => c.Code == "{context_code}", ct);
+
+        // 2. Create the application
+        var app = NavigationApplication.Create(
+            parentContext.Id,
+            "{app_code}",
+            "{app_label_en}",
+            "{app_desc_en}",
+            "{app_icon}",
+            IconType.Lucide,
+            "/{context_code}/{app_code}",
+            {display_order});
+        context.NavigationApplications.Add(app);
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // 3. Create modules
+        // Use GUIDs and data from {Module}NavigationSeedData.cs
+        foreach (var moduleData in GetModuleSeedEntries(app.Id))
+        {
+            var module = NavigationModule.Create(
+                moduleData.ApplicationId,
+                moduleData.Code,
+                moduleData.Label,
+                moduleData.Description,
+                moduleData.Icon,
+                IconType.Lucide,
+                moduleData.Route,
+                moduleData.DisplayOrder);
+            context.NavigationModules.Add(module);
+        }
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // 4. Create translations (4 languages per entity)
+        // Use data from {Module}NavigationTranslationSeedData.cs
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.Permissions
+            .AnyAsync(p => p.Path == "{full_path}.*", ct);
+        if (exists) return;
+
+        // Retrieve modules by Code for FK resolution
+        // Use data from {Module}PermissionSeedData.cs
+        // Create via Permission.CreateForModule(...) and Permission.CreateWildcard(...)
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.RolePermissions
+            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{full_path}."), ct);
+        if (exists) return;
+
+        // Retrieve existing roles and created permissions
+        // Use data from {Module}RolePermissionSeedData.cs
+        // Create via RolePermission.Create(roleId, permissionId, "system")
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    // Private helper methods fed by SeedData classes
+    // ...
+}
+```
+
+### 2. DI Registration
+
+Modify `Infrastructure/DependencyInjection.cs` of the client project:
+
+```csharp
+// Add using:
+using SmartStack.Application.Common.Interfaces;
+
+// In the registration method:
+services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
+```
+
+---
+
+## CRITICAL RULES
+
+1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` - NEVER `new Entity()`
+2. **Idempotence**: Each Seed method checks existence before inserting
+3. **SaveChangesAsync per group**: Navigation -> save -> Permissions -> save -> RolePermissions -> save
+4. **Deterministic GUIDs**: Use IDs from SeedData classes (not Guid.NewGuid())
+5. **Resolve FK by Code**: Parent modules are found by `Code`, not hardcoded GUID
+6. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Read SeedData files from steps 01-03
+
+Identify all SeedData files created in previous steps:
+
+```
+Glob: **/Persistence/Seeding/Data/{Domain}/*SeedData.cs
+```
+
+Expected files:
+- `{Module}NavigationSeedData.cs` (from step 01)
+- `{Module}NavigationTranslationSeedData.cs` (from step 01)
+- `{Module}PermissionSeedData.cs` (from step 02)
+- `{Module}RolePermissionSeedData.cs` (from step 03)
+
+### 2. Generate Provider Class
+
+Using the SeedData files as data sources, generate the `{AppPascalName}SeedDataProvider.cs` following the pattern above.
+
+Adapt the template:
+- Replace `{AppPascalName}` with the PascalCase application name
+- Replace `{app_code}` with the kebab-case application code
+- Replace `{context_code}` with the parent context code
+- Fill in the actual navigation, permission, and role-permission creation logic
+  using the helper methods from the SeedData classes
+
+### 3. Register in DI
+
+Find and update `Infrastructure/DependencyInjection.cs`:
+
+```
+Glob: **/Infrastructure/DependencyInjection.cs
+```
+
+Add the `IClientSeedDataProvider` registration.
+
+### 4. Verify
+
+Before proceeding to step-04, verify:
+- [ ] Provider generated with 3 methods (SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync)
+- [ ] Registered in DI (`services.AddScoped<IClientSeedDataProvider, ...>()`)
+- [ ] Consumes SeedData classes from steps 01-03
+- [ ] Idempotent (check existence before insert)
+- [ ] Uses factory methods (no `new Entity()`)
+
+---
+
+## SUCCESS METRICS
+
+- Provider class generated with all 3 seed methods
+- DI registration added
+- SeedData classes from steps 01-03 properly consumed
+- All methods are idempotent
+- Factory methods used throughout
+- Proceeded to step-04-backend.md
+
+## FAILURE MODES
+
+- SeedData files not found from previous steps (return to step-01)
+- DependencyInjection.cs not found (ask user for DI registration location)
+- Missing IClientSeedDataProvider interface (verify SmartStack.Application reference)
+
+---
+
+## NEXT STEP
+
+After generating the provider and registering it in DI,
+proceed to `./step-04-backend.md`

package/templates/skills/application/steps/step-04-backend.md

@@ -285,6 +285,80 @@ If MCP call fails:
 
 ---
 
+## POST-GENERATION VERIFICATION (MANDATORY)
+
+**Before proceeding to step-05, run these checks on ALL generated backend files:**
+
+### Check 1: Backend Build (BLOCKING)
+
+```bash
+dotnet build {SolutionName}.sln --no-restore
+```
+
+IF build fails:
+- Read the error output carefully
+- Fix compilation errors in generated files (common: missing `using`, wrong namespace, type mismatch)
+- Re-run build until it succeeds
+- DO NOT proceed to step-05 until the backend builds successfully
+
+### Check 2: DbSet Registration (BLOCKING)
+
+Verify the entity DbSet is registered in the DbContext interface:
+
+```
+Search for: DbSet<{EntityName}>
+In: **/I{DbContextName}.cs or **/{DbContextName}.cs
+```
+
+IF NOT found: Add the DbSet declaration immediately:
+```csharp
+public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();
+```
+
+### Check 3: DI Registration (BLOCKING)
+
+Verify the service is registered in the DI container:
+
+```
+Search for: I{EntityName}Service
+In: **/DependencyInjection.cs
+```
+
+IF NOT found: Add the service registration immediately:
+```csharp
+services.AddScoped<I{EntityName}Service, {EntityName}Service>();
+```
+
+### Check 4: RequirePermission Attributes (BLOCKING)
+
+Verify ALL controller actions have `[RequirePermission]` attributes:
+
+```
+Search for: [HttpGet], [HttpPost], [HttpPut], [HttpDelete]
+In: **/Controllers/**/{EntityName}Controller.cs
+```
+
+Each HTTP action MUST have a corresponding `[RequirePermission(Permissions.{Context}.{Application}.{Module}.{Action})]`.
+IF any action is missing the attribute: Add it immediately.
+
+### Check 5: Entity Configuration (BLOCKING)
+
+Verify the EF Core configuration file exists and has correct structure:
+
+```
+Search for: {EntityName}Configuration
+In: **/Persistence/Configurations/**/*Configuration.cs
+```
+
+Verify:
+- `builder.ToTable("{table_prefix}{EntityName}s")` uses the correct table prefix
+- `builder.HasKey(e => e.Id)` is present
+- `builder.HasIndex` is defined for unique fields (e.g., Code)
+
+IF configuration is incomplete: Fix it before continuing.
+
+---
+
 ## SUCCESS METRICS
 
 - MCP scaffold_extension called successfully
@@ -293,6 +367,7 @@ If MCP call fails:
 - NavRoute attribute included
 - Entity seeding offered to user (SeedData.cs + DevDataSeeder if accepted)
 - Entity info stored for frontend
+- Post-generation verification passed (all 5 checks)
 - Proceeded to step-05-frontend.md
 
 ## FAILURE MODES

package/templates/skills/application/steps/step-05-frontend.md

@@ -89,7 +89,50 @@ Args:
 
 This updates:
 - `navRoutes.generated.ts` - Route registry
-- `routes.tsx` - React Router configuration
+- `routes.tsx` / `App.tsx` - React Router configuration
+
+#### ⚠️ CRITICAL: Route Placement Inside Layout Wrapper
+
+**BLOCKING RULE:** New routes MUST be added as **children** of the existing layout route for the target context. SmartStack layouts (`AdminLayout`, `BusinessLayout`, `UserLayout`) provide the shell (header with AvatarMenu, sidebar, navigation) via React Router's `<Outlet />`.
+
+**If routes are placed OUTSIDE the layout wrapper, the entire shell (header, sidebar, AvatarMenu) will NOT render.**
+
+| Context | Layout Route to find in App.tsx | Layout Component |
+|---------|--------------------------------|------------------|
+| `platform.*` | `<Route path="/platform" element={<AdminLayout />}>` | `AdminLayout` |
+| `business.*` | `<Route path="/business" element={<BusinessLayout />}>` | `BusinessLayout` |
+| `personal.*` | `<Route path="/personal/myspace" element={<UserLayout />}>` | `UserLayout` |
+
+**Insertion rules:**
+
+1. Open `App.tsx` (or `routes.tsx`)
+2. Find the existing `<Route path="/{context}" element={<{Context}Layout />}>` block
+3. Add the new routes **INSIDE** that block as children
+4. Use **relative paths** (not absolute) since they are children of the context route
+
+```tsx
+// ✅ CORRECT - Route added INSIDE the layout wrapper
+<Route path="/business" element={<BusinessLayout />}>
+  {/* ... existing routes ... */}
+  <Route path="{application}/{module}" element={<{EntityName}Page />} />
+</Route>
+
+// ❌ FORBIDDEN - Route added OUTSIDE layout (AvatarMenu will disappear!)
+<Route path="/business/{application}/{module}" element={<{EntityName}Page />} />
+```
+
+**For new applications (no existing layout route for the context):**
+
+If the context doesn't have a layout route yet, create one wrapping all child routes:
+
+```tsx
+<Route path="/{context}/{application}" element={<{Context}Layout />}>
+  <Route index element={<Navigate to="{default_module}" replace />} />
+  <Route path="{module}" element={<{EntityName}Page />} />
+</Route>
+```
+
+**Remember:** Also add the routes inside the tenant-prefixed block (`/t/:slug/...`) if it exists.
 
 ### 4. Generate i18n Files
 
@@ -165,19 +208,37 @@ Repeat for en, it, de with appropriate translations.
 
 ## ROUTING RULES
 
-**CRITICAL:** SmartStack requires NESTED routes:
+### 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 - Nested routes
-<Route path="sales">
-  <Route index element={<Navigate to="products" replace />} />
-  <Route path="products" element={<ProductsPage />} />
-  <Route path="orders" element={<OrdersPage />} />
+// ✅ CORRECT - Inside BusinessLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/business" element={<BusinessLayout />}>
+  <Route path="sales/products" element={<ProductsPage />} />
 </Route>
 
-// ❌ FORBIDDEN - Flat routes (cause redirect issues)
-<Route path="sales" element={<Navigate to="products" />} />
-<Route path="sales/products" element={<ProductsPage />} />
+// ❌ FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
+<Route path="/business/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="/business" element={<BusinessLayout />}>
+  <Route path="sales">
+    <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="/business/sales" element={<Navigate to="products" />} />
+<Route path="/business/sales/products" element={<ProductsPage />} />
 ```
 
 ---
@@ -200,12 +261,88 @@ locales/
 
 ---
 
+## 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 Layout wrapper (`BusinessLayout`, `AdminLayout`, or `UserLayout`)
+- **NESTED** (not flat)
+- Following path convention: `/{context}/{application}/{module}`
+
+### 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/{context}/{application}/{module}/*.tsx`
+- `services/api/{entityCode}Api.ts`
+- `types/{entityName}.types.ts`
+- `hooks/use{EntityName}*.ts`
+
+---
+
 ## SUCCESS METRICS
 
 - React component generated
 - API client generated with types
 - Routes updated (nested structure)
 - i18n files created (4 languages)
+- Post-generation verification passed (all 7 checks including TypeScript build)
 - Proceeded to step-06-migration.md
 
 ## FAILURE MODES
@@ -213,6 +350,8 @@ locales/
 - Component generation failed (check entity name)
 - API client generation failed (check navRoute)
 - Route configuration failed (check existing routes)
+- Hardcoded colors detected → Fix before continuing
+- Missing language files → Generate all 4 before continuing
 
 ---
 

package/templates/skills/application/steps/step-06-migration.md

@@ -2,7 +2,7 @@
 name: step-06-migration
 description: Create EF Core migration and finalize application setup
 prev_step: steps/step-05-frontend.md
-next_step: null
+next_step: steps/step-07-tests.md
 ---
 
 # Step 6: Migration & Finalization
@@ -37,6 +37,29 @@ From previous steps:
 
 ## EXECUTION SEQUENCE
 
+### 0. 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
+```
+
+IF build fails:
+- Fix all compilation errors before proceeding
+- 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
+- Re-run build until successful
+- DO NOT attempt migration creation on a broken build
+
+**After build succeeds:** Continue to migration name suggestion.
+
 ### 1. Get Migration Name Suggestion
 
 ```
@@ -168,23 +191,12 @@ cd web && rm -rf node_modules/.cache && npm run dev
 
 ## SUCCESS METRICS
 
+- Pre-migration build verification passed
 - Migration name suggested via MCP
 - Migration created and applied
 - All checklist items verified
 - Application functional
 
-## COMPLETION
-
-The /application skill workflow is complete. The user now has:
-- Full navigation structure
-- RBAC permissions
-- Backend CRUD API
-- Frontend components
-- i18n support
-- Database migration
-
----
-
-## END OF WORKFLOW
+## NEXT STEP
 
-This is the final step. No further steps to proceed.
+After migration is applied and verified, proceed to `./step-07-tests.md` for test generation.