@atlashub/smartstack-cli 4.33.0 → 4.34.0

package/package.json

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

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

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

@@ -0,0 +1,181 @@
+# {{ProjectName}}.Application - Memory
+
+## Purpose
+
+Use cases orchestration. Defines WHAT the application does. Contains business logic that doesn't belong to entities.
+
+## Dependencies
+
+- **{{ProjectName}}.Domain** (entities, interfaces)
+- **MediatR** (CQRS) - add when needed
+- **FluentValidation** - add when needed
+- **AutoMapper** - add when needed
+
+## Structure
+
+```
+{{ProjectName}}.Application/
+├── Common/
+│   ├── Authorization/             → Permissions constants
+│   ├── Behaviors/                 → MediatR pipeline behaviors
+│   ├── Exceptions/                → Application exceptions
+│   ├── Interfaces/
+│   │   ├── Identity/              → ICurrentUserService, IJwtService
+│   │   └── Persistence/           → IExtensionsDbContext
+│   └── Licensing/                 → License validation
+├── {Feature}/                     → Feature-specific commands/queries
+│   ├── Commands/
+│   ├── Queries/
+│   └── DTOs/
+└── DependencyInjection.cs
+```
+
+## Patterns
+
+### Command Template (with MediatR)
+
+```csharp
+namespace {{ProjectName}}.Application.{Feature}.Commands;
+
+// Command
+public record CreateOrderCommand(string Name, decimal Amount) : IRequest<Guid>;
+
+// Handler
+public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, Guid>
+{
+    private readonly IExtensionsDbContext _context;
+
+    public CreateOrderCommandHandler(IExtensionsDbContext context)
+    {
+        _context = context;
+    }
+
+    public async Task<Guid> Handle(CreateOrderCommand request, CancellationToken ct)
+    {
+        var order = Order.Create(request.Name, request.Amount);
+
+        await _context.Orders.AddAsync(order, ct);
+        await _context.SaveChangesAsync(ct);
+
+        return order.Id;
+    }
+}
+
+// Validator (FluentValidation)
+public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
+{
+    public CreateOrderCommandValidator()
+    {
+        RuleFor(x => x.Name)
+            .NotEmpty().WithMessage("Name is required")
+            .MaximumLength(200).WithMessage("Name max 200 chars");
+
+        RuleFor(x => x.Amount)
+            .GreaterThan(0).WithMessage("Amount must be positive");
+    }
+}
+```
+
+### Query Template
+
+```csharp
+namespace {{ProjectName}}.Application.{Feature}.Queries;
+
+// Query
+public record GetOrdersQuery(string? SearchTerm = null) : IRequest<IReadOnlyList<OrderDto>>;
+
+// Handler
+public class GetOrdersQueryHandler : IRequestHandler<GetOrdersQuery, IReadOnlyList<OrderDto>>
+{
+    private readonly IExtensionsDbContext _context;
+    private readonly IMapper _mapper;
+
+    public GetOrdersQueryHandler(IExtensionsDbContext context, IMapper mapper)
+    {
+        _context = context;
+        _mapper = mapper;
+    }
+
+    public async Task<IReadOnlyList<OrderDto>> Handle(GetOrdersQuery request, CancellationToken ct)
+    {
+        var query = _context.Orders.AsNoTracking();
+
+        if (!string.IsNullOrWhiteSpace(request.SearchTerm))
+            query = query.Where(o => o.Name.Contains(request.SearchTerm));
+
+        return await query
+            .ProjectTo<OrderDto>(_mapper.ConfigurationProvider)
+            .ToListAsync(ct);
+    }
+}
+```
+
+### DTO Template
+
+```csharp
+namespace {{ProjectName}}.Application.{Feature}.DTOs;
+
+public record OrderDto(Guid Id, string Name, decimal Amount, DateTime CreatedAt);
+
+// AutoMapper Profile
+public class OrderProfile : Profile
+{
+    public OrderProfile()
+    {
+        CreateMap<Order, OrderDto>();
+    }
+}
+```
+
+### Interface Template (ExtensionsDbContext)
+
+```csharp
+namespace {{ProjectName}}.Application.Common.Interfaces.Persistence;
+
+public interface IExtensionsDbContext
+{
+    DbSet<Order> Orders { get; }
+    // Add DbSets for your entities here
+    Task<int> SaveChangesAsync(CancellationToken ct = default);
+}
+```
+
+## DependencyInjection Setup
+
+```csharp
+public static class DependencyInjection
+{
+    public static IServiceCollection AddApplication(this IServiceCollection services)
+    {
+        var assembly = typeof(DependencyInjection).Assembly;
+
+        services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(assembly));
+        services.AddValidatorsFromAssembly(assembly);
+        services.AddAutoMapper(assembly);
+        services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
+        services.AddTransient(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
+
+        return services;
+    }
+}
+```
+
+## Rules
+
+1. **NO** direct database access - use `IExtensionsDbContext` (from Common/Interfaces/Persistence)
+2. **NO** HttpContext, Controllers - that's API layer
+3. **Commands** modify state, return Id or nothing
+4. **Queries** read-only, return DTOs
+5. **Handlers** are the use cases
+6. **One handler per command/query**
+
+## When Adding New Feature
+
+1. Create folder in `{Feature}/` (appropriate namespace path)
+2. Add `Commands/` and/or `Queries/` subfolders
+3. Add `DTOs/` subfolder if needed
+4. Create Command/Query record
+5. Create Handler class
+6. Create Validator (optional but recommended)
+7. Add DTO record and AutoMapper profile if needed
+8. Register in `DependencyInjection.cs`

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

@@ -0,0 +1,125 @@
+# {{ProjectName}}.Domain - Memory
+
+## Purpose
+
+Core business logic. **ZERO external dependencies**. This layer defines WHAT the business does, not HOW.
+
+## Structure
+
+```
+{{ProjectName}}.Domain/
+├── Common/
+│   ├── BaseEntity.cs              → Base for all entities (Id, CreatedAt, UpdatedAt)
+│   └── IAuditableEntity.cs        → Audit tracking interface
+├── Enums/                         → Domain enumerations
+├── {Feature}/                     → Feature-specific entities
+│   ├── Order.cs                   → Aggregate root
+│   └── OrderItem.cs               → Child entity
+├── Exceptions/                    → DomainException, custom exceptions
+└── Interfaces/                    → Repository contracts
+```
+
+## Rules (STRICT)
+
+1. **NO** NuGet packages except BCL
+2. **NO** `using` statements referencing other projects
+3. **NO** EF Core attributes (`[Key]`, `[Required]`) - use Fluent API in Infrastructure
+4. **NO** DTOs - entities only
+5. **ALL** business rules live here
+
+## Patterns
+
+### Entity Template
+
+```csharp
+namespace {{ProjectName}}.Domain.{Feature};
+
+public class Order : BaseEntity
+{
+    public string Name { get; private set; } = null!;
+    public decimal Amount { get; private set; }
+    public bool IsActive { get; private set; }
+
+    private Order() { } // EF Core
+
+    public static Order Create(string name, decimal amount)
+    {
+        if (string.IsNullOrWhiteSpace(name))
+            throw new DomainException("Name is required");
+        if (amount <= 0)
+            throw new DomainException("Amount must be positive");
+
+        return new Order
+        {
+            Id = Guid.NewGuid(),
+            Name = name,
+            Amount = amount,
+            IsActive = true,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+
+    public void Deactivate()
+    {
+        IsActive = false;
+        UpdatedAt = DateTime.UtcNow;
+    }
+}
+```
+
+### Value Object Template
+
+```csharp
+namespace {{ProjectName}}.Domain.Common.ValueObjects;
+
+public record Money(decimal Amount, string Currency)
+{
+    public static Money Create(decimal amount, string currency)
+    {
+        if (amount < 0)
+            throw new DomainException("Amount cannot be negative");
+        if (string.IsNullOrWhiteSpace(currency))
+            throw new DomainException("Currency is required");
+
+        return new Money(amount, currency);
+    }
+}
+```
+
+### Domain Event Template
+
+```csharp
+namespace {{ProjectName}}.Domain.Common.Events;
+
+public record OrderCreatedEvent(Guid OrderId, string Name, DateTime OccurredAt);
+```
+
+### Repository Interface Template
+
+```csharp
+namespace {{ProjectName}}.Domain.Interfaces;
+
+public interface IRepository<T> where T : BaseEntity
+{
+    Task<T?> GetByIdAsync(Guid id, CancellationToken ct = default);
+    Task<IReadOnlyList<T>> GetAllAsync(CancellationToken ct = default);
+    Task AddAsync(T entity, CancellationToken ct = default);
+    void Update(T entity);
+    void Remove(T entity);
+}
+```
+
+## Validation
+
+- **Entities validate themselves** in constructors and methods
+- Throw `DomainException` for business rule violations
+- Use **Guard clauses** at method start
+
+## When Adding New Entity
+
+1. Create in the appropriate domain folder
+2. Inherit from `BaseEntity`
+3. Private parameterless constructor for EF
+4. Static `Create()` factory method
+5. Encapsulate all state changes in methods
+6. Add repository interface in `Interfaces/`