@atlashub/smartstack-cli 3.9.0 → 3.10.0

package/templates/skills/controller/steps/step-03-generate.md

@@ -1,48 +1,189 @@
 ---
 name: step-03-generate
-description: Generate controller file and DTOs
+description: Generate controller using MCP scaffold_extension with NavRoute
 next_step: steps/step-04-perms.md
 ---
 
 # Step 3: Generate Controller
 
-## YOUR TASK:
+## MANDATORY EXECUTION RULES
 
-Generate the controller file following SmartStack conventions. Use templates from `templates.md`.
+- ALWAYS use MCP `scaffold_extension` tool - NEVER use templates
+- ALWAYS generate Controller + DTOs as a unit
+- ALWAYS include NavRoute attribute for frontend/backend sync
+- YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+- MCP is the SOURCE OF TRUTH for code generation
 
-**ULTRA THINK about security and patterns.**
+## YOUR TASK
+
+Call the SmartStack MCP `scaffold_extension` tool with type "controller" to generate:
+1. API Controller with NavRoute attribute
+2. DTOs (Response, Create, Update)
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{area}` | Controller folder (Admin, Business, Support, User) |
+| `{module}` | kebab-case module identifier |
+| `{entity}` | Entity name (PascalCase) |
+| `{permission_path}` | Complete navigation path (navRoute) |
+| `{controller_type}` | crud, readonly, custom, auth |
 
 ---
 
-## EXECUTION SEQUENCE:
+## EXECUTION SEQUENCE
 
-### 1. Load Templates
+### 1. Derive Entity Name
 
-**Read template file:**
+Convert `{module}` to PascalCase for entity name:
 
 ```
-Read: templates/templates.md
+module: "products"        → entityName: "Product"
+module: "order-items"     → entityName: "OrderItem"
+module: "user-profiles"   → entityName: "UserProfile"
 ```
 
-**Select appropriate template based on {controller_type}:**
-- CRUD Controller template
-- Auth Controller template
-- ReadOnly Controller template
+### 2. Determine Table Prefix
+
+Based on navigation context extracted from `{permission_path}`:
+
+| Context | Table Prefix | Controller Folder |
+|---------|--------------|-------------------|
+| platform.administration | `auth_` or `cfg_` | `Admin` |
+| platform.support | `support_` | `Support` |
+| business.* | `ref_` or domain-specific | `Business` |
+| personal.* | `usr_` | `User` |
+
+### 3. Call MCP scaffold_extension (TWO CALLS)
+
+**First call: Generate DTOs**
+
+```
+Tool: mcp__smartstack__scaffold_extension
+Args:
+  type: "dto"
+  name: "{entityName}"  # PascalCase from step 1
+  options:
+    navRoute: "{permission_path}"  # For proper namespace hierarchy
+    schema: "core"
+    dryRun: false
+```
 
-### 2. Generate Controller File
+**Second call: Generate Controller with NavRoute**
 
-**Target path:**
 ```
-src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.cs
+Tool: mcp__smartstack__scaffold_extension
+Args:
+  type: "controller"
+  name: "{entityName}"  # PascalCase from step 1
+  options:
+    navRoute: "{permission_path}"  # MANDATORY for NavRoute attribute
+    navRouteSuffix: null            # Optional (e.g., "details" → [NavRoute("path", Suffix = "details")])
+    dryRun: false
 ```
-> Context mapping: `business` → `Business`, `platform` → `Admin`, `personal` → `User`
 
-See [references/controller-code-templates.md](../references/controller-code-templates.md) for all C# templates:
-- **Controller class** with DI constructor (IApplicationDbContext, ICurrentUserService, ILogger)
-- **GET endpoint** with pagination (PagedResult, AsNoTracking)
-- **DTOs** (CreateDto, UpdateDto, ResponseDto with entity mapping constructor)
-- **Security logging** (Create/Update at Info, Delete at Warning)
-- **System account protection** guard (UserType.System/LocalAdmin)
+**CRITICAL: NavRoute is MANDATORY** - Without it, frontend/backend sync will fail.
+
+**Why two calls?**
+- The skill `/controller` assumes the Entity already exists (verified in step-01-analyze.md)
+- Type "dto" generates DTOs without regenerating the Entity
+- Type "controller" generates the Controller with NavRoute and references to DTOs
+
+### 4. Parse MCP Responses
+
+**From first call (DTOs):**
+- `Application/{Context}/{Application}/{Module}/DTOs/{entityName}ResponseDto.cs` - Response DTO
+- `Application/{Context}/{Application}/{Module}/DTOs/Create{entityName}Dto.cs` - Create request
+- `Application/{Context}/{Application}/{Module}/DTOs/Update{entityName}Dto.cs` - Update request
+
+**From second call (Controller):**
+- `Api/Controllers/{area}/{entityName}Controller.cs` - REST Controller **with [NavRoute]**
+
+### 5. Present Output to User
+
+```markdown
+## Controller Generated via MCP
+
+### API Layer
+- `Controllers/{area}/{entityName}Controller.cs`
+  - **NavRoute: `{permission_path}`** ✅
+  - Endpoints:
+    - GET /api/{module} - List all
+    - GET /api/{module}/{id} - Get by ID
+    - POST /api/{module} - Create
+    - PUT /api/{module}/{id} - Update
+    - DELETE /api/{module}/{id} - Delete
+
+### Application Layer (DTOs)
+- `{Context}/{Application}/{Module}/DTOs/{entityName}ResponseDto.cs`
+- `{Context}/{Application}/{Module}/DTOs/Create{entityName}Dto.cs`
+- `{Context}/{Application}/{Module}/DTOs/Update{entityName}Dto.cs`
+
+### ✅ NavRoute Integration
+The controller uses `[NavRoute("{permission_path}")]` which enables:
+- ✅ Automatic frontend route generation
+- ✅ Permission-based navigation sync
+- ✅ Dynamic API routing from Navigation entities
+
+### Next Steps
+1. Permissions will be synchronized in step-04-perms.md
+2. Validate conventions with MCP `validate_conventions`
+```
+
+---
+
+## MCP RESPONSE HANDLING
+
+### Success Case
+
+**After first call (DTOs):**
+- Display all generated DTO files
+- Verify DTOs match entity properties
+- Continue to second call
+
+**After second call (Controller):**
+- Display controller file
+- Show NavRoute attribute included
+- Highlight frontend/backend sync enabled
+- Store controller info for permission sync
+- Proceed to step-04-perms.md
+
+### Error Case
+
+**If first call (DTOs) fails:**
+- Display error message
+- Suggest checking entity name format
+- Verify entity properties are defined
+- Verify MCP server is running (`/mcp:healthcheck`)
+- Do NOT proceed to second call
+
+**If second call (Controller) fails:**
+- Display error message
+- Note that DTOs were generated successfully
+- Suggest checking navRoute format
+- Verify MCP server is running (`/mcp:healthcheck`)
+- Do NOT proceed to step-04-perms.md
+
+---
+
+## NAVROUTE VALIDATION
+
+**After generation, verify NavRoute is present:**
+
+```
+Generated controller MUST contain:
+[NavRoute("{permission_path}")]
+
+WITHOUT NavRoute:
+❌ Frontend routes will be hardcoded
+❌ No automatic permission sync
+❌ Manual navigation management required
+```
 
 ---
 
@@ -53,7 +194,7 @@ Generated Files:
 
 | File | Path | Status |
 |------|------|--------|
-| Controller | src/.../Controllers/{area}/{module}Controller.cs | ✅ Created |
+| Controller | src/.../Controllers/{area}/{entity}Controller.cs | ✅ Created with [NavRoute] |
 | CreateDto | src/.../DTOs/{module}/{entity}CreateDto.cs | ✅ Created |
 | UpdateDto | src/.../DTOs/{module}/{entity}UpdateDto.cs | ✅ Created |
 | ResponseDto | src/.../DTOs/{module}/{entity}ResponseDto.cs | ✅ Created |
@@ -63,6 +204,25 @@ Generated Files:
 
 ---
 
+## SUCCESS METRICS
+
+- MCP scaffold_extension called successfully (DTOs)
+- DTOs generated (ResponseDto, CreateDto, UpdateDto)
+- MCP scaffold_extension called successfully (Controller)
+- Controller generated with **[NavRoute]** attribute
+- NavRoute matches permission_path
+- Controller references DTOs correctly
+- Proceeded to step-04-perms.md
+
+## FAILURE MODES
+
+- MCP call failed (display error, run /mcp:healthcheck, stop)
+- Invalid entity name (must be PascalCase)
+- Invalid navRoute format
+- MCP server not running
+
+---
+
 ## NEXT STEP:
 
-After generation complete, proceed to `./step-04-perms.md`
+After controller generation complete, proceed to `./step-04-perms.md`

package/templates/skills/controller/templates.md

@@ -1,7 +1,16 @@
 # SmartStack Controller Templates
 
-> **Note:** These templates are used by the `controller` skill and `/controller:create` command.
-> Adapt variables `{Area}`, `{Module}`, `{Entity}`, `{PermissionPath}` according to context.
+> **⚠️ OBSOLETE - DO NOT USE THESE TEMPLATES MANUALLY**
+>
+> **The `/controller` skill now uses the MCP `scaffold_extension` tool to generate controllers.**
+> These templates are kept for reference only. All controller generation MUST go through the MCP to ensure:
+> - ✅ `[NavRoute]` attribute is included for frontend/backend sync
+> - ✅ Permissions are correctly generated
+> - ✅ Consistency with SmartStack conventions
+>
+> **To generate a controller, use:** `/controller` skill which calls MCP `scaffold_extension` automatically.
+>
+> **If you modify these templates, they will NOT be used.** The MCP templates in `templates/mcp-scaffolding/controller.cs.hbs` are the source of truth.
 
 ---
 

package/templates/skills/ralph-loop/references/core-seed-data.md

@@ -279,7 +279,129 @@ If MCP `generate_permissions` fails, use the template above directly with values
 
 ---
 
-## 4. RolesSeedData.cs
+## 4. ApplicationRolesSeedData.cs (Application-Level, Once per Application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+### Purpose
+
+Creates the 4 standard application-scoped roles: Admin, Manager, Contributor, Viewer.
+
+**CRITICAL:** This file is created **ONCE per application** (not per module).
+Without these roles, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently.
+
+### GUID Generation Rule
+
+```csharp
+// Deterministic GUID from application ID + role type
+private static Guid GenerateRoleGuid(string roleType)
+{
+    using var sha256 = System.Security.Cryptography.SHA256.Create();
+    var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"role-{ApplicationId}-{roleType}"));
+    return new Guid(hash.Take(16).ToArray());
+}
+// roleType values: "admin", "manager", "contributor", "viewer"
+```
+
+### Template
+
+```csharp
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+
+/// <summary>
+/// Application-scoped role seed data for {AppLabel}.
+/// Defines the 4 standard application roles: Admin, Manager, Contributor, Viewer.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class ApplicationRolesSeedData
+{
+    // Application ID from NavigationApplicationSeedData
+    private static readonly Guid ApplicationId = {ApplicationGuid};
+
+    public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
+    public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
+    public static readonly Guid ContributorRoleId = GenerateRoleGuid("contributor");
+    public static readonly Guid ViewerRoleId = GenerateRoleGuid("viewer");
+
+    public static IEnumerable<ApplicationRoleSeedEntry> GetRoleEntries()
+    {
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = AdminRoleId,
+            Code = "admin",
+            Name = "{AppLabel} Admin",
+            Description = "Full administrative access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 1
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ManagerRoleId,
+            Code = "manager",
+            Name = "{AppLabel} Manager",
+            Description = "Management access to {AppLabel} (Create, Read, Update)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 2
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ContributorRoleId,
+            Code = "contributor",
+            Name = "{AppLabel} Contributor",
+            Description = "Contributor access to {AppLabel} (Create, Read)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 3
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ViewerRoleId,
+            Code = "viewer",
+            Name = "{AppLabel} Viewer",
+            Description = "Read-only access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 4
+        };
+    }
+
+    private static Guid GenerateRoleGuid(string roleType)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"role-{ApplicationId}-{roleType}"));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+public class ApplicationRoleSeedEntry
+{
+    public Guid Id { get; init; }
+    public string Code { get; init; } = null!;
+    public string Name { get; init; } = null!;
+    public string Description { get; init; } = null!;
+    public Guid ApplicationId { get; init; }
+    public bool IsSystem { get; init; }
+    public bool IsActive { get; init; }
+    public int DisplayOrder { get; init; }
+}
+```
+
+**Replace placeholders** with values from PRD and navigation metadata.
+
+---
+
+## 5. {Module}RolesSeedData.cs (Per Module)
 
 **File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/RolesSeedData.cs`
 
@@ -335,7 +457,7 @@ public class RolePermissionSeedEntry
 
 ---
 
-## 5. IClientSeedDataProvider Implementation
+## 6. IClientSeedDataProvider Implementation
 
 **File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
 
@@ -343,10 +465,11 @@ public class RolePermissionSeedEntry
 
 | Rule | Description |
 |------|-------------|
-| Factory methods | `NavigationModule.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()` |
+| Factory methods | `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()` |
 | Idempotence | Each Seed method checks existence before inserting |
-| SaveChanges per group | Navigation -> save -> Permissions -> save -> RolePermissions -> save |
-| FK resolution by Code | Parent entities found by `Code`, not hardcoded GUID |
+| Execution order | Navigation → Roles → Permissions → RolePermissions (roles MUST exist before mapping) |
+| SaveChanges per group | Navigation -> save -> Roles -> save -> Permissions -> save -> RolePermissions -> save |
+| FK resolution by Code | Parent entities (modules, roles) found by `Code`, not hardcoded GUID |
 | DI registration | `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()` |
 
 ### Template
@@ -357,13 +480,14 @@ using SmartStack.Application.Common.Interfaces;
 using SmartStack.Application.Common.Interfaces.Seeding;
 using SmartStack.Domain.Navigation;
 using SmartStack.Domain.Platform.Administration.Roles;
+using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
 using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{Module1Pascal};
 // using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{Module2Pascal}; // Add per module
 
 namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
 
 /// <summary>
-/// Seeds {AppLabel} navigation, permissions, and role-permission data
+/// Seeds {AppLabel} navigation, roles, permissions, and role-permission data
 /// into the SmartStack Core schema at application startup.
 /// </summary>
 public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
@@ -420,6 +544,28 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         await ((DbContext)context).SaveChangesAsync(ct);
     }
 
+    public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var applicationId = ApplicationRolesSeedData.ApplicationId;
+        var exists = await context.Roles
+            .AnyAsync(r => r.ApplicationId == applicationId, ct);
+        if (exists) return;
+
+        // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
+        foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
+        {
+            var role = Role.Create(
+                entry.Code,
+                entry.Name,
+                entry.Description,
+                entry.ApplicationId,
+                entry.IsSystem);
+            context.Roles.Add(role);
+        }
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
     public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
     {
         var exists = await context.Permissions
@@ -495,43 +641,49 @@ services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
 
 ---
 
-## 6. Multi-Module Handling
+## 7. Multi-Module Handling
 
 When processing multiple modules in the same ralph-loop run:
 
 ### Module 1 (first): Creates everything from scratch
 
-1. `{Module1}NavigationSeedData.cs`
-2. `{Module1}PermissionsSeedData.cs`
-3. `{Module1}RolesSeedData.cs`
-4. `{AppPascalName}SeedDataProvider.cs` (new)
-5. DI registration (new)
+1. `ApplicationRolesSeedData.cs` (application-level, once per app)
+2. `{Module1}NavigationSeedData.cs`
+3. `{Module1}PermissionsSeedData.cs`
+4. `{Module1}RolesSeedData.cs`
+5. `{AppPascalName}SeedDataProvider.cs` (new, with 4 methods)
+6. DI registration (new)
 
 ### Module 2+ (subsequent): Append to existing provider
 
-1. `{Module2}NavigationSeedData.cs` (new file)
-2. `{Module2}PermissionsSeedData.cs` (new file)
-3. `{Module2}RolesSeedData.cs` (new file)
-4. `{AppPascalName}SeedDataProvider.cs` (**modify** — add using, add entries in each Seed method)
-5. DI registration (already exists — skip)
+1. `ApplicationRolesSeedData.cs` (already exists — skip)
+2. `{Module2}NavigationSeedData.cs` (new file)
+3. `{Module2}PermissionsSeedData.cs` (new file)
+4. `{Module2}RolesSeedData.cs` (new file)
+5. `{AppPascalName}SeedDataProvider.cs` (**modify** — add using, add entries in Navigation/Permissions/RolePermissions methods)
+6. DI registration (already exists — skip)
 
-**Detection:** Check if `{AppPascalName}SeedDataProvider.cs` exists. If yes, READ it and ADD the new module's entries to each of the 3 methods.
+**Detection:** Check if `{AppPascalName}SeedDataProvider.cs` exists. If yes, READ it and ADD the new module's entries to the appropriate methods (Navigation, Permissions, RolePermissions). Do NOT modify SeedRolesAsync().
 
 ---
 
-## 7. Verification Checklist (BLOCKING)
+## 8. Verification Checklist (BLOCKING)
 
 Before marking the task as completed, verify ALL:
 
 - [ ] Deterministic GUIDs (NEVER `Guid.NewGuid()`) — SHA256 of path
 - [ ] 4 languages for each navigation entity (fr, en, it, de)
+- [ ] `ApplicationRolesSeedData.cs` created (once per application)
+- [ ] 4 application roles defined: Admin, Manager, Contributor, Viewer
+- [ ] Each role has a valid `Code` value ("admin", "manager", "contributor", "viewer")
 - [ ] `Permissions.cs` constants match seed data paths
 - [ ] MCP `generate_permissions` called (or fallback used)
 - [ ] Role-permission mappings assigned (Admin, Manager, Contributor, Viewer)
-- [ ] `IClientSeedDataProvider` generated with 3 methods
+- [ ] `IClientSeedDataProvider` generated with 4 methods (Navigation, Roles, Permissions, RolePermissions)
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
 - [ ] Each Seed method is idempotent (checks existence before inserting)
 - [ ] Factory methods used throughout (NEVER `new Entity()`)
-- [ ] `SaveChangesAsync` called per group (Navigation → Permissions → RolePermissions)
+- [ ] `SaveChangesAsync` called per group (Navigation → Roles → Permissions → RolePermissions)
 - [ ] DI registration added: `services.AddScoped<IClientSeedDataProvider, ...>()`
 - [ ] `dotnet build` passes after generation