@atlashub/smartstack-cli 3.36.0 → 3.38.0

package/templates/skills/application/references/init-parameter-detection.md

@@ -0,0 +1,120 @@
+# 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) |
+
+---
+
+## Parameter Extraction
+
+Required parameters to extract:
+
+```yaml
+# Required
+level: application | module | section
+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" (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

@@ -0,0 +1,100 @@
+# 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)
+- Navigation translations (4 languages)
+- Permissions (CRUD + wildcard)
+- RolePermissions (role assignments)
+- Domain entity table
+- Indexes and constraints
+- SQL Objects injection (if any .sql files exist)
+
+---
+
+## SQL Objects Injection
+
+Check if any SQL object files exist:
+```
+Glob: **/Persistence/SqlObjects/Functions/*.sql
+```
+
+If SQL files are found, the migration's `Up()` method should include a call to re-apply all SQL objects:
+```csharp
+// At the end of the Up() method:
+SqlObjectHelper.ApplyAll(migrationBuilder);
+```
+
+This ensures SQL functions/views are re-applied with each migration (`CREATE OR ALTER` = idempotent).
+
+---
+
+## 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
+- [ ] SQL objects injected (if applicable)
+- [ ] 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

@@ -25,7 +25,7 @@
 
 3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
    ```
-   Read the Configuration for the target level (Context, Application, Module, Section).
+   Read the Configuration for the target level (Application, Module, Section).
    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.
@@ -39,11 +39,11 @@
 
 ## F2. Determine Parent GUID
 
-For non-context levels, find the parent entity GUID:
+For non-application levels, find the parent entity GUID:
 
 | Level | Parent | Where to Find Parent GUID |
 |-------|--------|---------------------------|
-| application | context | `NavigationContextSeedData.cs` → e.g. `PlatformContextId` |
+| application | (none — top level) | — |
 | module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
 | section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
 
@@ -99,8 +99,7 @@ new {
 
 | Level | FK Property | References |
 |-------|-------------|------------|
-| context | (none) | - |
-| application | `ContextId` | NavigationContextSeedData.{Parent}Id |
+| application | (none — top level) | — |
 | module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
 | section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
 
@@ -180,7 +179,7 @@ Before proceeding, verify:
 - [ ] 4 languages present (fr, en, it, de)
 - [ ] Translation index continues existing sequence (no gaps, no collisions)
 - [ ] Parent GUID correctly references existing entity
-- [ ] Route path matches `/{context}/{app}/{module}` pattern
+- [ ] Route path matches `/{app}/{module}` pattern
 - [ ] DisplayOrder is consistent with existing entities
 - [ ] Code is WRITTEN to files, not just displayed
 

package/templates/skills/application/references/provider-template.md

@@ -31,7 +31,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
     {
         // --- Application (idempotent — reuse if already exists) ---
-        var appEntry = NavigationApplicationSeedData.GetApplicationEntry(Guid.Empty);
+        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
         var existingApp = await context.NavigationApplications
             .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
 
@@ -42,12 +42,8 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         }
         else
         {
-            var parentContext = await context.NavigationContexts
-                .FirstAsync(c => c.Code == "{context_code}", ct);
-
-            appEntry = NavigationApplicationSeedData.GetApplicationEntry(parentContext.Id);
             app = NavigationApplication.Create(
-                appEntry.ContextId, appEntry.Code, appEntry.Label,
+                appEntry.Code, appEntry.Label,
                 appEntry.Description, appEntry.Icon, appEntry.IconType,
                 appEntry.Route, appEntry.DisplayOrder);
             context.NavigationApplications.Add(app);

package/templates/skills/application/references/roles-client-project-handling.md

@@ -0,0 +1,55 @@
+# Step 3: Client Project Handling (seeding_strategy = "provider")
+
+> Referenced from `steps/step-03-roles.md` — Specific handling for client projects.
+
+---
+
+## ApplicationRolesSeedData.cs (ONCE per application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
+
+**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
+
+See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
+
+**Key requirements:**
+- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
+- 4 roles: Admin, Manager, Contributor, Viewer
+- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
+- `ApplicationId` references the navigation application GUID
+- `IsSystem = false` (application-scoped, not system roles)
+
+**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
+
+---
+
+## {Module}RolePermissionSeedData.cs (PER module)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
+
+Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
+These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
+
+---
+
+## Default Role Mapping Table
+
+Based on navigation application prefix:
+
+| Application prefix | PlatformAdmin | TenantAdmin | StandardUser |
+|---------|---------------|-------------|--------------|
+| `administration.*` | Full CRUD | Read only | None |
+| `*` (business apps) | Full CRUD | Full CRUD | Read only |
+| `myspace.*` | None | Full CRUD | Full CRUD |
+
+---
+
+## Summary
+
+After creating both files:
+- Proceed to step-03b-provider.md (which will skip for core projects)
+- The provider will consume these SeedData files to seed roles and permissions at runtime

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

@@ -0,0 +1,149 @@
+# Role-Permission Generation: Fallback Procedure (When MCP Unavailable)
+
+> Reference for step-03-roles.md — Generates role-permission HasData entries following SmartStack.app patterns.
+
+---
+
+## F1. Read Existing RolePermissionConfiguration.cs
+
+```
+Glob: **/Persistence/Configurations/Authorization/RolePermissionConfiguration.cs
+```
+
+Read the file to determine:
+- Existing role-permission mappings
+- The GetSeedData() method structure
+- Which roles already have which permissions
+- The GUID generation method used (deterministic or hardcoded)
+
+---
+
+## F2. Read Role GUIDs
+
+**System-level roles** (well-known GUIDs):
+
+| Role | GUID |
+|------|------|
+| SuperAdmin | `11111111-1111-1111-1111-111111111111` |
+| PlatformAdmin | `22222222-2222-2222-2222-222222222222` |
+| TenantAdmin | `33333333-3333-3333-3333-333333333333` |
+| StandardUser | `44444444-4444-4444-4444-444444444444` |
+
+**IMPORTANT:** Read the actual `RoleSeedData.cs` or `RoleConfiguration.cs` in the target project to confirm the actual role GUIDs. The above are defaults; the project may use different values.
+
+**Application-scoped roles** (deterministic GUIDs based on application):
+
+```csharp
+// Read the existing GenerateDeterministicGuid method in RolePermissionConfiguration.cs
+// Typically uses MD5 hash:
+private static Guid GenerateDeterministicGuid(Guid applicationId, string roleType)
+{
+    using var md5 = System.Security.Cryptography.MD5.Create();
+    var input = $"{applicationId}-{roleType}";
+    var hash = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(input));
+    return new Guid(hash);
+}
+// roleType values: "admin", "manager", "contributor", "viewer"
+```
+
+Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
+
+---
+
+## F3. Determine Application-Based Default Mappings
+
+Based on `{full_path}` application prefix:
+
+| Application Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
+|----------------|------------|---------------|-----------|-------------|-----------------|------------|
+| `administration.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `*` (business apps) | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `myspace.*` | wildcard | None | Full CRUD | CRU | CR | R |
+
+---
+
+## F4. Generate RolePermission HasData Entries
+
+Using `{permission_guids}` from step-02:
+
+```csharp
+// In RolePermissionConfiguration.cs - GetSeedData() method
+var seedDate = SeedConstants.SeedDate;
+
+// ============================================================
+// {MODULE_NAME} PERMISSIONS
+// ============================================================
+
+// SuperAdmin: already has *.* wildcard - no individual entries needed
+
+// PlatformAdmin (for platform.* context)
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.delete}, AssignedAt = seedDate });
+
+// Application-scoped: Admin → wildcard
+rolePermissions.Add(new { RoleId = appAdminRoleId, PermissionId = {permission_guids.wildcard}, AssignedAt = seedDate });
+
+// Application-scoped: Manager → CRU (read + create + update — no delete)
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
+
+// Application-scoped: Contributor → CR
+rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+
+// Application-scoped: Viewer → R
+rolePermissions.Add(new { RoleId = appViewerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+```
+
+---
+
+## F5. Write Code to RolePermissionConfiguration.cs
+
+**CRITICAL:** Do NOT just display code. WRITE it to the actual file.
+
+1. Open `RolePermissionConfiguration.cs`
+2. Find the `GetSeedData()` method
+3. Add the new role-permission entries to the list
+4. Add necessary permission GUID references (import from PermissionConfiguration or use inline)
+5. Add comments grouping the new entries: `// {MODULE_NAME} PERMISSIONS`
+
+---
+
+## F6. Present Summary
+
+```markdown
+## Role-Permission Mappings Generated (Fallback)
+
+| Role | Permissions |
+|------|-------------|
+| SuperAdmin | Already has wildcard access |
+| PlatformAdmin | {full_path}.read, .create, .update, .delete |
+| App Admin | {full_path}.* (wildcard) |
+| App Manager | {full_path}.read, .create, .update |
+| App Contributor | {full_path}.read, .create |
+| App Viewer | {full_path}.read |
+
+Written to: RolePermissionConfiguration.cs
+```
+
+---
+
+## F7. Offer User Adjustment
+
+If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
+
+---
+
+## Validation Checklist
+
+Before marking as completed, verify:
+
+- [ ] All role GUIDs correctly identified (system and application-scoped)
+- [ ] Role-permission mappings follow application hierarchy
+- [ ] Code WRITTEN to files (not just displayed)
+- [ ] Permission GUID references correct
+- [ ] Comments added for module grouping
+- [ ] No gaps or missing permissions