@atlashub/smartstack-cli 3.22.0 → 3.24.0

package/package.json

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

package/templates/mcp-scaffolding/component.tsx.hbs

@@ -174,7 +174,27 @@ export const {{name}}: React.FC<{{name}}Props> = ({
 
       {/* Form */}
       <form onSubmit={handleSubmit} className="p-6 space-y-6">
-        {/* TODO: Add form fields */}
+        {/*
+          TODO: Add form fields based on entity properties.
+          IMPORTANT — Field type mapping:
+          - string properties → <input type="text" />
+          - bool properties → <input type="checkbox" />
+          - number properties → <input type="number" />
+          - DateTime properties → <input type="date" />
+          - Guid FK properties (e.g., EmployeeId, DepartmentId) → <EntityLookup /> (NEVER plain text input!)
+
+          For FK fields, use EntityLookup from @/components/ui/EntityLookup:
+          <EntityLookup
+            apiEndpoint="/api/{related-entity-route}"
+            value={data.relatedEntityId}
+            onChange={(id) => handleChange('relatedEntityId', id)}
+            label="Related Entity"
+            mapOption={(item) => ({ id: item.id, label: item.name, sublabel: item.code })}
+            required
+          />
+
+          See smartstack-frontend.md section 6 for the full EntityLookup pattern.
+        */}
         <div className="text-[var(--text-secondary)] text-center py-8">
           Add your form fields here
         </div>

package/templates/skills/apex/SKILL.md

@@ -91,6 +91,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | File | Purpose | Loaded by |
 |------|---------|-----------|
+| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01, step-03 |
 | `references/smartstack-layers.md` | Layer execution rules, skill/MCP mapping, seed data | step-02, step-03 |
 | `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 |
 </reference_files>
@@ -108,6 +109,26 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 </execution_rules>
 
+<error_handling>
+
+## Error Handling Strategy
+
+| Error | Action | Max Retries |
+|-------|--------|-------------|
+| `dotnet build` fails | Identify error, fix via skill/MCP, rebuild | 3 |
+| `npm run typecheck` fails | Fix TypeScript error, retry | 3 |
+| MCP unavailable | Degraded mode: use `smartstack-api.md` as sole reference, no MCP validation | — |
+| File lock (MSB3021) | Auto-use `--output /tmp/{project}_build` for build verification | — |
+| NuGet restore required | Run `dotnet restore` before first `dotnet build` | 1 |
+| Migration fails | Rollback migration (`dotnet ef migrations remove`), fix entity/config, retry | 2 |
+| MCP scaffold output wrong | Verify against `smartstack-api.md` patterns, fix manually | — |
+| POST-CHECK fails | Return to step-03, fix the issue, re-validate | 2 |
+| Stuck after max retries | AskUserQuestion with options: "Try alternative", "Skip", "Discuss" | — |
+
+**Principle:** Always fix CODE, never bypass checks. If stuck, escalate to user.
+
+</error_handling>
+
 <success_criteria>
 - SmartStack context detected (context/app/module)
 - Plan validated with skill/MCP mapped for each file

package/templates/skills/apex/references/smartstack-api.md

@@ -0,0 +1,507 @@
+# SmartStack Domain API Reference
+
+> **Source of truth:** `SmartStack.app/src/SmartStack.Domain/Common/`
+> **Loaded by:** step-01 (analyze), step-03 (execute)
+
+---
+
+## BaseEntity
+
+```csharp
+namespace SmartStack.Domain.Common;
+
+public abstract class BaseEntity
+{
+    public Guid Id { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime? UpdatedAt { get; set; }
+}
+```
+
+**ONLY 3 properties.** No Code, no IsDeleted, no RowVersion, no SoftDelete, no CreatedBy/UpdatedBy.
+
+---
+
+## Interfaces
+
+### ITenantEntity (mandatory tenant isolation)
+
+```csharp
+public interface ITenantEntity
+{
+    Guid TenantId { get; }
+}
+```
+
+### IAuditableEntity (audit trail)
+
+```csharp
+public interface IAuditableEntity
+{
+    string? CreatedBy { get; set; }
+    string? UpdatedBy { get; set; }
+}
+```
+
+### IOptionalTenantEntity (nullable tenant)
+
+```csharp
+public interface IOptionalTenantEntity
+{
+    Guid? TenantId { get; }
+}
+```
+
+### IScopedTenantEntity (tenant + scope visibility)
+
+```csharp
+public interface IScopedTenantEntity : IOptionalTenantEntity
+{
+    EntityScope Scope { get; }
+}
+```
+
+### EntityScope enum
+
+```csharp
+public enum EntityScope
+{
+    Tenant = 0,   // Visible only to specific tenant (TenantId required)
+    Shared = 1,   // Visible to all tenants (TenantId null)
+    Platform = 2  // Visible only to platform admins (HasGlobalAccess)
+}
+```
+
+---
+
+## Entity Pattern (tenant-scoped, most common)
+
+```csharp
+using SmartStack.Domain.Common;
+
+namespace {ProjectName}.Domain.Entities.{Context}.{App}.{Module};
+
+public class {Name} : BaseEntity, ITenantEntity, IAuditableEntity
+{
+    // ITenantEntity
+    public Guid TenantId { get; private set; }
+
+    // IAuditableEntity
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Business properties (add your own)
+    public string Code { get; private set; } = null!;
+    public string Name { get; private set; } = null!;
+    public string? Description { get; private set; }
+    public bool IsActive { get; private set; } = true;
+
+    private {Name}() { }
+
+    public static {Name} Create(Guid tenantId, string code, string name)
+    {
+        if (tenantId == Guid.Empty)
+            throw new ArgumentException("TenantId is required", nameof(tenantId));
+
+        return new {Name}
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Code = code.ToLowerInvariant(),
+            Name = name,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+
+    public void Update(string name, string? description)
+    {
+        Name = name;
+        Description = description;
+        UpdatedAt = DateTime.UtcNow;
+    }
+}
+```
+
+---
+
+## Entity Pattern (platform-level, no tenant)
+
+```csharp
+public class {Name} : BaseEntity, IAuditableEntity
+{
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Business properties
+    public string Code { get; private set; } = null!;
+    public string Name { get; private set; } = null!;
+
+    private {Name}() { }
+
+    public static {Name} Create(string code, string name)
+    {
+        return new {Name}
+        {
+            Id = Guid.NewGuid(),
+            Code = code.ToLowerInvariant(),
+            Name = name,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+}
+```
+
+---
+
+## EF Configuration Pattern
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+
+public class {Name}Configuration : IEntityTypeConfiguration<{Name}>
+{
+    public void Configure(EntityTypeBuilder<{Name}> builder)
+    {
+        builder.ToTable("{prefix}{Name}s", "{schema}");
+
+        builder.HasKey(x => x.Id);
+
+        // Tenant (if ITenantEntity)
+        builder.Property(x => x.TenantId).IsRequired();
+        builder.HasIndex(x => x.TenantId)
+            .HasDatabaseName("IX_{prefix}{Name}s_TenantId");
+
+        // Business properties
+        builder.Property(x => x.Code).HasMaxLength(50).IsRequired();
+        builder.Property(x => x.Name).HasMaxLength(100).IsRequired();
+        builder.Property(x => x.Description).HasMaxLength(500);
+
+        // Audit (from IAuditableEntity)
+        builder.Property(x => x.CreatedBy).HasMaxLength(256);
+        builder.Property(x => x.UpdatedBy).HasMaxLength(256);
+
+        // Unique indexes
+        builder.HasIndex(x => new { x.TenantId, x.Code })
+            .IsUnique()
+            .HasDatabaseName("IX_{prefix}{Name}s_Tenant_Code");
+
+        // Relationships
+        // builder.HasMany(x => x.Children)
+        //     .WithOne(x => x.Parent)
+        //     .HasForeignKey(x => x.ParentId)
+        //     .OnDelete(DeleteBehavior.Restrict);
+
+        // Seed data (if applicable)
+        // builder.HasData({Name}SeedData.GetSeedData());
+    }
+}
+```
+
+---
+
+## Service Pattern (tenant-scoped, MANDATORY)
+
+> **CRITICAL:** ALL services MUST inject `ICurrentUser` and filter by `TenantId`. Missing TenantId = OWASP A01 vulnerability.
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+using SmartStack.Application.Common.Interfaces.Identity;
+using SmartStack.Application.Common.Interfaces.Persistence;
+
+namespace {ProjectName}.Infrastructure.Services.{Context}.{App}.{Module};
+
+public class {Name}Service : I{Name}Service
+{
+    private readonly IExtensionsDbContext _db;
+    private readonly ICurrentUser _currentUser;
+    private readonly ILogger<{Name}Service> _logger;
+
+    public {Name}Service(
+        IExtensionsDbContext db,
+        ICurrentUser currentUser,
+        ILogger<{Name}Service> logger)
+    {
+        _db = db;
+        _currentUser = currentUser;
+        _logger = logger;
+    }
+
+    public async Task<PaginatedResult<{Name}ResponseDto>> GetAllAsync(
+        string? search = null,
+        int page = 1,
+        int pageSize = 20,
+        CancellationToken ct = default)
+    {
+        var query = _db.{Name}s
+            .Where(x => x.TenantId == _currentUser.TenantId)  // MANDATORY tenant filter
+            .AsNoTracking();
+
+        // Search filter — enables EntityLookup on frontend
+        if (!string.IsNullOrWhiteSpace(search))
+        {
+            query = query.Where(x =>
+                x.Name.Contains(search) ||
+                x.Code.Contains(search));
+        }
+
+        var totalCount = await query.CountAsync(ct);
+        var items = await query
+            .OrderBy(x => x.Name)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
+            .ToListAsync(ct);
+
+        return new PaginatedResult<{Name}ResponseDto>(items, totalCount, page, pageSize);
+    }
+
+    public async Task<{Name}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
+    {
+        return await _db.{Name}s
+            .Where(x => x.Id == id && x.TenantId == _currentUser.TenantId)  // MANDATORY
+            .AsNoTracking()
+            .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
+            .FirstOrDefaultAsync(ct);
+    }
+
+    public async Task<{Name}ResponseDto> CreateAsync(Create{Name}Dto dto, CancellationToken ct)
+    {
+        var entity = {Name}.Create(
+            tenantId: _currentUser.TenantId,  // MANDATORY — never Guid.Empty
+            code: dto.Code,
+            name: dto.Name);
+
+        entity.CreatedBy = _currentUser.UserId?.ToString();
+
+        _db.{Name}s.Add(entity);
+        await _db.SaveChangesAsync(ct);
+
+        _logger.LogInformation("Created {Entity} {Id} for tenant {TenantId}",
+            nameof({Name}), entity.Id, _currentUser.TenantId);
+
+        return new {Name}ResponseDto(entity.Id, entity.Code, entity.Name, entity.CreatedAt);
+    }
+
+    public async Task DeleteAsync(Guid id, CancellationToken ct)
+    {
+        var entity = await _db.{Name}s
+            .FirstOrDefaultAsync(x => x.Id == id && x.TenantId == _currentUser.TenantId, ct)
+            ?? throw new KeyNotFoundException($"{Name} {id} not found");
+
+        _db.{Name}s.Remove(entity);
+        await _db.SaveChangesAsync(ct);
+    }
+}
+```
+
+**Key interfaces:**
+- `ICurrentUser` (from `SmartStack.Application.Common.Interfaces.Identity`): provides `TenantId`, `UserId`, `Email`
+- `IExtensionsDbContext` (for client extensions) or `ICoreDbContext` (for platform)
+
+**FORBIDDEN in services:**
+- `tenantId: Guid.Empty` — always use `_currentUser.TenantId`
+- Queries WITHOUT `.Where(x => x.TenantId == _currentUser.TenantId)` — data leak
+- Missing `ILogger<T>` — undiagnosable in production
+
+---
+
+## Controller Pattern (NavRoute)
+
+```csharp
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using SmartStack.Api.Routing;
+using SmartStack.Api.Authorization;
+
+namespace {ProjectName}.Api.Controllers.{Context}.{App};
+
+[ApiController]
+[NavRoute("{context}.{app}.{module}")]
+[Authorize]
+public class {Name}Controller : ControllerBase
+{
+    private readonly I{Name}Service _service;
+    private readonly ILogger<{Name}Controller> _logger;
+
+    public {Name}Controller(I{Name}Service service, ILogger<{Name}Controller> logger)
+    {
+        _service = service;
+        _logger = logger;
+    }
+
+    [HttpGet]
+    [RequirePermission(Permissions.{Module}.Read)]
+    public async Task<ActionResult<PaginatedResult<{Name}ResponseDto>>> GetAll(
+        [FromQuery] string? search = null,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20,
+        CancellationToken ct = default)
+        => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
+
+    [HttpGet("{id:guid}")]
+    [RequirePermission(Permissions.{Module}.Read)]
+    public async Task<ActionResult<{Name}ResponseDto>> GetById(Guid id, CancellationToken ct)
+    {
+        var result = await _service.GetByIdAsync(id, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    [RequirePermission(Permissions.{Module}.Create)]
+    public async Task<ActionResult<{Name}ResponseDto>> Create([FromBody] Create{Name}Dto dto, CancellationToken ct)
+    {
+        var result = await _service.CreateAsync(dto, ct);
+        return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+    }
+
+    [HttpDelete("{id:guid}")]
+    [RequirePermission(Permissions.{Module}.Delete)]
+    public async Task<ActionResult> Delete(Guid id, CancellationToken ct)
+    {
+        await _service.DeleteAsync(id, ct);
+        return NoContent();
+    }
+}
+```
+
+**CRITICAL:** Use `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint — NEVER `[Authorize]` alone (no RBAC enforcement).
+
+**Namespace:** `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
+
+**NavRoute resolves at startup from DB:** `platform.administration.users` → `api/platform/administration/users`
+
+---
+
+## Navigation Seed Data Pattern (CRITICAL — routes must be full paths)
+
+> **The navigation seed data defines menu routes stored in DB. These routes MUST be full paths starting with `/`.**
+> Short routes (e.g., `humanresources`) cause 400 Bad Request on application-tracking.
+
+### Route Convention
+
+| Level | Route Format | Example |
+|-------|-------------|---------|
+| Application | `/{context}/{app-kebab}` | `/business/human-resources` |
+| Module | `/{context}/{app-kebab}/{module-kebab}` | `/business/human-resources/employees` |
+| Section | `/{context}/{app-kebab}/{module-kebab}/{section-kebab}` | `/business/human-resources/employees/list` |
+| Resource | `/{context}/{app-kebab}/{module-kebab}/{section-kebab}/{resource-kebab}` | `/business/human-resources/employees/list/export` |
+
+**Rules:**
+- Routes ALWAYS start with `/`
+- Routes ALWAYS include the full hierarchy from context to current level
+- Routes ALWAYS use kebab-case (NOT PascalCase, NOT camelCase)
+- Code identifiers stay PascalCase in C# (`HumanResources`) but routes are kebab-case (`human-resources`)
+
+### ToKebabCase Helper (include in SeedConstants or SeedDataProvider)
+
+```csharp
+private static string ToKebabCase(string value)
+    => System.Text.RegularExpressions.Regex
+        .Replace(value, "(?<!^)([A-Z])", "-$1")
+        .ToLowerInvariant();
+```
+
+### SeedConstants Pattern
+
+```csharp
+public static class SeedConstants
+{
+    // Deterministic GUIDs (SHA256-based, reproducible across environments)
+    public static readonly Guid ApplicationId = DeterministicGuid("nav:business.humanresources");
+    public static readonly Guid ModuleId = DeterministicGuid("nav:business.humanresources.employees");
+    public static readonly Guid SectionId = DeterministicGuid("nav:business.humanresources.employees.list");
+
+    private static Guid DeterministicGuid(string input)
+    {
+        var hash = System.Security.Cryptography.SHA256.HashData(
+            System.Text.Encoding.UTF8.GetBytes(input));
+        var bytes = new byte[16];
+        Array.Copy(hash, bytes, 16);
+        bytes[6] = (byte)((bytes[6] & 0x0F) | 0x50); // version 5
+        bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80); // variant
+        return new Guid(bytes);
+    }
+}
+```
+
+### Navigation Seed Data Example
+
+```csharp
+// Application: /business/human-resources
+var app = NavigationApplication.Create(
+    businessCtx.Id, "humanresources", "Human Resources", "HR Management",
+    "Users", IconType.Lucide,
+    "/business/human-resources",  // FULL PATH — starts with /, kebab-case
+    10);
+
+// Module: /business/human-resources/employees
+var module = NavigationModule.Create(
+    app.Id, "employees", "Employees", "Employee management",
+    "UserCheck", IconType.Lucide,
+    "/business/human-resources/employees",  // FULL PATH — includes parent
+    10);
+
+// Section: /business/human-resources/employees/departments
+var section = NavigationSection.Create(
+    module.Id, "departments", "Departments", "Manage departments",
+    "Building2", IconType.Lucide,
+    "/business/human-resources/employees/departments",  // FULL PATH
+    10);
+```
+
+### FORBIDDEN in Seed Data
+
+| Mistake | Reality |
+|---------|---------|
+| `"humanresources"` as route | Must be `"/business/human-resources"` (full path, kebab-case) |
+| `"employees"` as route | Must be `"/business/human-resources/employees"` (includes parent) |
+| `Guid.NewGuid()` in seed data | Must use deterministic GUIDs (SHA256) |
+| Missing translations | Must have 4 languages: fr, en, it, de |
+| Missing NavigationApplicationSeedData | Menu invisible without Application level |
+
+---
+
+## DbContext Pattern (extensions)
+
+```csharp
+// In IExtensionsDbContext.cs:
+public DbSet<{Name}> {Name}s => Set<{Name}>();
+
+// In ExtensionsDbContext.cs (same line):
+public DbSet<{Name}> {Name}s => Set<{Name}>();
+```
+
+---
+
+## DI Registration Pattern
+
+```csharp
+// In DependencyInjection.cs or ServiceCollectionExtensions.cs:
+services.AddScoped<I{Name}Service, {Name}Service>();
+services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
+```
+
+---
+
+## Common Mistakes to Avoid
+
+| Mistake | Reality |
+|---------|---------|
+| `entity.SoftDelete()` | Does NOT exist — no soft delete in BaseEntity |
+| `entity.Code` inherited | Code is a business property — add it yourself |
+| `e.RowVersion` in config | Does NOT exist in BaseEntity |
+| `e.IsDeleted` filter | Does NOT exist — no soft delete |
+| `SmartStack.Api.Core.Routing` | Wrong — use `SmartStack.Api.Routing` |
+| `SystemEntity` base class | Does NOT exist — use `BaseEntity` for all |
+| `[Route] + [NavRoute]` | Only `[NavRoute]` needed (resolves route from DB) |
+| `SmartStack.Domain.Common.Interfaces` | Wrong — interfaces are in `SmartStack.Domain.Common` directly |
+| `[Authorize]` without `[RequirePermission]` | No RBAC enforcement — always use `[RequirePermission]` |
+| `tenantId: Guid.Empty` in services | OWASP A01 — always use `_currentUser.TenantId` |
+| Service without `ICurrentUser` | All tenant data leaks — inject `ICurrentUser` |
+| Route `"humanresources"` in seed data | Must be full path `"/business/human-resources"` |
+| Route without leading `/` | All routes must start with `/` |
+| `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
+| `GetAllAsync()` without search param | ALL GetAll endpoints MUST support `?search=` for EntityLookup |
+| FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |