aw-spec-cli 0.1.4 → 0.1.6

package/assets/docs/architecture/persistence.md

@@ -1,269 +0,0 @@
-# Persistence Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[persistence.domain]]. NON-NEGOTIABLE where marked. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## EF Core conventions
-
-- The `DbContext` is a `ContextAwareDbContext<TContext>` and is **provider-aware**.
-- EF Core mapping lives **only** in `{Module}/Persistence/<Aggregate>Configuration.cs`,
-  applied via `ApplyConfigurationsFromAssembly`.
-- `DateTimeOffset` columns **MUST** be re-mapped to `timestamptz` when the provider is Npgsql.
-- Cross-cutting behaviors are applied via `modelBuilder.ApplyCrossCuttingBehaviors(this)`:
-  soft-delete global filters, tenant filters, base concurrency-token configuration.
-
-## Repository rules
-
-- **Read handlers** inject `IReadRepository<TAggregate>`; **write handlers** inject
-  `IRepository<TAggregate>` + `IUnitOfWork`.
-- No "repository as data-access god object" — **no custom methods** beyond
-  `IRepository<T>` / `IReadRepository<T>` + `Specification<T>`.
-- Direct `DbContext.Set<T>()` LINQ inside Application Features is FORBIDDEN — use
-  `IReadRepository<T>` + a `Specification<T>` only.
-
-## Specification pattern
-
-- Every non-trivial query is encapsulated in a `Specification<TAggregate>` under
-  `{Module}/Domain/Specifications/`.
-- Specifications **MUST be composable**; paging via `WithPaging(pageNumber, pageSize)`.
-- Ordering uses shared generic helpers (`OrderByIdAsc`, `OrderByIdDesc`, `OrderByNameAsc`);
-  ad-hoc `OrderBy` in handlers is forbidden when a typed helper exists.
-- **Cross-aggregate joins via EF navigation properties are FORBIDDEN** — reference parent
-  aggregates by strongly-typed ID and project client-side.
-
-## Concurrency handling
-
-- Every mutable aggregate **MUST** implement `IConcurrencyTracked`.
-- Concurrency tokens are **client-managed**: `byte[] RowVersion`,
-  `IsConcurrencyToken().ValueGeneratedNever()`, refreshed by a `SaveChanges` interceptor.
-- SQL Server `IsRowVersion()` semantics **MUST NOT** leak into entity configurations.
-- ETag / `If-Match` at the edge: see [[api-versioning]].
-  - Server sets the ETag header on every create/read/update via `SetETagFromBase64(...)`.
-  - Update/Delete endpoints extract `If-Match` via `GetIfMatchBase64Token()` and pass it
-    to the command; mismatch returns `409 concurrency.conflict`.
-  - `DbUpdateConcurrencyException` is translated to the same `409 concurrency.conflict`.
-
-## Soft-delete rules
-
-- Soft delete is enabled via `EnableSoftDelete()`.
-- **Hard deletes are FORBIDDEN** for any aggregate flagged as retention-protected / regulated;
-  deletion is logical via `MarkAsDeleted(...)`. (See [[persistence.domain]] for which data
-  classes are retention-protected.)
-- Append-only aggregates have no delete path at all.
-
-## Tenancy patterns
-
-- Tenancy is enabled via `EnableTenancy()` and `RegisterDefaultContexts(...)`.
-- Tenant resolution **MUST be transparent** to handlers.
-- Default model: **tenant-per-row** with tenant-aware global filters; deployments MAY opt
-  into tenant-per-database via configuration.
-
-## Migrations policy
-
-- Migrations are authored against **PostgreSQL** (production provider). Development MAY run
-  on SQLite (non-sensitive development data only).
-- Multi-provider warnings (`PendingModelChangesWarning`) **MUST** be suppressed only at the
-  runtime registration site, **never** in migration code.
-- Migrations **MUST** apply cleanly to a fresh PostgreSQL instance (CI gate).
-
-## Provider profile
-
-- Production: PostgreSQL 16+ (encryption-at-rest profile in [[persistence.domain]]);
-  per-module schemas where reasonable.
-- Development: PostgreSQL via Aspire containers; SQLite only for in-memory unit-test fixtures.
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-EF Core configuration (Vogen ID + value object conversions, unique business key,
-cross-aggregate FK stored as a raw `Guid` with no navigation):
-
-```csharp
-// <SampleProjectName>.Service/Projects/Persistence/ProjectConfiguration.cs
-public class ProjectConfiguration : IEntityTypeConfiguration<Project>
-{
-    public void Configure(EntityTypeBuilder<Project> builder)
-    {
-        builder.ToTable("Projects");
-        builder.HasKey(e => e.Id);
-
-        // Strongly-typed Vogen ID -> Guid, never DB-generated
-        builder.Property(e => e.Id)
-            .HasConversion(id => id.Value, v => ProjectId.From(v))
-            .ValueGeneratedNever();
-
-        // Value object -> column + unique business key
-        builder.Property(e => e.Code)
-            .HasConversion(c => c.Value, v => ProjectCode.From(v))
-            .HasColumnName("Code").HasMaxLength(20).IsRequired();
-        builder.HasIndex(e => e.Code).IsUnique();
-
-        builder.Property(e => e.Status).HasConversion<string>().HasMaxLength(30).IsRequired();
-
-        // Cross-aggregate FK as nullable Guid — NO EF navigation to TaskUser
-        builder.Property(e => e.OwnerId)
-            .HasConversion(
-                id => id.HasValue ? id.Value.Value : (Guid?)null,
-                v => v.HasValue ? TaskUserId.From(v.Value) : (TaskUserId?)null)
-            .HasColumnName("OwnerId");
-    }
-}
-```
-
-Composable specification (filter + include + paging):
-
-```csharp
-// {Module}/Domain/Specifications/ProjectSearchSpec.cs
-public sealed class ProjectSearchSpec : Specification<Project>
-{
-    public ProjectSearchSpec(string? search, ProjectStatus? status = null)
-    {
-        Query.Include(p => p.Tasks);
-        if (!string.IsNullOrWhiteSpace(search))
-        {
-            var s = search.Trim().ToLowerInvariant();
-            Query.Where(p => p.Code.Value.ToLower().Contains(s) || p.Name.ToLower().Contains(s));
-        }
-        if (status.HasValue) Query.Where(p => p.Status == status.Value);
-    }
-
-    public ProjectSearchSpec WithPaging(int pageNumber, int pageSize)
-    {
-        Query.Skip(Math.Max(0, (pageNumber - 1) * pageSize)).Take(Math.Max(1, pageSize));
-        return this;
-    }
-}
-```
-
-Read handler using the spec + typed ordering helper, returning `PagedResult<T>`:
-
-```csharp
-var spec = new ProjectSearchSpec(request.Search, request.Status)
-    .OrderByIdDesc<ProjectSearchSpec, Project, ProjectId>();   // typed helper, not ad-hoc OrderBy
-
-var total = await _repo.CountAsync(spec, ct);
-var items = await _repo.ListAsync(spec.WithPaging(request.PageNumber, request.PageSize), ct);
-
-return Result<PagedResult<ProjectDto>>.Ok(new PagedResult<ProjectDto>
-{
-    Items = items.ToDtoList(), TotalCount = total,
-    PageNumber = request.PageNumber, PageSize = request.PageSize
-});
-```
-
-Owned child-entity configuration (separate table, FK + cascade, soft-delete mirror filter,
-no EF navigation to other aggregates):
-
-```csharp
-// {Module}/Persistence/ProjectTaskConfiguration.cs
-public class ProjectTaskConfiguration : IEntityTypeConfiguration<ProjectTask>
-{
-    public void Configure(EntityTypeBuilder<ProjectTask> builder)
-    {
-        builder.ToTable("ProjectTasks");
-        builder.HasKey(e => e.Id);
-        builder.Property(e => e.Id)
-            .HasConversion(id => id.Value, v => ProjectTaskId.From(v)).ValueGeneratedNever();
-
-        builder.Property(e => e.ProjectId)                       // FK back to the root
-            .HasConversion(id => id.Value, v => ProjectId.From(v)).IsRequired();
-
-        builder.Property(e => e.Title)                           // Vogen value object
-            .HasConversion(t => t.Value, v => TaskTitle.From(v)).HasMaxLength(300).IsRequired();
-        builder.Property(e => e.Status).HasConversion<string>().HasMaxLength(30).IsRequired();
-
-        // Cross-aggregate ref stored as raw Guid — NO navigation to TaskUser
-        builder.Property(e => e.AssigneeId)
-            .HasConversion(
-                id => id.HasValue ? id.Value.Value : (Guid?)null,
-                v => v.HasValue ? TaskUserId.From(v.Value) : (TaskUserId?)null);
-
-        builder.HasOne(e => e.Project).WithMany(p => p.Tasks)    // owned collection
-            .HasForeignKey(e => e.ProjectId).OnDelete(DeleteBehavior.Cascade);
-
-        // Mirror the parent's ISoftDeletable filter onto the required dependent
-        builder.HasQueryFilter(t => !t.Project.IsDeleted);
-        builder.HasIndex(e => e.ProjectId);
-        builder.HasIndex(e => e.AssigneeId);
-    }
-}
-```
-
-DbContext — `ContextAwareDbContext`, assembly-scanned configs, provider-aware `timestamptz`,
-cross-cutting behaviors, and the client-managed concurrency token override:
-
-```csharp
-// <SampleProjectName>.Service/Infrastructure/ApplicationDbContext.cs
-public class ApplicationDbContext(
-    DbContextOptions<ApplicationDbContext> options, ICurrentTenant? tenant = null)
-    : ContextAwareDbContext<ApplicationDbContext>(options, tenant)
-{
-    protected override void OnModelCreating(ModelBuilder modelBuilder)
-    {
-        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
-
-        if (Database.ProviderName == "Npgsql.EntityFrameworkCore.PostgreSQL")
-            foreach (var et in modelBuilder.Model.GetEntityTypes())
-                foreach (var p in et.GetProperties()
-                    .Where(p => p.ClrType == typeof(DateTimeOffset) || p.ClrType == typeof(DateTimeOffset?)))
-                    p.SetColumnType("timestamptz");
-
-        modelBuilder.ApplyCrossCuttingBehaviors(this);   // soft-delete + tenant filters + audit
-
-        // Client-managed concurrency token (works on SQLite + PostgreSQL; not SQL Server IsRowVersion)
-        foreach (var et in modelBuilder.Model.GetEntityTypes())
-            if (typeof(IConcurrencyTracked).IsAssignableFrom(et.ClrType))
-                modelBuilder.Entity(et.ClrType).Property<byte[]>("RowVersion")
-                    .IsConcurrencyToken().ValueGeneratedNever();
-
-        base.OnModelCreating(modelBuilder);
-    }
-
-    public DbSet<Project> Projects => Set<Project>();
-    public DbSet<ProjectTask> ProjectTasks => Set<ProjectTask>();
-}
-```
-
-Soft-delete: logical delete via `MarkAsDeleted(...)` + `DeleteAsync` (never a hard delete),
-and a separate `IgnoreQueryFilters()` spec for admin/audit reads:
-
-```csharp
-// Delete handler — soft delete + concurrency guard (returns Result, no DTO)
-var entity = await _repo.GetByIdAsync(ProjectId.From(request.Id), ct);
-if (entity is null)
-    return Result.Failure(new Error("project.not_found", $"Project {request.Id} not found", 404, "projects"));
-// ... concurrency token check (see api-versioning) ...
-entity.MarkAsDeleted();                 // sets IsDeleted/DeletedOn + raises ProjectDeletedEvent
-await _repo.DeleteAsync(entity, ct);    // framework translates to UPDATE, not DELETE
-
-// Admin/audit spec that bypasses the global soft-delete filter
-public sealed class ProjectSearchIncludeDeletedSpec : Specification<Project>
-{
-    public ProjectSearchIncludeDeletedSpec(string? search, ProjectStatus? status = null)
-    {
-        Query.Include(p => p.Tasks).IgnoreQueryFilters();   // include soft-deleted rows
-        // ... same Where filters as ProjectSearchSpec ...
-    }
-}
-```
-
-Composition — repository + cross-cutting behaviors registered once at startup:
-
-```csharp
-// <SampleProjectName>.Service/Extensions/InfrastructureServiceRegistration.cs
-services.AddRepositories(builder =>
-{
-    builder
-        .UseSingleDbContextEFRepositories<ApplicationDbContext>(db => db.UseSqlite(/* or UseNpgsql */)
-            .ConfigureWarnings(w => w.Ignore(RelationalEventId.PendingModelChangesWarning)))
-        .EnableTenancy()
-        .EnableSoftDelete()
-        .EnableClientManagedConcurrency()
-        .EnableAuditing().EnableAdvancedAuditing()   // see [[auditing]]
-        .Done();
-}, options => options.Provider = "EfCore");
-
-services.TryAddScoped(typeof(IUnitOfWork), typeof(EfUnitOfWork<ApplicationDbContext>));
-```
-
-## Related
-
-- [[clean-architecture]] · [[cqrs]] · [[domain-driven-design]] · [[api-versioning]] · [[persistence.domain]]

package/assets/docs/architecture/testing.md

@@ -1,55 +0,0 @@
-# Testing Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[testing.domain]]. Commands: `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Test-first engineering
-
-- Generated tests follow Test-First Engineering and **MUST fail before** the production
-  change is in place.
-- Any change to an aggregate invariant, endpoint contract, or error code **MUST** include
-  the corresponding test update **in the same commit**.
-
-## Unit test conventions
-
-- Unit tests are required for **every** aggregate behavior, value object, and specification.
-- Tests are **deterministic** — time, randomness, and IDs are injected
-  (use the framework-provided `IClock` / `IGuidGenerator`). Never `DateTime.UtcNow` /
-  `Guid.NewGuid()` in the system under test.
-- Tests **MUST NOT** reach into module internals; they exercise the public endpoint or
-  `IMediator` surface.
-
-## Handler tests
-
-Required for **every** Command/Query handler and MUST cover:
-
-- happy path
-- validation failure
-- not-found
-- (for writes) concurrency conflict
-
-## Integration testing
-
-- Required for **every** endpoint; run against **PostgreSQL via Testcontainers** or Aspire.
-- Test database engine: Testcontainers PostgreSQL for integration; in-memory fixtures for
-  unit tests.
-
-## Testcontainers usage
-
-- Integration and contract tests spin up real PostgreSQL (and other backing services)
-  via Testcontainers / Aspire — no faked persistence in integration tests.
-
-## Test data hygiene
-
-- Tests use a **shared fixture library** rather than inlining fabricated data.
-- Production data MUST NOT be used in development, test, demo, or shared CI.
-  (Domain specifics — synthetic fixtures + terminology sentinels — in [[testing.domain]].)
-
-## Coverage rules
-
-- Minimum **85% line coverage** on Application + Domain.
-- **100%** on aggregate behaviors and value objects.
-- Code coverage on changed files must meet the threshold (CI gate).
-
-## Related
-
-- [[domain-driven-design]] · [[persistence]] · [[testing.domain]]

package/assets/docs/architecture/vertical-slices.md

@@ -1,201 +0,0 @@
-# Vertical Slice Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[vertical-slices.domain]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Feature organization
-
-- Each feature is a **self-contained vertical slice**: Command/Query, Handler, Endpoint,
-  Validator co-located in **one folder**.
-- No horizontal "Services/Managers" layers spanning slices.
-
-## Folder structure (per module)
-
-```
-<Module>/
-  Domain/
-    <Aggregate>.cs
-    <ChildEntity>.cs
-    <ValueObject>.cs
-    <Aggregate>Id.cs            [ValueObject<Guid>] partial struct
-    Events/                     DomainEventBase descendants
-    Specifications/
-  Persistence/<Aggregate>Configuration.cs
-  Features/<FeatureName>/       Command/Query + Handler + Endpoint + Validator
-  Interop/                      external-protocol adapters (see [[vertical-slices.domain]])
-  Shared/                       module-public DTOs + ToDto extensions
-```
-
-## Endpoint conventions
-
-- One endpoint **per file**. Endpoints inherit `SecureFastEndpoint<TRequest, TResponse>`.
-- Kebab-case routes; resources are plural nouns; verbs map to intent
-  (POST create, GET list/fetch, PUT full update, PATCH partial update, DELETE logical delete).
-- GUID route ids **MUST** use the `:guid` constraint.
-- Tagged via `Options(o => o.WithTags("NN - <Module> - (FastEndpoints)"))` and **MUST**
-  provide a `Summary`.
-- HTTP request classes are declared **inside the same file as the Endpoint** and contain
-  **primitive types only**.
-- Endpoints **MUST NOT** swallow exceptions — the central exception handler owns the contract.
-- See [[authorization]] for security cache policy on endpoints.
-
-## Validator placement
-
-- Validators live in the **feature folder** alongside the Command/Query they validate.
-- Validators check **request shape only**; aggregate invariants are enforced in the Domain.
-
-## DTO placement (immutable contracts)
-
-- DTOs live in `{Module}/Shared/` and are mapped with **hand-written** `ToDto()` /
-  `ToDtoList()` extension methods. AutoMapper-style reflection mappers are FORBIDDEN.
-- `record EntityDto { public required Guid Id { get; init; } ... }` — no setters;
-  required init for non-nullable members.
-- Every DTO **MUST** include a base64 `RowVersionBase64` when the aggregate implements
-  `IConcurrencyTracked`.
-- Paged results **MUST** use the standard `PagedResult<T>` shape
-  (`Items, TotalCount, PageNumber, PageSize`, computed `TotalPages`) with required init props.
-
-## Specification placement
-
-- Query composition lives in the **Domain**, under `{Module}/Domain/Specifications/`.
-  See [[persistence]] for specification rules.
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-A complete slice: Endpoint (+ request class in the same file), Validator, DTO, and mapping.
-
-```csharp
-// <SampleProjectName>.Service/Projects/Features/CreateProject/CreateProjectEndpoint.cs
-public class CreateProjectEndpoint(IMediator _mediator)
-    : SecureFastEndpoint<CreateProjectRequest, ProjectDto>
-{
-    public override void Configure()
-    {
-        Post("/projects");                                  // kebab-case, plural noun
-        Summary(s => s.Summary = "Create a new project");
-        Options(o => o.WithTags("02 - Project - (FastEndpoints)"));
-    }
-
-    protected override SecurityCachePolicy GetSecurityCachePolicy() => new()
-    {
-        SecurityLevel = SecurityLevel.Internal,
-        CachePolicy = CachePolicy.NoStore                   // mutating endpoint
-    };
-
-    protected override async Task<Result<ProjectDto>> ExecuteAsync(
-        CreateProjectRequest req, CancellationToken ct)
-    {
-        var result = await _mediator.Send(new CreateProjectCommand(   // IMediator only
-            req.Code, req.Name, req.Description, req.StartDate, req.EndDate, req.OwnerId), ct);
-
-        if (result.IsSuccess && !string.IsNullOrWhiteSpace(result.Value?.RowVersionBase64))
-            HttpContext.Response.SetETagFromBase64(result.Value!.RowVersionBase64);
-        return result;
-    }
-}
-
-// Request lives in the SAME file — primitive types only
-public class CreateProjectRequest
-{
-    public string Code { get; set; } = string.Empty;
-    public string Name { get; set; } = string.Empty;
-    public string? Description { get; set; }
-    public DateOnly StartDate { get; set; }
-    public DateOnly? EndDate { get; set; }
-    public Guid? OwnerId { get; set; }
-}
-```
-
-```csharp
-// .../CreateProject/CreateProjectValidator.cs — request shape only
-public class CreateProjectValidator : AbstractValidator<CreateProjectCommand>
-{
-    public CreateProjectValidator()
-    {
-        RuleFor(x => x.Code).NotEmpty().MaximumLength(20).Matches(@"^[A-Z0-9\-]+$");
-        RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
-        RuleFor(x => x.EndDate)
-            .GreaterThanOrEqualTo(x => x.StartDate).When(x => x.EndDate.HasValue);
-    }
-}
-```
-
-```csharp
-// {Module}/Shared/ProjectDto.cs — includes RowVersionBase64 (IConcurrencyTracked)
-public record ProjectDto
-{
-    public Guid Id { get; set; }
-    public string Code { get; set; } = string.Empty;
-    public string Name { get; set; } = string.Empty;
-    public string Status { get; set; } = string.Empty;
-    public Guid? OwnerId { get; set; }
-    public List<ProjectTaskDto> Tasks { get; set; } = new();
-    public string RowVersionBase64 { get; set; } = string.Empty;
-}
-
-// {Module}/Shared/ProjectMappingExtensions.cs — hand-written, zero reflection
-public static class ProjectMappingExtensions
-{
-    public static ProjectDto ToDto(this Project e) => new()
-    {
-        Id = e.Id.Value, Code = e.Code.Value, Name = e.Name,
-        Status = e.Status.ToString(), OwnerId = e.OwnerId?.Value,
-        Tasks = e.Tasks.Select(t => t.ToDto()).ToList(),
-        RowVersionBase64 = e.RowVersion is { Length: > 0 } rv
-            ? Convert.ToBase64String(rv) : string.Empty
-    };
-
-    public static List<ProjectDto> ToDtoList(this IEnumerable<Project> es)
-        => es.Select(e => e.ToDto()).ToList();
-}
-```
-
-Sub-resource endpoint for a distinct operation on a child — nested route, multiple route
-params, `EmptyResponse` when there is no body to return:
-
-```csharp
-// .../Features/AssignTask/AssignTaskEndpoint.cs
-public class AssignTaskEndpoint(IMediator _mediator)
-    : SecureFastEndpoint<AssignTaskRequest, EmptyResponse>
-{
-    public override void Configure()
-    {
-        Put("/projects/{projectId:guid}/tasks/{taskId:guid}/assignee");   // sub-resource
-        Summary(s => s.Summary = "Assign a task to a TaskUser");
-        Options(o => o.WithTags("02 - Project - (FastEndpoints)"));
-    }
-
-    protected override SecurityCachePolicy GetSecurityCachePolicy() => new()
-    { SecurityLevel = SecurityLevel.Internal, CachePolicy = CachePolicy.NoStore };
-
-    protected override async Task<Result<EmptyResponse>> ExecuteAsync(
-        AssignTaskRequest req, CancellationToken ct)
-    {
-        var projectId = Route<Guid>("projectId");
-        var taskId = Route<Guid>("taskId");
-        var result = await _mediator.Send(new AssignTaskCommand(projectId, taskId, req.AssigneeId), ct);
-        return result.IsSuccess
-            ? Result<EmptyResponse>.Ok(new EmptyResponse())
-            : Result<EmptyResponse>.Failure([.. result.Errors]);
-    }
-}
-
-public class AssignTaskRequest { public Guid AssigneeId { get; set; } }
-```
-
-Standard `PagedResult<T>` contract (required init props, computed `TotalPages`):
-
-```csharp
-// {Module}/Common/PagedResult.cs
-public sealed class PagedResult<T>
-{
-    public required IReadOnlyList<T> Items { get; init; }
-    public required int TotalCount { get; init; }
-    public required int PageNumber { get; init; }
-    public required int PageSize { get; init; }
-    public int TotalPages => (int)Math.Ceiling((double)TotalCount / PageSize);
-}
-```
-
-## Related
-
-- [[clean-architecture]] · [[cqrs]] · [[persistence]] · [[authorization]] · [[vertical-slices.domain]]