@atlashub/smartstack-cli 3.7.0 → 3.9.0

package/templates/skills/controller/references/controller-code-templates.md

@@ -0,0 +1,159 @@
+# Controller & DTO Code Templates
+
+> Referenced from `steps/step-03-generate.md` — C# templates for controller, DTOs, and security patterns.
+
+---
+
+## Controller Template
+
+**Target path:** `src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.cs`
+
+> Context mapping: `business` → `Business`, `platform` → `Admin`, `personal` → `User`
+
+```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...
+}
+```
+
+---
+
+## GET Endpoint Example
+
+```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));
+}
+```
+
+**Endpoint attributes to include:**
+1. `[HttpGet]`, `[HttpPost]`, etc.
+2. `[RequirePermission(Permissions.{module}.View)]`
+3. `[ProducesResponseType(typeof(...), StatusCodes.Status200OK)]`
+4. `[ProducesResponseType(StatusCodes.Status401Unauthorized)]`
+5. `[ProducesResponseType(StatusCodes.Status403Forbidden)]`
+
+---
+
+## DTO Templates
+
+**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
+```
+
+**CreateDto:**
+```csharp
+public record {entity}CreateDto(
+    string Name,
+    // ... required properties
+);
+```
+
+**UpdateDto:**
+```csharp
+public record {entity}UpdateDto(
+    string? Name,
+    // ... optional properties
+);
+```
+
+**ResponseDto:**
+```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
+    ) { }
+}
+```
+
+---
+
+## Security Logging Templates
+
+```csharp
+// Create
+_logger.LogInformation("User {User} created {entity} {Id}",
+    _currentUser.Email, entity.Id);
+
+// Update
+_logger.LogInformation("User {User} updated {entity} {Id}",
+    _currentUser.Email, entity.Id);
+
+// Delete (Warning level)
+_logger.LogWarning("User {User} deleted {entity} {Id} ({Name})",
+    _currentUser.Email, id, entity.Name);
+```
+
+---
+
+## System Account Protection
+
+```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" });
+}
+```

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

@@ -37,164 +37,12 @@ src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.c
 ```
 > 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...
-}
-```
-
-### 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));
-}
-```
-
-### 4. Generate DTOs (if dto_mode)
-
-**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
-```
-
-**CreateDto template:**
-
-```csharp
-public record {entity}CreateDto(
-    string Name,
-    // ... required properties
-);
-```
-
-**UpdateDto template:**
-
-```csharp
-public record {entity}UpdateDto(
-    string? Name,
-    // ... optional properties
-);
-```
-
-**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
-    ) { }
-}
-```
-
-### 5. Add Security Logging
-
-**Ensure logging for all operations:**
-
-```csharp
-// Create
-_logger.LogInformation("User {User} created {entity} {Id}",
-    _currentUser.Email, entity.Id);
-
-// Update
-_logger.LogInformation("User {User} updated {entity} {Id}",
-    _currentUser.Email, entity.Id);
-
-// Delete (Warning level)
-_logger.LogWarning("User {User} deleted {entity} {Id} ({Name})",
-    _currentUser.Email, id, entity.Name);
-```
-
-### 6. Protect System Accounts (if applicable)
-
-**Add guard for system entities:**
-
-```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" });
-}
-```
+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)
 
 ---
 

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).
 
 ---
 

package/templates/skills/debug/SKILL.md

@@ -163,3 +163,10 @@ Evaluate solutions:
 <priority>
 Understanding > Speed > Completeness. Every bug must be fully understood before attempting fixes.
 </priority>
+
+<success_criteria>
+- Root cause identified with evidence (not just symptoms)
+- Fix implemented with minimal, targeted changes
+- Original error no longer reproducible
+- Related tests pass without regressions
+</success_criteria>

package/templates/skills/explore/SKILL.md

@@ -90,3 +90,9 @@ Provide comprehensive response:
 <priority>
 Accuracy > Speed > Brevity. Provide complete answers with evidence.
 </priority>
+
+<success_criteria>
+- Question answered with supporting file references and line numbers
+- All relevant code patterns and conventions identified
+- Dependencies and connections mapped
+</success_criteria>