@atlashub/smartstack-cli 1.13.2 → 1.14.0

package/templates/skills/controller/steps/step-01-analyze.md

@@ -0,0 +1,146 @@
+---
+name: step-01-analyze
+description: Analyze existing codebase - find Entity, DbContext, patterns
+next_step: steps/step-02-plan.md
+---
+
+# Step 1: Analyze Codebase
+
+## YOUR TASK:
+
+Gather all context needed to generate the controller. Find the Entity, check DbContext, analyze existing patterns.
+
+**ULTRA THINK before searching.**
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Find Entity Domain
+
+**Search for entity file:**
+
+```
+Glob: "src/SmartStack.Domain/**/{entity}.cs"
+Glob: "src/SmartStack.Domain/**/{entity}s.cs"
+```
+
+**Extract from Entity:**
+- Properties (for DTO generation)
+- Factory method signature `Create(...)`
+- Update method signature `Update(...)`
+- Relationships (navigation properties)
+- Base class (BaseEntity, AuditableEntity, TenantEntity)
+
+**If Entity NOT found:**
+```
+STOP - Entity {entity} not found in Domain layer.
+Create entity first: /apex add {entity} entity to Domain
+```
+
+### 2. Check DbContext
+
+**Verify DbSet exists:**
+
+```
+Grep: "DbSet<{entity}>" in IApplicationDbContext.cs
+```
+
+**If DbSet NOT found:**
+```
+WARNING: DbSet<{entity}> not in DbContext.
+Will need to add: DbSet<{entity}> {module} { get; }
+```
+
+### 3. Analyze Existing Permissions
+
+**Check current permissions:**
+
+```
+Read: src/SmartStack.Application/Common/Authorization/Permissions.cs
+```
+
+**Look for:**
+- Existing permission class for this module
+- Permission naming pattern used
+- Nested class structure
+
+### 4. Find Similar Controllers
+
+**Find reference controllers in same area:**
+
+```
+Glob: "src/SmartStack.Api/Controllers/{area}/*.cs"
+```
+
+**Extract patterns from existing controllers:**
+- Constructor injection pattern
+- Base class used
+- Common attributes
+- Response type patterns
+- Error handling patterns
+
+### 5. Check for Existing Controller
+
+**Verify controller doesn't exist:**
+
+```
+Glob: "src/SmartStack.Api/Controllers/{area}/{module}Controller.cs"
+```
+
+**If EXISTS:**
+```
+WARNING: Controller already exists!
+Options:
+1. Overwrite (will backup existing)
+2. Abort generation
+```
+
+### 6. Compile Analysis Report
+
+**Store in state:**
+
+```
+{entity_found}       = true/false
+{entity_path}        = "src/SmartStack.Domain/..."
+{entity_properties}  = [list of properties]
+{entity_base_class}  = "TenantEntity" | "AuditableEntity" | "BaseEntity"
+{dbset_exists}       = true/false
+{permissions_exist}  = true/false
+{similar_controller} = "path/to/similar.cs" (for reference)
+{controller_exists}  = true/false
+```
+
+---
+
+## OUTPUT FORMAT:
+
+```
+Analysis Complete:
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Entity | ✅/❌ | {entity_path} |
+| DbSet | ✅/❌ | DbSet<{entity}> |
+| Permissions | ✅/❌ | {permission_path}.* |
+| Reference | ✅ | {similar_controller} |
+| Existing | ⚠️/✅ | Controller exists/new |
+
+Entity Properties:
+- Id (Guid)
+- Name (string)
+- ... (extracted from entity)
+
+-> Planning controller structure...
+```
+
+---
+
+## BLOCKING CONDITIONS:
+
+- **Entity not found** → STOP, suggest creating entity first
+- **Controller exists + auto_mode=false** → ASK user to confirm overwrite
+
+## NEXT STEP:
+
+After analysis complete, proceed to `./step-02-plan.md`

package/templates/skills/controller/steps/step-02-plan.md

@@ -0,0 +1,176 @@
+---
+name: step-02-plan
+description: Plan controller structure - endpoints, DTOs, permissions
+next_step: steps/step-03-generate.md
+---
+
+# Step 2: Plan Controller Structure
+
+## YOUR TASK:
+
+Design the complete controller structure based on analysis. Define endpoints, DTOs, and permissions.
+
+**ULTRA THINK about REST conventions and SmartStack patterns.**
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Determine Controller Type
+
+**Based on {area} and analysis:**
+
+| Indicator | → Controller Type |
+|-----------|-------------------|
+| Area = Auth | `auth` (login, logout, tokens) |
+| Entity has all CRUD methods | `crud` (full CRUD) |
+| Entity missing Create/Update | `readonly` (GET only) |
+| User specifies custom | `custom` (specific endpoints) |
+
+**If not auto_mode, confirm:**
+
+```yaml
+AskUserQuestion:
+  header: "Type"
+  question: "What type of controller?"
+  options:
+    - label: "CRUD Complet (Recommended)"
+      description: "GET list, GET by ID, POST, PUT, PATCH, DELETE"
+    - label: "Read-Only"
+      description: "GET list, GET by ID only"
+    - label: "Custom"
+      description: "I'll specify the endpoints"
+```
+
+### 2. Plan Endpoints
+
+**For CRUD controller:**
+
+| Method | Route | Action | Permission |
+|--------|-------|--------|------------|
+| GET | `/{module}` | GetAll | `{permission_path}.read` |
+| GET | `/{module}/{id}` | GetById | `{permission_path}.read` |
+| POST | `/{module}` | Create | `{permission_path}.create` |
+| PUT | `/{module}/{id}` | Update | `{permission_path}.update` |
+| PATCH | `/{module}/{id}/status` | UpdateStatus | `{permission_path}.update` |
+| DELETE | `/{module}/{id}` | Delete | `{permission_path}.delete` |
+
+**For Auth controller:**
+
+| Method | Route | Action | Permission |
+|--------|-------|--------|------------|
+| POST | `/auth/login` | Login | AllowAnonymous |
+| POST | `/auth/logout` | Logout | Authorize |
+| POST | `/auth/refresh` | RefreshToken | AllowAnonymous |
+| POST | `/auth/change-password` | ChangePassword | Authorize |
+
+### 3. Plan DTOs (if dto_mode)
+
+**CreateDto:**
+```
+{entity}CreateDto:
+  - Required properties from Entity.Create()
+  - Validation attributes
+  - No Id, CreatedAt, etc.
+```
+
+**UpdateDto:**
+```
+{entity}UpdateDto:
+  - Updatable properties from Entity.Update()
+  - Validation attributes
+  - No Id, audit fields
+```
+
+**ResponseDto:**
+```
+{entity}ResponseDto:
+  - All public properties
+  - Formatted dates
+  - Nested DTOs for relationships
+```
+
+### 4. Plan Permissions
+
+**Permission structure:**
+
+```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";
+}
+```
+
+**Permission seeds:**
+
+```csharp
+new Permission { Code = "{permission_path}.read", Name = "View {module}", ... }
+new Permission { Code = "{permission_path}.create", Name = "Create {module}", ... }
+new Permission { Code = "{permission_path}.update", Name = "Update {module}", ... }
+new Permission { Code = "{permission_path}.delete", Name = "Delete {module}", ... }
+```
+
+### 5. Plan Services to Inject
+
+**Required services:**
+
+| Service | Required | Reason |
+|---------|----------|--------|
+| `IApplicationDbContext` | Always | DB access |
+| `ICurrentUserService` | Always | User context |
+| `ILogger<T>` | Always | Logging |
+| `IPermissionService` | If roles/perms | Cache invalidation |
+| `IPasswordService` | If auth | Password hashing |
+| `IJwtService` | If auth | Token generation |
+
+### 6. Confirmation (if not auto_mode)
+
+**Show plan for approval:**
+
+```
+Controller Plan: {area}/{module}Controller
+
+Endpoints:
+  GET    /api/{area}/{module}           → GetAll
+  GET    /api/{area}/{module}/{id}      → GetById
+  POST   /api/{area}/{module}           → Create
+  PUT    /api/{area}/{module}/{id}      → Update
+  DELETE /api/{area}/{module}/{id}      → Delete
+
+DTOs: {dto_mode ? "CreateDto, UpdateDto, ResponseDto" : "None (inline)"}
+
+Permissions:
+  {permission_path}.read
+  {permission_path}.create
+  {permission_path}.update
+  {permission_path}.delete
+
+Proceed with generation?
+```
+
+---
+
+## OUTPUT FORMAT:
+
+```
+Plan Complete:
+
+| Aspect | Details |
+|--------|---------|
+| Type | {controller_type} |
+| Endpoints | {endpoint_count} |
+| DTOs | {dto_count} |
+| Permissions | 4 (CRUD) |
+| Services | {service_count} |
+
+-> Generating controller...
+```
+
+---
+
+## NEXT STEP:
+
+After plan confirmed (or auto_mode), proceed to `./step-03-generate.md`

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

@@ -0,0 +1,219 @@
+---
+name: step-03-generate
+description: Generate controller file and DTOs
+next_step: steps/step-04-perms.md
+---
+
+# Step 3: Generate Controller
+
+## YOUR TASK:
+
+Generate the controller file following SmartStack conventions. Use templates from `templates.md`.
+
+**ULTRA THINK about security and patterns.**
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Templates
+
+**Read template file:**
+
+```
+Read: templates/templates.md
+```
+
+**Select appropriate template based on {controller_type}:**
+- CRUD Controller template
+- Auth Controller template
+- ReadOnly Controller template
+
+### 2. Generate Controller File
+
+**Target path:**
+```
+src/SmartStack.Api/Controllers/{area}/{module}Controller.cs
+```
+
+**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" });
+}
+```
+
+---
+
+## OUTPUT FORMAT:
+
+```
+Generated Files:
+
+| File | Path | Status |
+|------|------|--------|
+| Controller | src/.../Controllers/{area}/{module}Controller.cs | ✅ Created |
+| CreateDto | src/.../DTOs/{module}/{entity}CreateDto.cs | ✅ Created |
+| UpdateDto | src/.../DTOs/{module}/{entity}UpdateDto.cs | ✅ Created |
+| ResponseDto | src/.../DTOs/{module}/{entity}ResponseDto.cs | ✅ Created |
+
+-> Synchronizing permissions...
+```
+
+---
+
+## NEXT STEP:
+
+After generation complete, proceed to `./step-04-perms.md`