@atlashub/smartstack-cli 3.37.0 → 3.38.0

package/templates/skills/application/references/migration-checklist-troubleshooting.md

@@ -0,0 +1,100 @@
+# Migration: Checklist & Troubleshooting
+
+> Referenced from `steps/step-06-migration.md` — Migration verification and common issues.
+
+---
+
+## Pre-Migration Build Verification (BLOCKING)
+
+**CRITICAL:** The backend MUST build successfully before creating a migration.
+EF Core tools compile the project internally; a build failure produces confusing errors
+that do not point to the actual source file.
+
+```bash
+dotnet build {SolutionName}.sln --no-restore
+```
+
+**Common causes at this stage:**
+- Missing DbSet registration (should have been caught in step-04 Check 2)
+- Missing DI registration (should have been caught in step-04 Check 3)
+- Circular references between generated services
+- Missing package references (e.g., FluentValidation)
+- Frontend changes that modified shared files
+
+**After build succeeds:** Continue to migration name suggestion.
+
+---
+
+## Migration Content Verification
+
+The migration should include:
+- Navigation entity (Application/Module/Section)
+- Navigation translations (4 languages)
+- Permissions (CRUD + wildcard)
+- RolePermissions (role assignments)
+- Domain entity table
+- Indexes and constraints
+- SQL Objects injection (if any .sql files exist)
+
+---
+
+## SQL Objects Injection
+
+Check if any SQL object files exist:
+```
+Glob: **/Persistence/SqlObjects/Functions/*.sql
+```
+
+If SQL files are found, the migration's `Up()` method should include a call to re-apply all SQL objects:
+```csharp
+// At the end of the Up() method:
+SqlObjectHelper.ApplyAll(migrationBuilder);
+```
+
+This ensures SQL functions/views are re-applied with each migration (`CREATE OR ALTER` = idempotent).
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Migration conflicts | Run `/efcore:conflicts` to analyze |
+| Permission 403 errors | Verify Permissions.cs and PermissionConfiguration.cs are in sync |
+| Navigation not visible | Check user role has appropriate permissions |
+| Route not found | Verify nested route structure in routes.tsx |
+| i18n missing | Check locale files exist and are properly loaded |
+| EF Core compilation error | Check DbSet and DI registration |
+| FK constraint errors | Verify all entity references exist in seed data |
+
+### Quick Fixes
+
+```bash
+# Rebuild and restart
+dotnet build
+dotnet ef database update
+
+# Clear frontend cache
+cd web && rm -rf node_modules/.cache && npm run dev
+
+# Reset database (development only)
+dotnet ef database drop --context CoreDbContext --force
+dotnet ef database update --context CoreDbContext
+```
+
+---
+
+## Final Checklist
+
+- [ ] Pre-migration build passed
+- [ ] Migration name suggested via MCP
+- [ ] Migration created with correct context
+- [ ] Migration includes navigation, permissions, and entity table
+- [ ] SQL objects injected (if applicable)
+- [ ] Migration applied successfully
+- [ ] Database updated without errors
+- [ ] DbSet registered in DbContext
+- [ ] DI registration in place
+- [ ] Application starts without errors

package/templates/skills/application/references/nav-fallback-procedure.md

@@ -25,7 +25,7 @@
 
 3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
    ```
-   Read the Configuration for the target level (Context, Application, Module, Section).
+   Read the Configuration for the target level (Application, Module, Section).
    Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
    If yes: Read the corresponding SeedData class to find existing entries.
    If no: You will need to add HasData() call.
@@ -39,11 +39,11 @@
 
 ## F2. Determine Parent GUID
 
-For non-context levels, find the parent entity GUID:
+For non-application levels, find the parent entity GUID:
 
 | Level | Parent | Where to Find Parent GUID |
 |-------|--------|---------------------------|
-| application | context | `NavigationContextSeedData.cs` → e.g. `PlatformContextId` |
+| application | (none — top level) | — |
 | module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
 | section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
 
@@ -99,8 +99,7 @@ new {
 
 | Level | FK Property | References |
 |-------|-------------|------------|
-| context | (none) | - |
-| application | `ContextId` | NavigationContextSeedData.{Parent}Id |
+| application | (none — top level) | — |
 | module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
 | section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
 
@@ -180,7 +179,7 @@ Before proceeding, verify:
 - [ ] 4 languages present (fr, en, it, de)
 - [ ] Translation index continues existing sequence (no gaps, no collisions)
 - [ ] Parent GUID correctly references existing entity
-- [ ] Route path matches `/{context}/{app}/{module}` pattern
+- [ ] Route path matches `/{app}/{module}` pattern
 - [ ] DisplayOrder is consistent with existing entities
 - [ ] Code is WRITTEN to files, not just displayed
 

package/templates/skills/application/references/provider-template.md

@@ -31,7 +31,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
     {
         // --- Application (idempotent — reuse if already exists) ---
-        var appEntry = NavigationApplicationSeedData.GetApplicationEntry(Guid.Empty);
+        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
         var existingApp = await context.NavigationApplications
             .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
 
@@ -42,12 +42,8 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         }
         else
         {
-            var parentContext = await context.NavigationContexts
-                .FirstAsync(c => c.Code == "{context_code}", ct);
-
-            appEntry = NavigationApplicationSeedData.GetApplicationEntry(parentContext.Id);
             app = NavigationApplication.Create(
-                appEntry.ContextId, appEntry.Code, appEntry.Label,
+                appEntry.Code, appEntry.Label,
                 appEntry.Description, appEntry.Icon, appEntry.IconType,
                 appEntry.Route, appEntry.DisplayOrder);
             context.NavigationApplications.Add(app);

package/templates/skills/application/references/roles-client-project-handling.md

@@ -0,0 +1,55 @@
+# Step 3: Client Project Handling (seeding_strategy = "provider")
+
+> Referenced from `steps/step-03-roles.md` — Specific handling for client projects.
+
+---
+
+## ApplicationRolesSeedData.cs (ONCE per application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
+
+**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
+
+See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
+
+**Key requirements:**
+- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
+- 4 roles: Admin, Manager, Contributor, Viewer
+- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
+- `ApplicationId` references the navigation application GUID
+- `IsSystem = false` (application-scoped, not system roles)
+
+**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
+
+---
+
+## {Module}RolePermissionSeedData.cs (PER module)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
+
+Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
+These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
+
+---
+
+## Default Role Mapping Table
+
+Based on navigation application prefix:
+
+| Application prefix | PlatformAdmin | TenantAdmin | StandardUser |
+|---------|---------------|-------------|--------------|
+| `administration.*` | Full CRUD | Read only | None |
+| `*` (business apps) | Full CRUD | Full CRUD | Read only |
+| `myspace.*` | None | Full CRUD | Full CRUD |
+
+---
+
+## Summary
+
+After creating both files:
+- Proceed to step-03b-provider.md (which will skip for core projects)
+- The provider will consume these SeedData files to seed roles and permissions at runtime

package/templates/skills/application/references/roles-fallback-procedure.md

@@ -0,0 +1,149 @@
+# Role-Permission Generation: Fallback Procedure (When MCP Unavailable)
+
+> Reference for step-03-roles.md — Generates role-permission HasData entries following SmartStack.app patterns.
+
+---
+
+## F1. Read Existing RolePermissionConfiguration.cs
+
+```
+Glob: **/Persistence/Configurations/Authorization/RolePermissionConfiguration.cs
+```
+
+Read the file to determine:
+- Existing role-permission mappings
+- The GetSeedData() method structure
+- Which roles already have which permissions
+- The GUID generation method used (deterministic or hardcoded)
+
+---
+
+## F2. Read Role GUIDs
+
+**System-level roles** (well-known GUIDs):
+
+| Role | GUID |
+|------|------|
+| SuperAdmin | `11111111-1111-1111-1111-111111111111` |
+| PlatformAdmin | `22222222-2222-2222-2222-222222222222` |
+| TenantAdmin | `33333333-3333-3333-3333-333333333333` |
+| StandardUser | `44444444-4444-4444-4444-444444444444` |
+
+**IMPORTANT:** Read the actual `RoleSeedData.cs` or `RoleConfiguration.cs` in the target project to confirm the actual role GUIDs. The above are defaults; the project may use different values.
+
+**Application-scoped roles** (deterministic GUIDs based on application):
+
+```csharp
+// Read the existing GenerateDeterministicGuid method in RolePermissionConfiguration.cs
+// Typically uses MD5 hash:
+private static Guid GenerateDeterministicGuid(Guid applicationId, string roleType)
+{
+    using var md5 = System.Security.Cryptography.MD5.Create();
+    var input = $"{applicationId}-{roleType}";
+    var hash = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(input));
+    return new Guid(hash);
+}
+// roleType values: "admin", "manager", "contributor", "viewer"
+```
+
+Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
+
+---
+
+## F3. Determine Application-Based Default Mappings
+
+Based on `{full_path}` application prefix:
+
+| Application Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
+|----------------|------------|---------------|-----------|-------------|-----------------|------------|
+| `administration.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `*` (business apps) | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `myspace.*` | wildcard | None | Full CRUD | CRU | CR | R |
+
+---
+
+## F4. Generate RolePermission HasData Entries
+
+Using `{permission_guids}` from step-02:
+
+```csharp
+// In RolePermissionConfiguration.cs - GetSeedData() method
+var seedDate = SeedConstants.SeedDate;
+
+// ============================================================
+// {MODULE_NAME} PERMISSIONS
+// ============================================================
+
+// SuperAdmin: already has *.* wildcard - no individual entries needed
+
+// PlatformAdmin (for platform.* context)
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.delete}, AssignedAt = seedDate });
+
+// Application-scoped: Admin → wildcard
+rolePermissions.Add(new { RoleId = appAdminRoleId, PermissionId = {permission_guids.wildcard}, AssignedAt = seedDate });
+
+// Application-scoped: Manager → CRU (read + create + update — no delete)
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
+
+// Application-scoped: Contributor → CR
+rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+
+// Application-scoped: Viewer → R
+rolePermissions.Add(new { RoleId = appViewerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+```
+
+---
+
+## F5. Write Code to RolePermissionConfiguration.cs
+
+**CRITICAL:** Do NOT just display code. WRITE it to the actual file.
+
+1. Open `RolePermissionConfiguration.cs`
+2. Find the `GetSeedData()` method
+3. Add the new role-permission entries to the list
+4. Add necessary permission GUID references (import from PermissionConfiguration or use inline)
+5. Add comments grouping the new entries: `// {MODULE_NAME} PERMISSIONS`
+
+---
+
+## F6. Present Summary
+
+```markdown
+## Role-Permission Mappings Generated (Fallback)
+
+| Role | Permissions |
+|------|-------------|
+| SuperAdmin | Already has wildcard access |
+| PlatformAdmin | {full_path}.read, .create, .update, .delete |
+| App Admin | {full_path}.* (wildcard) |
+| App Manager | {full_path}.read, .create, .update |
+| App Contributor | {full_path}.read, .create |
+| App Viewer | {full_path}.read |
+
+Written to: RolePermissionConfiguration.cs
+```
+
+---
+
+## F7. Offer User Adjustment
+
+If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
+
+---
+
+## Validation Checklist
+
+Before marking as completed, verify:
+
+- [ ] All role GUIDs correctly identified (system and application-scoped)
+- [ ] Role-permission mappings follow application hierarchy
+- [ ] Code WRITTEN to files (not just displayed)
+- [ ] Permission GUID references correct
+- [ ] Comments added for module grouping
+- [ ] No gaps or missing permissions

package/templates/skills/application/references/test-coverage-requirements.md

@@ -0,0 +1,213 @@
+# Test Generation: Coverage Requirements & Categories
+
+> Referenced from `steps/step-07-tests.md` — Test coverage minimums and category definitions.
+
+---
+
+## Minimum Test Coverage Per Category
+
+| Category | Minimum Tests | Focus Areas |
+|----------|---------------|------------|
+| Controller (mock) | 10 | CRUD routing, auth/tenant handling, error responses |
+| Controller (real integration) | 8 | CRUD with actual DB persistence, tenant isolation, 404/409 cases |
+| Service | 8 | Business logic, CRUD, error handling, edge cases |
+| Entity | 5 | Factory method, property updates, validation, soft delete |
+| Validator | 8 | Code validation, name validation, security rules |
+| Repository | 8 | CRUD, tenant filtering, pagination, indexes |
+| Security | 10 | Auth bypass attempts, injection attacks, header validation |
+
+**Total minimum:** ~67 tests per entity
+
+---
+
+## Real Integration Test Coverage
+
+Integration tests (with actual DB):
+- GET all → 200 with list
+- GET by ID → 200 when exists, 404 when not
+- POST → 201/200 when valid, persist to DB, read back to verify
+- POST → 400 when invalid data
+- POST → 409 when duplicate code
+- PUT → 200 when valid, persist changes, read back to verify
+- PUT → 404 when not exists
+- DELETE → 204 when exists
+- DELETE → 404 when not exists
+- Tenant isolation → create in tenant A, invisible in tenant B (REAL DB)
+- Authorization → 401 when not authenticated
+
+---
+
+## Test Naming Convention (BLOCKING)
+
+All test methods MUST follow: `{Method}_When{Condition}_Should{Result}`
+
+**FORBIDDEN patterns:**
+- `Test1`, `Test2`, `TestMethod`, `MyTest`
+- `Should_Return_OK`, `test_get_all`
+
+**REQUIRED pattern:**
+```csharp
+GetAll_WhenCalled_ShouldReturn200WithList
+Create_WhenDuplicateCode_ShouldThrowException
+Delete_WhenNotAuthenticated_ShouldReturn401
+```
+
+---
+
+## Test Structure (BLOCKING)
+
+All tests MUST follow Arrange-Act-Assert:
+
+```csharp
+// CORRECT
+[Fact]
+public async Task GetById_WhenExists_ShouldReturn200()
+{
+    // Arrange
+    var id = Guid.NewGuid();
+    // ... setup
+
+    // Act
+    var response = await _client.GetAsync($"/api/{entityCode}/{id}");
+
+    // Assert
+    response.StatusCode.Should().Be(HttpStatusCode.OK);
+}
+
+// FORBIDDEN - No structure
+[Fact]
+public void TestGetById()
+{
+    var response = _client.GetAsync("/api/product/1");
+    Assert.Equal(200, response.StatusCode);
+}
+```
+
+---
+
+## Dependencies Check (BLOCKING)
+
+Verify test project uses:
+- `FluentAssertions` (NOT `Assert.Equal`)
+- `Moq` (NOT manual fakes)
+- `xunit` (NOT NUnit or MSTest)
+
+---
+
+## Test Categories
+
+### 1. Controller Mock Tests
+
+Unit tests with mocked dependencies:
+- Routing validation
+- Authentication/Authorization
+- Error response formatting
+- Input validation
+
+```csharp
+[Fact]
+public async Task GetAll_WhenCalled_ShouldReturn200WithList()
+{
+    // Mock service
+    _mockService.Setup(s => s.GetAllAsync(It.IsAny<CancellationToken>()))
+        .ReturnsAsync(new List<ProductDto>());
+
+    // Act & Assert
+    ...
+}
+```
+
+### 2. Controller Integration Tests
+
+REAL tests with actual DB (via WebApplicationFactory):
+- Full HTTP flow
+- Database persistence
+- Tenant isolation
+- Query validation
+
+### 3. Service Tests
+
+Unit tests for business logic:
+- CRUD operations
+- Error handling
+- Validation logic
+
+### 4. Entity Tests
+
+Domain model tests:
+- Factory methods
+- Property validation
+- State transitions
+- Soft delete
+
+### 5. Validator Tests
+
+Input validation:
+- Code format validation
+- Name constraints
+- Security rules (XSS, SQL injection detection)
+
+### 6. Repository Tests
+
+Data access tests:
+- Query correctness
+- Tenant filtering
+- Pagination
+- Indexes
+
+### 7. Security Tests
+
+OWASP coverage:
+- Authentication bypass attempts
+- Authorization bypass attempts
+- SQL injection attempts
+- XSS payload handling
+- CSRF token validation
+- Tenant isolation breach attempts
+- Header injection attempts
+
+---
+
+## Build & Run Checks (BLOCKING)
+
+```bash
+# Build
+dotnet build tests/{SolutionName}.Tests/{SolutionName}.Tests.csproj
+
+# Run
+dotnet test tests/{SolutionName}.Tests/{SolutionName}.Tests.csproj --no-build --verbosity normal
+```
+
+**ALL tests MUST pass.** If tests fail:
+1. Read the failure output carefully
+2. Fix the failing tests or the code they test
+3. Re-run until all tests pass
+4. Do NOT proceed to the next step until all tests are green
+
+---
+
+## Frontend Test Categories
+
+| File | Category | Focus |
+|------|----------|-------|
+| `{EntityName}Page.test.tsx` | Page | Loading, error, render with data |
+| `{EntityName}ListView.test.tsx` | List | Pagination, filtering, view toggle |
+| `{EntityName}DetailPage.test.tsx` | Detail | Tab switching, back navigation |
+| `use{EntityName}Preferences.test.ts` | Hooks | State persistence, local storage |
+| `{entityName}Api.test.ts` | API Client | MSW mocking, HTTP methods |
+
+---
+
+## Validation Checklist
+
+- [ ] All test methods follow `{Method}_When{Condition}_Should{Result}` naming
+- [ ] All tests use Arrange-Act-Assert structure
+- [ ] FluentAssertions used throughout (not Assert.Equal)
+- [ ] Moq used for mock-based tests only
+- [ ] Minimum test count met per category
+- [ ] Real integration tests verify DB persistence
+- [ ] Security tests cover OWASP top 10 issues
+- [ ] Backend tests build successfully
+- [ ] **ALL backend tests pass**
+- [ ] Frontend tests build successfully
+- [ ] **ALL frontend tests pass**

package/templates/skills/application/references/test-frontend.md

@@ -53,9 +53,9 @@ Args:
 ```
 
 This generates:
-- `src/pages/{context}/{application}/__tests__/{EntityName}Page.test.tsx` - Page rendering, loading, error states
-- `src/pages/{context}/{application}/__tests__/{EntityName}ListView.test.tsx` - List display, pagination, view toggle
-- `src/pages/{context}/{application}/__tests__/{EntityName}DetailPage.test.tsx` - Detail view, tabs, back navigation
+- `src/pages/{application}/__tests__/{EntityName}Page.test.tsx` - Page rendering, loading, error states
+- `src/pages/{application}/__tests__/{EntityName}ListView.test.tsx` - List display, pagination, view toggle
+- `src/pages/{application}/__tests__/{EntityName}DetailPage.test.tsx` - Detail view, tabs, back navigation
 - `src/hooks/__tests__/use{EntityName}Preferences.test.ts` - Preference get/set
 - `src/services/api/__tests__/{entityName}Api.test.ts` - API client calls with MSW