@atlashub/smartstack-cli 3.8.0 → 3.10.0

package/templates/skills/controller/references/permission-sync-templates.md

@@ -0,0 +1,152 @@
+# Permission Synchronization Templates
+
+> Referenced from `steps/step-04-perms.md` — C# code templates for Permissions.cs, PermissionConfiguration.cs, and Postman tests.
+
+---
+
+## Permissions.cs Template
+
+**Target file:** `src/SmartStack.Application/Common/Authorization/Permissions.cs`
+
+**Find the correct parent class based on `{permission_path}`:**
+
+| Permission Path | Parent Class |
+|-----------------|--------------|
+| `platform.administration.*` | `Platform.Administration` |
+| `platform.support.*` | `Platform.Support` |
+| `business.*` | `Business` |
+| `personal.myspace.*` | `Personal.MySpace` |
+
+**Add nested class:**
+
+```csharp
+public static class {module}
+{
+    public const string View = "{permission_path}.read";
+    public const string Create = "{permission_path}.create";
+    public const string Update = "{permission_path}.update";
+    public const string Delete = "{permission_path}.delete";
+}
+```
+
+**Example for platform.support.tickets:**
+
+```csharp
+public static partial class Permissions
+{
+    public static class Platform
+    {
+        public static class Support
+        {
+            // Existing classes...
+
+            public static class Tickets  // NEW
+            {
+                public const string View = "platform.support.tickets.read";
+                public const string Create = "platform.support.tickets.create";
+                public const string Update = "platform.support.tickets.update";
+                public const string Delete = "platform.support.tickets.delete";
+            }
+        }
+    }
+}
+```
+
+---
+
+## PermissionConfiguration.cs Template
+
+**Target file:** `src/SmartStack.Infrastructure/Persistence/Configurations/PermissionConfiguration.cs`
+
+**Find HasData section and add seeds:**
+
+```csharp
+builder.HasData(
+    // Existing permissions...
+
+    // {module} permissions
+    new Permission
+    {
+        Id = Guid.NewGuid(), // Generate new GUID
+        Code = "{permission_path}.read",
+        Name = "View {module}",
+        Description = "Allows viewing {module_lowercase} list and details",
+        Category = "{area}",
+        IsSystem = true,
+        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
+    },
+    new Permission
+    {
+        Id = Guid.NewGuid(),
+        Code = "{permission_path}.create",
+        Name = "Create {module}",
+        Description = "Allows creating new {module_lowercase}",
+        Category = "{area}",
+        IsSystem = true,
+        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
+    },
+    new Permission
+    {
+        Id = Guid.NewGuid(),
+        Code = "{permission_path}.update",
+        Name = "Update {module}",
+        Description = "Allows updating existing {module_lowercase}",
+        Category = "{area}",
+        IsSystem = true,
+        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
+    },
+    new Permission
+    {
+        Id = Guid.NewGuid(),
+        Code = "{permission_path}.delete",
+        Name = "Delete {module}",
+        Description = "Allows deleting {module_lowercase}",
+        Category = "{area}",
+        IsSystem = true,
+        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
+    }
+);
+```
+
+---
+
+## Postman Test Templates
+
+**If `{postman_mode}` = true, generate API tests:**
+
+```json
+{
+  "name": "{module} API Tests",
+  "item": [
+    {
+      "name": "GET {module} - SuperAdmin (200)",
+      "request": {
+        "method": "GET",
+        "url": "{{baseUrl}}/api/{area}/{module}"
+      },
+      "event": [
+        {
+          "listen": "test",
+          "script": {
+            "exec": ["pm.test('Status 200', () => pm.response.to.have.status(200));"]
+          }
+        }
+      ]
+    },
+    {
+      "name": "GET {module} - No Permission (403)",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/{area}/{module}" },
+      "event": [
+        {
+          "listen": "prerequest",
+          "script": { "exec": ["// Use NoPermUser token"] }
+        },
+        {
+          "listen": "test",
+          "script": { "exec": ["pm.test('Status 403', () => pm.response.to.have.status(403));"] }
+        }
+      ]
+    }
+  ]
+}
+```

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

@@ -1,199 +1,188 @@
 ---
 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)
 
 ---
 
-## EXECUTION SEQUENCE:
+## AVAILABLE STATE
 
-### 1. Load Templates
+From previous steps:
 
-**Read template file:**
+| 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 |
 
-```
-Read: templates/templates.md
-```
+---
 
-**Select appropriate template based on {controller_type}:**
-- CRUD Controller template
-- Auth Controller template
-- ReadOnly Controller template
+## EXECUTION SEQUENCE
 
-### 2. Generate Controller File
+### 1. Derive Entity Name
+
+Convert `{module}` to PascalCase for entity name:
 
-**Target path:**
-```
-src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.cs
 ```
-> Context mapping: `business` → `Business`, `platform` → `Admin`, `personal` → `User`
-
-**Apply template with variables:**
-
-```csharp
-using Microsoft.AspNetCore.Mvc;
-using Microsoft.AspNetCore.Http;
-using SmartStack.Application.Common.Authorization;
-using SmartStack.Application.Common.Interfaces;
-using SmartStack.Domain.Entities;
-
-namespace SmartStack.Api.Controllers.{area};
-
-[ApiController]
-[Route("api/{area_lowercase}/[controller]")]
-[Authorize]
-public class {module}Controller : ControllerBase
-{
-    private readonly IApplicationDbContext _context;
-    private readonly ICurrentUserService _currentUser;
-    private readonly ILogger<{module}Controller> _logger;
-
-    public {module}Controller(
-        IApplicationDbContext context,
-        ICurrentUserService currentUser,
-        ILogger<{module}Controller> logger)
-    {
-        _context = context;
-        _currentUser = currentUser;
-        _logger = logger;
-    }
-
-    // Endpoints generated based on plan...
-}
+module: "products"        → entityName: "Product"
+module: "order-items"     → entityName: "OrderItem"
+module: "user-profiles"   → entityName: "UserProfile"
 ```
 
-### 3. Generate Endpoints
-
-**For each planned endpoint, generate with:**
-
-1. **Attributes:**
-   - `[HttpGet]`, `[HttpPost]`, etc.
-   - `[RequirePermission(Permissions.{module}.View)]`
-   - `[ProducesResponseType(typeof(...), StatusCodes.Status200OK)]`
-   - `[ProducesResponseType(StatusCodes.Status401Unauthorized)]`
-   - `[ProducesResponseType(StatusCodes.Status403Forbidden)]`
-
-2. **Method body:**
-   - Parameter validation
-   - Entity operation
-   - Logging
-   - Response mapping
-
-**Example GET endpoint:**
-
-```csharp
-[HttpGet]
-[RequirePermission(Permissions.{module}.View)]
-[ProducesResponseType(typeof(PagedResult<{entity}ResponseDto>), StatusCodes.Status200OK)]
-[ProducesResponseType(StatusCodes.Status401Unauthorized)]
-[ProducesResponseType(StatusCodes.Status403Forbidden)]
-public async Task<IActionResult> GetAll(
-    [FromQuery] int page = 1,
-    [FromQuery] int pageSize = 20,
-    CancellationToken ct = default)
-{
-    var query = _context.{module}
-        .AsNoTracking()
-        .OrderByDescending(x => x.CreatedAt);
-
-    var total = await query.CountAsync(ct);
-    var items = await query
-        .Skip((page - 1) * pageSize)
-        .Take(pageSize)
-        .Select(x => new {entity}ResponseDto(x))
-        .ToListAsync(ct);
-
-    return Ok(new PagedResult<{entity}ResponseDto>(items, total, page, pageSize));
-}
-```
+### 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` |
 
-### 4. Generate DTOs (if dto_mode)
+### 3. Call MCP scaffold_extension (TWO CALLS)
+
+**First call: Generate DTOs**
 
-**Target paths:**
 ```
-src/SmartStack.Application/DTOs/{module}/{entity}CreateDto.cs
-src/SmartStack.Application/DTOs/{module}/{entity}UpdateDto.cs
-src/SmartStack.Application/DTOs/{module}/{entity}ResponseDto.cs
+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
 ```
 
-**CreateDto template:**
+**Second call: Generate Controller with NavRoute**
 
-```csharp
-public record {entity}CreateDto(
-    string Name,
-    // ... required properties
-);
+```
+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
 ```
 
-**UpdateDto template:**
+**CRITICAL: NavRoute is MANDATORY** - Without it, frontend/backend sync will fail.
 
-```csharp
-public record {entity}UpdateDto(
-    string? Name,
-    // ... optional properties
-);
-```
+**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
 
-**ResponseDto template:**
-
-```csharp
-public record {entity}ResponseDto(
-    Guid Id,
-    string Name,
-    // ... all public properties
-    DateTime CreatedAt,
-    DateTime? UpdatedAt
-)
-{
-    public {entity}ResponseDto({entity} entity) : this(
-        entity.Id,
-        entity.Name,
-        // ... mapping
-        entity.CreatedAt,
-        entity.UpdatedAt
-    ) { }
-}
-```
+### 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
 
-### 5. Add Security Logging
+**From second call (Controller):**
+- `Api/Controllers/{area}/{entityName}Controller.cs` - REST Controller **with [NavRoute]**
 
-**Ensure logging for all operations:**
+### 5. Present Output to User
 
-```csharp
-// Create
-_logger.LogInformation("User {User} created {entity} {Id}",
-    _currentUser.Email, entity.Id);
+```markdown
+## Controller Generated via MCP
 
-// Update
-_logger.LogInformation("User {User} updated {entity} {Id}",
-    _currentUser.Email, entity.Id);
+### 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
 
-// Delete (Warning level)
-_logger.LogWarning("User {User} deleted {entity} {Id} ({Name})",
-    _currentUser.Email, id, entity.Name);
+### 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`
 ```
 
-### 6. Protect System Accounts (if applicable)
+---
+
+## MCP RESPONSE HANDLING
 
-**Add guard for system entities:**
+### 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:**
 
-```csharp
-// Before modify/delete operations
-if (entity.UserType == UserType.System || entity.UserType == UserType.LocalAdmin)
-{
-    _logger.LogWarning("Attempt to modify system account {Id} by {User}",
-        entity.Id, _currentUser.Email);
-    return BadRequest(new { message = "Cannot modify system accounts" });
-}
+```
+Generated controller MUST contain:
+[NavRoute("{permission_path}")]
+
+WITHOUT NavRoute:
+❌ Frontend routes will be hardcoded
+❌ No automatic permission sync
+❌ Manual navigation management required
 ```
 
 ---
@@ -205,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 |
@@ -215,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/steps/step-04-perms.md

@@ -16,113 +16,11 @@ Add permissions to both Permissions.cs (constants) and PermissionConfiguration.c
 
 ## EXECUTION SEQUENCE:
 
-### 1. Update Permissions.cs
+### 1. Update Permissions.cs & PermissionConfiguration.cs
 
-**Target file:**
-```
-src/SmartStack.Application/Common/Authorization/Permissions.cs
-```
-
-**Find the correct parent class based on {permission_path}:**
-
-| Permission Path | Parent Class |
-|-----------------|--------------|
-| `platform.administration.*` | `Platform.Administration` |
-| `platform.support.*` | `Platform.Support` |
-| `business.*` | `Business` |
-| `personal.myspace.*` | `Personal.MySpace` |
-
-**Add nested class:**
-
-```csharp
-public static class {module}
-{
-    public const string View = "{permission_path}.read";
-    public const string Create = "{permission_path}.create";
-    public const string Update = "{permission_path}.update";
-    public const string Delete = "{permission_path}.delete";
-}
-```
-
-**Example for platform.support.tickets:**
-
-```csharp
-public static partial class Permissions
-{
-    public static class Platform
-    {
-        public static class Support
-        {
-            // Existing classes...
-
-            public static class Tickets  // NEW
-            {
-                public const string View = "platform.support.tickets.read";
-                public const string Create = "platform.support.tickets.create";
-                public const string Update = "platform.support.tickets.update";
-                public const string Delete = "platform.support.tickets.delete";
-            }
-        }
-    }
-}
-```
-
-### 2. Update PermissionConfiguration.cs
-
-**Target file:**
-```
-src/SmartStack.Infrastructure/Persistence/Configurations/PermissionConfiguration.cs
-```
-
-**Find HasData section and add seeds:**
-
-```csharp
-builder.HasData(
-    // Existing permissions...
-
-    // {module} permissions
-    new Permission
-    {
-        Id = Guid.NewGuid(), // Generate new GUID
-        Code = "{permission_path}.read",
-        Name = "View {module}",
-        Description = "Allows viewing {module_lowercase} list and details",
-        Category = "{area}",
-        IsSystem = true,
-        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
-    },
-    new Permission
-    {
-        Id = Guid.NewGuid(),
-        Code = "{permission_path}.create",
-        Name = "Create {module}",
-        Description = "Allows creating new {module_lowercase}",
-        Category = "{area}",
-        IsSystem = true,
-        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
-    },
-    new Permission
-    {
-        Id = Guid.NewGuid(),
-        Code = "{permission_path}.update",
-        Name = "Update {module}",
-        Description = "Allows updating existing {module_lowercase}",
-        Category = "{area}",
-        IsSystem = true,
-        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
-    },
-    new Permission
-    {
-        Id = Guid.NewGuid(),
-        Code = "{permission_path}.delete",
-        Name = "Delete {module}",
-        Description = "Allows deleting {module_lowercase}",
-        Category = "{area}",
-        IsSystem = true,
-        CreatedAt = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc)
-    }
-);
-```
+See [references/permission-sync-templates.md](../references/permission-sync-templates.md) for the C# templates:
+- **Permissions.cs**: Nested class with 4 constants (View, Create, Update, Delete) + path-to-class mapping
+- **PermissionConfiguration.cs**: 4 HasData Permission entries with deterministic GUIDs
 
 ### 3. Generate Migration (Required)
 
@@ -154,44 +52,7 @@ Suggest command:
 
 **If {postman_mode} = true:**
 
-Load `postman-templates.md` and generate tests:
-
-```json
-{
-  "name": "{module} API Tests",
-  "item": [
-    {
-      "name": "GET {module} - SuperAdmin (200)",
-      "request": {
-        "method": "GET",
-        "url": "{{baseUrl}}/api/{area}/{module}"
-      },
-      "event": [
-        {
-          "listen": "test",
-          "script": {
-            "exec": ["pm.test('Status 200', () => pm.response.to.have.status(200));"]
-          }
-        }
-      ]
-    },
-    {
-      "name": "GET {module} - No Permission (403)",
-      "request": { "method": "GET", "url": "{{baseUrl}}/api/{area}/{module}" },
-      "event": [
-        {
-          "listen": "prerequest",
-          "script": { "exec": ["// Use NoPermUser token"] }
-        },
-        {
-          "listen": "test",
-          "script": { "exec": ["pm.test('Status 403', () => pm.response.to.have.status(403));"] }
-        }
-      ]
-    }
-  ]
-}
-```
+See [references/permission-sync-templates.md](../references/permission-sync-templates.md) § "Postman API Test Template" for the JSON test collection template (200 OK + 403 Forbidden tests).
 
 ---