@atlashub/smartstack-cli 4.32.0 → 4.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.32.0",
+  "version": "4.34.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/mcp-scaffolding/controller.cs.hbs

@@ -1,192 +1,118 @@
-using System;
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.AspNetCore.Authorization;
+using MediatR;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.Extensions.Logging;
 using SmartStack.Api.Authorization;
 {{#if navRoute}}
 using SmartStack.Api.Routing;
 {{/if}}
-using SmartStack.Application.Common.Models;
+using SmartStack.Application.Common.Authorization;
 
-namespace {{namespace}}.Controllers;
+namespace {{namespace}};
 
 /// <summary>
-/// API controller for {{name}} operations
+/// API controller for {{name}} operations.
 /// </summary>
 [ApiController]
 {{#if navRoute}}
-[NavRoute("{{navRoute}}")]
+[NavRoute("{{navRoute}}"{{#if navRouteSuffix}}, Suffix = "{{navRouteSuffix}}"{{/if}}{{#if customSegment}}, CustomSegment = "{{customSegment}}"{{/if}})]
 {{else}}
 [Route("api/[controller]")]
 {{/if}}
-[Authorize]
+[Microsoft.AspNetCore.Authorization.Authorize]
 [Produces("application/json")]
+[Tags("{{namePlural}}")]
 public class {{name}}Controller : ControllerBase
 {
-    private readonly ILogger<{{name}}Controller> _logger;
-    // private readonly I{{name}}Service _{{nameCamel}}Service;
+    private readonly ISender _mediator;
 
-    public {{name}}Controller(
-        ILogger<{{name}}Controller> logger
-        // I{{name}}Service {{nameCamel}}Service
-    )
-    {
-        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
-        // _{{nameCamel}}Service = {{nameCamel}}Service ?? throw new ArgumentNullException(nameof({{nameCamel}}Service));
-    }
+    public {{name}}Controller(ISender mediator) => _mediator = mediator;
 
     /// <summary>
     /// Get all {{namePlural}} with pagination
     /// </summary>
     [HttpGet]
 {{#if navRoute}}
-    [RequirePermission("{{navRoute}}.read")]
+    [RequirePermission(Permissions.{{module}}.{{namePlural}}.View)]
 {{/if}}
-    [ProducesResponseType(typeof(PaginatedResult<{{name}}Dto>), 200)]
-    public async Task<ActionResult<PaginatedResult<{{name}}Dto>>> GetAll(
-        [FromQuery] string? search = null,
-        [FromQuery] int page = 1,
-        [FromQuery] int pageSize = 20,
-        CancellationToken cancellationToken = default)
+    [ProducesResponseType(typeof(List<{{name}}ListDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<List<{{name}}ListDto>>> GetAll(CancellationToken ct)
     {
-        _logger.LogInformation("Getting all {{namePlural}}");
-
-        // TODO: Implement using service
-        // var result = await _{{nameCamel}}Service.GetAllAsync(search, page, pageSize, cancellationToken);
-        // return Ok(result);
-
-        return Ok(PaginatedResult<{{name}}Dto>.Empty(page, pageSize));
+        var result = await _mediator.Send(new Get{{namePlural}}Query(), ct);
+        return Ok(result);
     }
 
     /// <summary>
     /// Get {{nameCamel}} by ID
     /// </summary>
-    /// <param name="id">{{name}} ID</param>
-    /// <param name="cancellationToken">Cancellation token</param>
-    /// <returns>{{name}} details</returns>
     [HttpGet("{id:guid}")]
 {{#if navRoute}}
-    [RequirePermission("{{navRoute}}.read")]
+    [RequirePermission(Permissions.{{module}}.{{namePlural}}.View)]
 {{/if}}
-    [ProducesResponseType(typeof({{name}}Dto), 200)]
-    [ProducesResponseType(404)]
-    public async Task<ActionResult<{{name}}Dto>> GetById(
-        Guid id,
-        CancellationToken cancellationToken = default)
+    [ProducesResponseType(typeof({{name}}DetailDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<{{name}}DetailDto>> GetById(
+        Guid id, CancellationToken ct)
     {
-        _logger.LogInformation("Getting {{nameCamel}} {Id}", id);
-
-        // TODO: Implement using service
-        // var result = await _{{nameCamel}}Service.GetByIdAsync(id, cancellationToken);
-        // if (result == null) return NotFound();
-        // return Ok(result);
-
-        return NotFound();
+        var result = await _mediator.Send(new Get{{name}}ByIdQuery(id), ct);
+        if (result == null) return NotFound(new { message = "{{name}} not found" });
+        return Ok(result);
     }
 
     /// <summary>
     /// Create new {{nameCamel}}
     /// </summary>
-    /// <param name="request">Create request</param>
-    /// <param name="cancellationToken">Cancellation token</param>
-    /// <returns>Created {{nameCamel}}</returns>
     [HttpPost]
 {{#if navRoute}}
-    [RequirePermission("{{navRoute}}.create")]
+    [RequirePermission(Permissions.{{module}}.{{namePlural}}.Create)]
 {{/if}}
-    [ProducesResponseType(typeof({{name}}Dto), 201)]
-    [ProducesResponseType(400)]
-    public async Task<ActionResult<{{name}}Dto>> Create(
-        [FromBody] Create{{name}}Request request,
-        CancellationToken cancellationToken = default)
+    [ProducesResponseType(typeof({{name}}DetailDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<{{name}}DetailDto>> Create(
+        [FromBody] Create{{name}}Request request, CancellationToken ct)
     {
-        _logger.LogInformation("Creating new {{nameCamel}}");
-
-        // TODO: Validate and create using service
-        // var result = await _{{nameCamel}}Service.CreateAsync(request, cancellationToken);
-        // return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
-
-        var id = Guid.NewGuid();
-        return CreatedAtAction(nameof(GetById), new { id }, null);
+        var result = await _mediator.Send(new Create{{name}}Command(request), ct);
+        return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
     }
 
     /// <summary>
     /// Update {{nameCamel}}
     /// </summary>
-    /// <param name="id">{{name}} ID</param>
-    /// <param name="request">Update request</param>
-    /// <param name="cancellationToken">Cancellation token</param>
     [HttpPut("{id:guid}")]
 {{#if navRoute}}
-    [RequirePermission("{{navRoute}}.update")]
+    [RequirePermission(Permissions.{{module}}.{{namePlural}}.Update)]
 {{/if}}
-    [ProducesResponseType(204)]
-    [ProducesResponseType(404)]
-    [ProducesResponseType(400)]
-    public async Task<ActionResult> Update(
-        Guid id,
-        [FromBody] Update{{name}}Request request,
-        CancellationToken cancellationToken = default)
+    [ProducesResponseType(typeof({{name}}DetailDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<{{name}}DetailDto>> Update(
+        Guid id, [FromBody] Update{{name}}Request request, CancellationToken ct)
     {
-        _logger.LogInformation("Updating {{nameCamel}} {Id}", id);
-
-        // TODO: Implement using service
-        // await _{{nameCamel}}Service.UpdateAsync(id, request, cancellationToken);
-
-        return NoContent();
+        var result = await _mediator.Send(new Update{{name}}Command(id, request), ct);
+        if (result.IsNotFound) return NotFound(new { message = "{{name}} not found" });
+        return Ok(result.Data);
     }
 
     /// <summary>
     /// Delete {{nameCamel}}
     /// </summary>
-    /// <param name="id">{{name}} ID</param>
-    /// <param name="cancellationToken">Cancellation token</param>
     [HttpDelete("{id:guid}")]
 {{#if navRoute}}
-    [RequirePermission("{{navRoute}}.delete")]
+    [RequirePermission(Permissions.{{module}}.{{namePlural}}.Delete)]
 {{/if}}
-    [ProducesResponseType(204)]
-    [ProducesResponseType(404)]
-    public async Task<ActionResult> Delete(
-        Guid id,
-        CancellationToken cancellationToken = default)
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<IActionResult> Delete(Guid id, CancellationToken ct)
     {
-        _logger.LogInformation("Deleting {{nameCamel}} {Id}", id);
-
-        // TODO: Implement using service
-        // await _{{nameCamel}}Service.DeleteAsync(id, cancellationToken);
-
-        return NoContent();
+        var success = await _mediator.Send(new Delete{{name}}Command(id), ct);
+        return success ? NoContent() : NotFound(new { message = "{{name}} not found" });
     }
 }
-
-// ============================================================================
-// DTOs
-// ============================================================================
-
-/// <summary>
-/// {{name}} data transfer object
-/// </summary>
-public record {{name}}Dto(
-    Guid Id,
-    DateTime CreatedAt,
-    DateTime? UpdatedAt
-    // TODO: Add additional properties
-);
-
-/// <summary>
-/// Request to create a new {{nameCamel}}
-/// </summary>
-public record Create{{name}}Request(
-    // TODO: Add creation properties
-);
-
-/// <summary>
-/// Request to update a {{nameCamel}}
-/// </summary>
-public record Update{{name}}Request(
-    // TODO: Add update properties
-);

package/templates/project/README.md

@@ -62,6 +62,25 @@ Migrations must be applied in order:
 
 This is handled automatically in `Program.cs.template`.
 
+## Frontend Setup (React)
+
+### Route Registration
+
+SmartStack uses **PageRegistry + DynamicRouter** for routing. Register your pages:
+
+```tsx
+import { PageRegistry } from '@atlashub/smartstack';
+import { lazy } from 'react';
+
+// Register your application pages
+PageRegistry.register('rh.time.dashboard', lazy(() => import('./pages/TimeDashboard')));
+PageRegistry.register('rh.time.list', lazy(() => import('./pages/TimeList')));
+PageRegistry.register('rh.time.detail', lazy(() => import('./pages/TimeDetail')));
+```
+
+Navigation entries (menu, permissions, routes) are managed in the database.
+DynamicRouter resolves everything automatically — no manual route wiring needed.
+
 ## Usage
 
 ```bash

package/templates/project/claude-md/api.CLAUDE.md.template

@@ -0,0 +1,315 @@
+# {{ProjectName}}.Api - Memory
+
+## Purpose
+
+HTTP entry point. REST API. Receives requests, delegates to Application layer, returns responses.
+
+## Dependencies
+
+- **{{ProjectName}}.Application** (commands, queries, DTOs)
+- **{{ProjectName}}.Infrastructure** (DI registration)
+- **MediatR** (sending commands/queries)
+- **Scalar.AspNetCore** (OpenAPI UI)
+
+---
+
+## OpenAPI / Swagger Configuration (CRITICAL)
+
+### Package Requirements
+
+```xml
+<!-- {{ProjectName}}.Api.csproj -->
+<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+<PackageReference Include="Scalar.AspNetCore" Version="2.0.0" />
+```
+
+### Program.cs Configuration
+
+```csharp
+// Services
+builder.Services.AddOpenApi(options =>
+{
+    options.AddDocumentTransformer((document, context, ct) =>
+    {
+        document.Info = new OpenApiInfo
+        {
+            Title = "{{ProjectName}} API",
+            Version = "v1",
+            Description = "{{ProjectName}} REST API"
+        };
+        return Task.CompletedTask;
+    });
+});
+
+// Middleware (after app.Build())
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi();                    // /openapi/v1.json
+    app.MapScalarApiReference(options => // /scalar/v1
+    {
+        options.WithTitle("{{ProjectName}} API")
+               .WithTheme(ScalarTheme.BluePlanet)
+               .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
+    });
+}
+```
+
+### XML Documentation (MANDATORY for all Controllers)
+
+```xml
+<!-- {{ProjectName}}.Api.csproj -->
+<PropertyGroup>
+  <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  <NoWarn>$(NoWarn);1591</NoWarn>
+</PropertyGroup>
+```
+
+### Controller Documentation Pattern
+
+```csharp
+/// <summary>
+/// Manages orders
+/// </summary>
+[ApiController]
+[Route("api/[controller]")]
+[Produces("application/json")]
+[Tags("Orders")]
+public class OrdersController : ControllerBase
+{
+    /// <summary>
+    /// Retrieves all orders with optional filtering
+    /// </summary>
+    [HttpGet]
+    [ProducesResponseType(typeof(IReadOnlyList<OrderDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status403Forbidden)]
+    public async Task<IActionResult> GetAll(CancellationToken ct)
+    {
+        var result = await _mediator.Send(new GetOrdersQuery(), ct);
+        return Ok(result);
+    }
+}
+```
+
+### ProducesResponseType Cheat Sheet
+
+| Scenario | Attributes |
+|----------|------------|
+| **GET (list)** | `[ProducesResponseType(typeof(List<Dto>), 200)]` |
+| **GET (single)** | `[ProducesResponseType(typeof(Dto), 200)]`<br>`[ProducesResponseType(typeof(ProblemDetails), 404)]` |
+| **POST (create)** | `[ProducesResponseType(typeof(Guid), 201)]`<br>`[ProducesResponseType(typeof(ValidationProblemDetails), 400)]` |
+| **PUT (update)** | `[ProducesResponseType(204)]`<br>`[ProducesResponseType(typeof(ProblemDetails), 404)]` |
+| **DELETE** | `[ProducesResponseType(204)]`<br>`[ProducesResponseType(typeof(ProblemDetails), 404)]` |
+| **Auth required** | Add `[ProducesResponseType(typeof(ProblemDetails), 401)]` |
+| **Permission required** | Add `[ProducesResponseType(typeof(ProblemDetails), 403)]` |
+| **Conflict possible** | Add `[ProducesResponseType(typeof(ProblemDetails), 409)]` |
+
+### OpenAPI URLs
+
+| Environment | URL | Purpose |
+|-------------|-----|---------|
+| Development | `/openapi/v1.json` | Raw OpenAPI spec |
+| Development | `/scalar/v1` | Interactive UI (Scalar) |
+| Production | Disabled | Security best practice |
+
+---
+
+## Structure
+
+```
+{{ProjectName}}.Api/
+├── Controllers/                → Organized by Application/Module
+├── Authorization/              → RequirePermissionAttribute
+├── Middleware/
+│   ├── GlobalExceptionHandlerMiddleware.cs
+│   └── SessionValidationMiddleware.cs
+├── Extensions/
+├── RateLimiting/
+├── Program.cs
+├── appsettings.json
+└── appsettings.Development.json
+```
+
+## Patterns
+
+### Controller Template
+
+```csharp
+namespace {{ProjectName}}.Api.Controllers;
+
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using {{ProjectName}}.Api.Authorization;
+
+[ApiController]
+[Route("api/[controller]")]
+[Produces("application/json")]
+[Tags("Orders")]
+public class OrdersController : ControllerBase
+{
+    private readonly ISender _mediator;
+
+    public OrdersController(ISender mediator)
+    {
+        _mediator = mediator;
+    }
+
+    [HttpGet]
+    [ProducesResponseType(typeof(IReadOnlyList<OrderDto>), StatusCodes.Status200OK)]
+    public async Task<IActionResult> GetAll(CancellationToken ct)
+    {
+        var result = await _mediator.Send(new GetOrdersQuery(), ct);
+        return Ok(result);
+    }
+
+    [HttpGet("{id:guid}")]
+    [ProducesResponseType(typeof(OrderDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
+    {
+        var result = await _mediator.Send(new GetOrderByIdQuery(id), ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    [ProducesResponseType(typeof(Guid), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> Create([FromBody] CreateOrderCommand command, CancellationToken ct)
+    {
+        var id = await _mediator.Send(command, ct);
+        return CreatedAtAction(nameof(GetById), new { id }, id);
+    }
+
+    [HttpPut("{id:guid}")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> Update(Guid id, [FromBody] UpdateOrderCommand command, CancellationToken ct)
+    {
+        if (id != command.Id) return BadRequest();
+        await _mediator.Send(command, ct);
+        return NoContent();
+    }
+
+    [HttpDelete("{id:guid}")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> Delete(Guid id, CancellationToken ct)
+    {
+        await _mediator.Send(new DeleteOrderCommand(id), ct);
+        return NoContent();
+    }
+}
+```
+
+### Exception Middleware
+
+```csharp
+namespace {{ProjectName}}.Api.Middleware;
+
+using System.Net;
+using FluentValidation;
+using Microsoft.AspNetCore.Mvc;
+using {{ProjectName}}.Application.Common.Exceptions;
+
+public class GlobalExceptionHandlerMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<GlobalExceptionHandlerMiddleware> _logger;
+
+    public GlobalExceptionHandlerMiddleware(RequestDelegate next, ILogger<GlobalExceptionHandlerMiddleware> logger)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await _next(context);
+        }
+        catch (ValidationException ex)
+        {
+            context.Response.StatusCode = StatusCodes.Status400BadRequest;
+            context.Response.ContentType = "application/json";
+            var problemDetails = new ValidationProblemDetails(
+                ex.Errors.GroupBy(e => e.PropertyName)
+                    .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray()))
+            {
+                Status = StatusCodes.Status400BadRequest,
+                Title = "Validation failed"
+            };
+            await context.Response.WriteAsJsonAsync(problemDetails);
+        }
+        catch (NotFoundException ex)
+        {
+            context.Response.StatusCode = StatusCodes.Status404NotFound;
+            context.Response.ContentType = "application/json";
+            var problemDetails = new ProblemDetails
+            {
+                Title = "Not Found",
+                Detail = ex.Message,
+                Status = StatusCodes.Status404NotFound
+            };
+            await context.Response.WriteAsJsonAsync(problemDetails);
+        }
+        catch (DomainException ex)
+        {
+            context.Response.StatusCode = StatusCodes.Status400BadRequest;
+            context.Response.ContentType = "application/json";
+            var problemDetails = new ProblemDetails
+            {
+                Title = "Business rule violation",
+                Detail = ex.Message,
+                Status = StatusCodes.Status400BadRequest
+            };
+            await context.Response.WriteAsJsonAsync(problemDetails);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Unhandled exception: {Message}", ex.Message);
+            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+            context.Response.ContentType = "application/json";
+            var problemDetails = new ProblemDetails
+            {
+                Title = "Internal Server Error",
+                Detail = "An unexpected error occurred",
+                Status = StatusCodes.Status500InternalServerError
+            };
+            await context.Response.WriteAsJsonAsync(problemDetails);
+        }
+    }
+}
+```
+
+## API Response Conventions
+
+| Action | Status Code | Response |
+|--------|-------------|----------|
+| GET (list) | 200 | `List<Dto>` |
+| GET (single) | 200 / 404 | `Dto` / ProblemDetails |
+| POST | 201 | Id + Location header |
+| PUT | 204 | Empty |
+| DELETE | 204 | Empty |
+| Validation error | 400 | ValidationProblemDetails |
+| Server error | 500 | ProblemDetails |
+
+## Rules
+
+1. **Controllers are thin** - delegate to MediatR immediately
+2. **NO business logic** in controllers
+3. **Use `CancellationToken`** in all async methods
+4. **Document with XML comments** for OpenAPI
+5. **Return `IActionResult`** for flexibility
+6. **ALWAYS add `[ProducesResponseType]`** for all possible responses
+7. **ALWAYS add `[Tags]`** to group endpoints in OpenAPI
+
+## When Adding New Endpoint
+
+1. Create controller in `Controllers/` (or add to existing)
+2. Inject `ISender` (MediatR)
+3. Create action method with proper HTTP verb
+4. Document with XML comments
+5. Add `[ProducesResponseType]` attributes
+6. Use command/query from Application layer