@atlashub/smartstack-cli 3.25.0 → 3.27.0

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

@@ -202,12 +202,13 @@ public class {Name}Configuration : IEntityTypeConfiguration<{Name}>
 
 ## Service Pattern (tenant-scoped, MANDATORY)
 
-> **CRITICAL:** ALL services MUST inject `ICurrentUser` and filter by `TenantId`. Missing TenantId = OWASP A01 vulnerability.
+> **CRITICAL:** ALL services MUST inject `ICurrentUserService` + `ICurrentTenantService` 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.Tenants;
 using SmartStack.Application.Common.Interfaces.Persistence;
 
 namespace {ProjectName}.Infrastructure.Services.{Context}.{App}.{Module};
@@ -215,16 +216,19 @@ namespace {ProjectName}.Infrastructure.Services.{Context}.{App}.{Module};
 public class {Name}Service : I{Name}Service
 {
     private readonly IExtensionsDbContext _db;
-    private readonly ICurrentUser _currentUser;
+    private readonly ICurrentUserService _currentUser;
+    private readonly ICurrentTenantService _currentTenant;
     private readonly ILogger<{Name}Service> _logger;
 
     public {Name}Service(
         IExtensionsDbContext db,
-        ICurrentUser currentUser,
+        ICurrentUserService currentUser,
+        ICurrentTenantService currentTenant,
         ILogger<{Name}Service> logger)
     {
         _db = db;
         _currentUser = currentUser;
+        _currentTenant = currentTenant;
         _logger = logger;
     }
 
@@ -234,8 +238,12 @@ public class {Name}Service : I{Name}Service
         int pageSize = 20,
         CancellationToken ct = default)
     {
+        // MANDATORY guard — throws 401 if no tenant context (e.g., missing X-Tenant-Slug header)
+        var tenantId = _currentTenant.TenantId
+            ?? throw new UnauthorizedAccessException("Tenant context is required");
+
         var query = _db.{Name}s
-            .Where(x => x.TenantId == _currentUser.TenantId)  // MANDATORY tenant filter
+            .Where(x => x.TenantId == tenantId)  // MANDATORY tenant filter
             .AsNoTracking();
 
         // Search filter — enables EntityLookup on frontend
@@ -259,8 +267,11 @@ public class {Name}Service : I{Name}Service
 
     public async Task<{Name}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
     {
+        var tenantId = _currentTenant.TenantId
+            ?? throw new UnauthorizedAccessException("Tenant context is required");
+
         return await _db.{Name}s
-            .Where(x => x.Id == id && x.TenantId == _currentUser.TenantId)  // MANDATORY
+            .Where(x => x.Id == id && x.TenantId == tenantId)  // MANDATORY
             .AsNoTracking()
             .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
             .FirstOrDefaultAsync(ct);
@@ -268,8 +279,11 @@ public class {Name}Service : I{Name}Service
 
     public async Task<{Name}ResponseDto> CreateAsync(Create{Name}Dto dto, CancellationToken ct)
     {
+        var tenantId = _currentTenant.TenantId
+            ?? throw new UnauthorizedAccessException("Tenant context is required");
+
         var entity = {Name}.Create(
-            tenantId: _currentUser.TenantId,  // MANDATORY — never Guid.Empty
+            tenantId: tenantId,  // MANDATORY — never Guid.Empty
             code: dto.Code,
             name: dto.Name);
 
@@ -279,15 +293,18 @@ public class {Name}Service : I{Name}Service
         await _db.SaveChangesAsync(ct);
 
         _logger.LogInformation("Created {Entity} {Id} for tenant {TenantId}",
-            nameof({Name}), entity.Id, _currentUser.TenantId);
+            nameof({Name}), entity.Id, tenantId);
 
         return new {Name}ResponseDto(entity.Id, entity.Code, entity.Name, entity.CreatedAt);
     }
 
     public async Task DeleteAsync(Guid id, CancellationToken ct)
     {
+        var tenantId = _currentTenant.TenantId
+            ?? throw new UnauthorizedAccessException("Tenant context is required");
+
         var entity = await _db.{Name}s
-            .FirstOrDefaultAsync(x => x.Id == id && x.TenantId == _currentUser.TenantId, ct)
+            .FirstOrDefaultAsync(x => x.Id == id && x.TenantId == tenantId, ct)
             ?? throw new KeyNotFoundException($"{Name} {id} not found");
 
         _db.{Name}s.Remove(entity);
@@ -296,14 +313,24 @@ public class {Name}Service : I{Name}Service
 }
 ```
 
-**Key interfaces:**
-- `ICurrentUser` (from `SmartStack.Application.Common.Interfaces.Identity`): provides `TenantId`, `UserId`, `Email`
+**Key interfaces (from SmartStack NuGet package):**
+- `ICurrentUserService` (from `SmartStack.Application.Common.Interfaces.Identity`): provides `UserId` (Guid?), `Email` (string?), `IsAuthenticated` (bool)
+- `ICurrentTenantService` (from `SmartStack.Application.Common.Interfaces.Tenants`): provides `TenantId` (Guid?), `HasTenant` (bool), `TenantSlug` (string?)
 - `IExtensionsDbContext` (for client extensions) or `ICoreDbContext` (for platform)
 
+**MANDATORY guard clause (first line of every method):**
+```csharp
+var tenantId = _currentTenant.TenantId
+    ?? throw new UnauthorizedAccessException("Tenant context is required");
+```
+This converts a null TenantId into a clean 401 response via `GlobalExceptionHandlerMiddleware`.
+
 **FORBIDDEN in services:**
-- `tenantId: Guid.Empty` — always use `_currentUser.TenantId`
-- Queries WITHOUT `.Where(x => x.TenantId == _currentUser.TenantId)` — data leak
+- `_currentTenant.TenantId!.Value` — throws `InvalidOperationException` (500) instead of clean 401
+- `tenantId: Guid.Empty` — always use validated tenantId from guard clause
+- Queries WITHOUT `.Where(x => x.TenantId == tenantId)` — data leak
 - Missing `ILogger<T>` — undiagnosable in production
+- Using `ICurrentUser` (does NOT exist) — use `ICurrentUserService` + `ICurrentTenantService`
 
 ---
 
@@ -405,14 +432,25 @@ private static string ToKebabCase(string value)
 
 ### SeedConstants Pattern
 
+> **CRITICAL — NavigationContext IDs are NEVER generated.**
+> Contexts (`business`, `platform`, `personal`) are pre-seeded by SmartStack core with hardcoded GUIDs.
+> You MUST query the context by code at runtime in the SeedDataProvider:
+> `var ctx = await db.NavigationContexts.FirstOrDefaultAsync(c => c.Code == "business", ct);`
+> **FORBIDDEN:** `DeterministicGuid("nav:business")` or any ContextId constant in SeedConstants.
+
 ```csharp
 public static class SeedConstants
 {
     // Deterministic GUIDs (SHA256-based, reproducible across environments)
+    // NOTE: Application/Module/Section/Resource IDs are deterministic.
+    //       Context IDs are NOT — they are pre-seeded by SmartStack core.
     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");
 
+    // FORBIDDEN — Context IDs are NOT deterministic, they come from SmartStack core:
+    // public static readonly Guid BusinessContextId = DeterministicGuid("nav:business"); // WRONG!
+
     private static Guid DeterministicGuid(string input)
     {
         var hash = System.Security.Cryptography.SHA256.HashData(
@@ -429,6 +467,11 @@ public static class SeedConstants
 ### Navigation Seed Data Example
 
 ```csharp
+// CRITICAL: Look up the context by code — NEVER use a hardcoded/deterministic GUID
+var businessCtx = await db.NavigationContexts
+    .FirstOrDefaultAsync(c => c.Code == "business", ct);
+if (businessCtx == null) return; // Context not yet seeded by SmartStack core
+
 // Application: /business/human-resources
 var app = NavigationApplication.Create(
     businessCtx.Id, "humanresources", "Human Resources", "HR Management",
@@ -458,6 +501,7 @@ var section = NavigationSection.Create(
 | `"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) |
+| `DeterministicGuid("nav:business")` for ContextId | Context IDs are pre-seeded by SmartStack core — look up by code |
 | Missing translations | Must have 4 languages: fr, en, it, de |
 | Missing NavigationApplicationSeedData | Menu invisible without Application level |
 
@@ -498,8 +542,10 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `[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` |
+| `tenantId: Guid.Empty` in services | OWASP A01 — always use validated `_currentTenant.TenantId` |
+| Service without `ICurrentTenantService` | All tenant data leaks — inject `ICurrentTenantService` |
+| `ICurrentUser` in service code | Does NOT exist — use `ICurrentUserService` + `ICurrentTenantService` |
+| `_currentTenant.TenantId!.Value` | Crashes with 500 — use `?? throw new UnauthorizedAccessException(...)` |
 | 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. |
@@ -648,3 +694,34 @@ public class UpdateMyEntityDtoValidator : AbstractValidator<UpdateMyEntityDto>
 ```
 
 **Why it's wrong:** Without an `UpdateValidator`, the Update endpoint accepts **any data without validation**.
+
+---
+
+### Anti-Pattern 6: `TenantId!.Value` null-forgiving operator (RUNTIME CRASH)
+
+The `!` (null-forgiving) operator followed by `.Value` on a `Guid?` suppresses compiler warnings but **throws `InvalidOperationException` at runtime** when TenantId is null.
+
+**INCORRECT — Crashes with 500 Internal Server Error:**
+```csharp
+// WRONG: Throws InvalidOperationException("Nullable object must have a value") → 500 error
+public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
+{
+    var tenantId = _currentTenant.TenantId!.Value;  // CRASH if no tenant context
+    var query = _db.MyEntities.Where(x => x.TenantId == tenantId);
+    // ...
+}
+```
+
+**CORRECT — Clean 401 via GlobalExceptionHandlerMiddleware:**
+```csharp
+// CORRECT: Throws UnauthorizedAccessException → middleware converts to 401
+public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
+{
+    var tenantId = _currentTenant.TenantId
+        ?? throw new UnauthorizedAccessException("Tenant context is required");
+    var query = _db.MyEntities.Where(x => x.TenantId == tenantId);
+    // ...
+}
+```
+
+**Why it's wrong:** When a user hits an API via Swagger with a valid JWT but no tenant context (missing `X-Tenant-Slug` header), `TenantId` is null. The `!.Value` pattern produces an opaque `500 Internal Server Error` instead of a clear `401 Unauthorized` with an actionable message. The `?? throw new UnauthorizedAccessException(...)` pattern is caught by `GlobalExceptionHandlerMiddleware` and returned as a proper 401 response.

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

@@ -62,13 +62,14 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
-- **ALL services MUST inject `ICurrentUser` and filter by `TenantId`** (see `smartstack-api.md` Service Pattern)
+- **ALL services MUST inject `ICurrentUserService` + `ICurrentTenantService` and filter by `TenantId`** (see `smartstack-api.md` Service Pattern)
+- **ALL services MUST use guard clause:** `var tenantId = _currentTenant.TenantId ?? throw new UnauthorizedAccessException("Tenant context is required");`
 - **ALL services MUST inject `ILogger<T>`** for production diagnostics
 - CQRS with MediatR
 - FluentValidation for all commands
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
-- **FORBIDDEN:** `tenantId: Guid.Empty`, queries without TenantId filter, services without ICurrentUser
+- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`)
 
 ---
 
@@ -118,18 +119,28 @@
 3. **NavigationSectionSeedData.cs** — Section-level navigation (if sections defined)
 4. **NavigationResourceSeedData.cs** — Resource-level navigation (if resources defined)
 5. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
-6. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
+6. **RolesSeedData.cs** — Code-based role mapping: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R. **NEVER use deterministic GUIDs for roles** — system roles are pre-seeded by SmartStack core, look up by Code at runtime.
 7. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
    - `SeedNavigationAsync()` — seeds Application → Module → Section → Resource + translations
-   - `SeedPermissionsAsync()` + `SeedRolePermissionsAsync()`
+   - `SeedPermissionsAsync()` + `SeedRolePermissionsAsync()` (roles resolved by Code, NOT by GUID)
    - DI: `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()`
 
 ### Deterministic GUID Pattern
 
+> **CRITICAL — NavigationContext IDs are NEVER generated.**
+> Contexts (`business`, `platform`, `personal`) are pre-seeded by SmartStack core with hardcoded GUIDs.
+> Look up the context at runtime: `db.NavigationContexts.FirstOrDefaultAsync(c => c.Code == "business", ct)`
+> **FORBIDDEN:** `GenerateDeterministicGuid("nav:business")` or any ContextId in SeedConstants.
+
 ```csharp
 // Use SHA256 for deterministic GUIDs (reproducible across environments)
+// NOTE: Application/Module/Section/Resource IDs are deterministic.
+//       Context IDs are NOT — they are pre-seeded by SmartStack core.
 public static readonly Guid ModuleId = GenerateDeterministicGuid("nav-module-{app}-{module}");
 
+// FORBIDDEN — Context IDs must NOT be generated:
+// public static readonly Guid BusinessContextId = GenerateDeterministicGuid("nav:business"); // WRONG!
+
 private static Guid GenerateDeterministicGuid(string input)
 {
     var hash = System.Security.Cryptography.SHA256.HashData(
@@ -181,6 +192,7 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 
 **FORBIDDEN:**
 - `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
+- `DeterministicGuid("nav:business")` for ContextId → context IDs are pre-seeded by SmartStack core, look up by code at runtime
 - Missing translations (must have fr, en, it, de)
 - Empty seed classes with no seeding logic
 - PascalCase in route URLs → always kebab-case

package/templates/skills/apex/steps/step-00-init.md

@@ -1,6 +1,6 @@
 ---
 name: step-00-init
-description: Parse flags, detect SmartStack context, verify MCP availability
+description: Parse flags, detect context, verify MCP, define hierarchy (5 levels), challenge the need
 model: sonnet
 next_step: steps/step-01-analyze.md
 ---
@@ -67,21 +67,7 @@ Scan the project to identify the SmartStack hierarchy:
 - `{prd_path}`: `.ralph/prd-{module_code}.json` if exists
 - `{feature_path}`: `docs/business/{app}/{module}/business-analyse/*/feature.json` if exists
 
-**If hierarchy cannot be inferred, ask the user:**
-
-```yaml
-questions:
-  - header: "Context"
-    question: "What is the SmartStack context for this work?"
-    options:
-      - label: "Business (Recommended)"
-        description: "Business application module"
-      - label: "Platform"
-        description: "Platform administration or support"
-      - label: "Personal"
-        description: "Personal user space"
-    multiSelect: false
-```
+If hierarchy cannot be inferred → load context detection question from `references/challenge-questions.md`.
 
 ---
 
@@ -96,70 +82,112 @@ IF failure → warn user, continue in degraded mode (manual tools only)
 
 ---
 
-## 4. Determine Needs
+## 4. Define Navigation Hierarchy (5 Levels)
+
+> **BLOCKING RULE:** SmartStack uses a 5-level navigation hierarchy:
+> **Context → Application → Module → Section → Resource**
+>
+> **Every module MUST have at least one section.** A module without sections produces an incomplete navigation tree, broken seed data, and missing frontend routes.
+
+### 4a. Validate Application Level
+
+Load and execute application question from `references/challenge-questions.md` section 4a.
+
+### 4b. Validate Module Level
+
+Load and execute module question from `references/challenge-questions.md` section 4b.
+
+### 4c. Define Sections (MANDATORY — at least one)
+
+Load and execute section questions from `references/challenge-questions.md` section 4c (includes validation and storage format).
 
+### 4d. Resources (Optional)
+
+If the task or feature.json mentions specific resources (export, import, bulk actions):
+```
+For each section, check if resources are needed.
+Resources are OPTIONAL — only define if explicitly mentioned or inferred.
 ```
-needs_seed_data = true IF:
-  - New module or new section with navigation entries
-  - Task mentions "navigation", "permissions", "roles", "seed"
 
-needs_migration = true IF:
-  - New entities or entity modifications detected
-  - Task mentions "entity", "field", "table", "column", "migration"
+### 4e. Hierarchy Summary
+
+Display before proceeding:
+
+```
+{context_code} → {app_name} ({app_code}) → {module_code} → [{sections[].code}]
+Routes: /{context_code}/{app-kebab}/{module-kebab}/{section-kebab}
 ```
 
 ---
 
-## 5. Resume Mode (if -r)
+## 5. Challenge the Need
+
+> **Objective:** Even without a formal Business Analysis (`/business-analyse`), the need MUST be challenged to avoid obvious gaps. This is a rapid scope validation — 3-4 targeted questions to ensure the developer has thought through the fundamentals.
+
+### 5a. Entity Scope & Relationships
+
+Load and execute entity questions from `references/challenge-questions.md` section 5a.
+
+### 5b. Dependencies & Key Properties
+
+Load and execute dependency questions from `references/challenge-questions.md` section 5b.
 
+### 5c. Store Responses
+
+```yaml
+{entities}: string[]            # Main entities to manage
+{module_complexity}: string     # "simple-crud" | "crud-rules" | "crud-workflow" | "complex"
+{has_dependencies}: string      # "none" | "references" | "unknown"
+{key_properties}: string[]      # Key business properties mentioned by user
 ```
-IF resume_mode:
-  1. Read .claude/output/apex/ → find latest task folder
-  2. Read 00-context.md → restore state variables
-  3. Find last completed step file
-  4. Route to next step directly
-  → SKIP to identified next step
+
+These values are propagated to:
+- **step-01 (Analyze):** Guide code exploration focus
+- **step-02 (Plan):** Inform layer mapping (e.g., workflow → needs /workflow skill)
+- **step-03 (Execute):** Entity scaffolding with correct properties and relationships
+
+---
+
+## 6. Determine Needs
+
+```
+needs_seed_data   = {sections}.length > 0 OR task mentions navigation/permissions/roles/seed
+needs_migration   = {entities}.length > 0 OR task mentions entity/field/table/column/migration
+needs_workflow    = {module_complexity} == "crud-workflow" OR task mentions workflow/email/approval
+needs_notification = {module_complexity} in ["crud-workflow","complex"] OR task mentions notification/alert
 ```
 
 ---
 
-## 6. Save Mode Setup (if -s)
+## 7. Resume Mode (if -r)
 
 ```
-IF save_mode:
-  1. Generate task_id: NN-kebab-case from task_description
-  2. Create .claude/output/apex/{task_id}/
-  3. Write 00-context.md with:
-     - Timestamp
-     - All state variables (generic + SmartStack)
-     - Flags
-     - Detected hierarchy
+IF resume_mode:
+  Read .claude/output/apex/ → find latest task → restore state from 00-context.md → SKIP to next step
 ```
 
 ---
 
-## 7. Display Context Summary
+## 8. Save Mode Setup (if -s)
 
 ```
-═══════════════════════════════════════════════════════════════
-  APEX INITIALIZATION COMPLETE
-  SmartStack CLI v{{SMARTSTACK_VERSION}}
-═══════════════════════════════════════════════════════════════
+IF save_mode:
+  Generate task_id → create .claude/output/apex/{task_id}/ → write 00-context.md
+  (timestamp, state variables, flags, hierarchy, challenge responses)
+```
 
-| Field              | Value                                        |
-|--------------------|----------------------------------------------|
-| Task               | {task_description}                            |
-| Context            | {context_code} / {app_name} / {module_code}  |
-| Sections           | {sections}                                   |
-| PRD                | {prd_path || "none"}                          |
-| Feature            | {feature_path || "none"}                     |
-| Flags              | {active_flags}                               |
-| MCP                | {available|degraded}                         |
-| Needs migration    | {yes|no}                                     |
-| Needs seed data    | {yes|no}                                     |
+---
+
+## 9. Display Context Summary
 
+```
+APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
+Task: {task_description}
+Context: {context_code} → {app_name} → {module_code} → {sections[].code}
+Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
+PRD: {prd_path||none} | Feature: {feature_path||none} | Flags: {active_flags}
+MCP: {available|degraded} | Needs: migration/seed/workflow/notification = {yes|no}
 NEXT STEP: step-01-analyze
-═══════════════════════════════════════════════════════════════
 ```
 
 ---