@atlashub/smartstack-cli 3.8.0 → 3.10.0

package/templates/skills/apex/steps/step-05-examine.md

@@ -0,0 +1,124 @@
+---
+name: step-05-examine
+description: Adversarial code review of changes — find issues before they reach production
+model: opus
+prev_step: steps/step-04-validate.md
+next_step: steps/step-06-resolve.md
+---
+
+# Step 5: Examine (if -x)
+
+**Goal:** Review the code as an adversarial external reviewer. Find bugs, security issues, and convention violations that automated checks missed.
+
+---
+
+## 1. Gather Changed Files
+
+```bash
+git diff --name-only HEAD~{commit_count}
+```
+
+List all files modified during this APEX session.
+
+---
+
+## 2. MCP Code Review
+
+```
+Call: mcp__smartstack__review_code
+  scope: "changed"      # Only review files changed in this session
+
+Call: mcp__smartstack__analyze_code_quality
+  scope: "changed"
+```
+
+---
+
+## 3. Manual Adversarial Review
+
+For each changed file, check:
+
+**Security (OWASP):**
+- [ ] `[RequirePermission]` on every endpoint (not `[Authorize]`)
+- [ ] No SQL injection (parameterized queries, EF Core only)
+- [ ] No XSS (React auto-escapes, but check dangerouslySetInnerHTML)
+- [ ] Multi-tenant isolation (IHasData filter applied)
+- [ ] No secrets in code
+
+**Architecture:**
+- [ ] Entities in correct Domain folder
+- [ ] Configs in correct Infrastructure folder
+- [ ] Services follow CQRS pattern
+- [ ] DTOs separate from domain entities
+- [ ] Controllers return DTOs, not entities
+- [ ] Frontend in correct hierarchy (Context/App/Module)
+
+**SmartStack conventions:**
+- [ ] Deterministic GUIDs in seed data (not Guid.NewGuid())
+- [ ] 4 languages in translations
+- [ ] CSS variables (not hardcoded colors)
+- [ ] SmartTable/SmartForm (not raw HTML tables/forms)
+- [ ] Correct Layout wrapper per context
+
+---
+
+## 4. Produce Findings
+
+For each issue found, classify:
+
+```
+[BLOCKING] — Must fix before completion
+[SUGGESTION] — Should fix, quality improvement
+[NIT] — Minor style/preference issue
+```
+
+**Findings format:**
+
+```markdown
+### Finding F01 [BLOCKING]
+**File:** {path}:{line}
+**Issue:** {description}
+**Fix:** {recommended fix}
+
+### Finding F02 [SUGGESTION]
+**File:** {path}:{line}
+**Issue:** {description}
+**Fix:** {recommended fix}
+```
+
+---
+
+## 5. Summary
+
+```
+**APEX SmartStack - Examine Complete**
+
+**Files reviewed:** {count}
+**Findings:** {blocking} BLOCKING, {suggestions} SUGGESTION, {nits} NIT
+
+{findings table}
+```
+
+---
+
+## 6. Save Output (if save_mode)
+
+Write to `{output_dir}/05-examine.md` with all findings.
+
+---
+
+## 7. Route to Next Step
+
+```
+IF BLOCKING findings exist:
+  → Load steps/step-06-resolve.md
+
+ELSE IF test_mode = true:
+  → Load steps/step-07-tests.md
+
+ELSE IF pr_mode = true:
+  → Create PR and show final summary
+
+ELSE:
+  → Show final summary and exit
+```

package/templates/skills/apex/steps/step-06-resolve.md

@@ -0,0 +1,105 @@
+---
+name: step-06-resolve
+description: Fix BLOCKING findings from adversarial review
+model: opus
+prev_step: steps/step-05-examine.md
+next_step: steps/step-07-tests.md
+---
+
+# Step 6: Resolve (if BLOCKING findings)
+
+**Goal:** Fix all BLOCKING findings from step-05. Re-validate after fixes.
+
+---
+
+## 1. Process BLOCKING Findings
+
+For each BLOCKING finding from step-05:
+
+```
+Finding: {F01, F02, ...}
+File: {path}
+Issue: {description}
+Fix approach: {use appropriate skill/MCP tool}
+```
+
+**Fixing rules:**
+- Use the SAME skill/MCP that created the original code
+- If the finding is in a controller → use /controller or MCP scaffold_extension
+- If the finding is in seed data → use MCP generate_permissions
+- If the finding is in frontend → use /ui-components or MCP scaffold_routes
+- NEVER fix by writing raw SmartStack code
+
+---
+
+## 2. Apply Fixes
+
+For each finding:
+
+```
+1. Read the file to understand current state
+2. Apply fix via appropriate skill/MCP
+3. Verify fix addresses the finding
+4. Mark finding as RESOLVED
+```
+
+---
+
+## 3. Re-Validate
+
+After all BLOCKING findings are fixed:
+
+```
+1. MCP validate_conventions → 0 errors
+2. dotnet build --no-restore → PASS
+3. npm run typecheck → PASS (if frontend)
+```
+
+---
+
+## 4. Commit Fixes
+
+```
+fix({module}): resolve review findings {F01, F02, ...}
+```
+
+---
+
+## 5. Resolution Summary
+
+```
+**APEX SmartStack - Resolve Complete**
+
+**BLOCKING findings:** {count}
+**Resolved:** {count}
+**Remaining:** {count} (should be 0)
+
+| Finding | Status | Fix Applied |
+|---------|--------|-------------|
+| F01 | RESOLVED | {description} |
+| F02 | RESOLVED | {description} |
+```
+
+---
+
+## 6. Save Output (if save_mode)
+
+Write to `{output_dir}/06-resolve.md` with resolution log.
+
+---
+
+## 7. Route to Next Step
+
+```
+IF remaining BLOCKING > 0:
+  → Loop: fix remaining, re-validate
+
+IF test_mode = true:
+  → Load steps/step-07-tests.md
+
+ELSE IF pr_mode = true:
+  → Create PR and show final summary
+
+ELSE:
+  → Show final summary and exit
+```

package/templates/skills/apex/steps/step-07-tests.md

@@ -0,0 +1,130 @@
+---
+name: step-07-tests
+description: Scaffold tests via MCP for all modified layers
+model: opus
+prev_step: steps/step-06-resolve.md
+next_step: steps/step-08-run-tests.md
+---
+
+# Step 7: Tests (if -t)
+
+**Goal:** Scaffold comprehensive tests using MCP tools. Target: >= 80% coverage.
+
+---
+
+## 1. Ensure Test Project Exists
+
+```bash
+# Check for existing test project
+TEST_PROJECT=$(find tests/ -name "*.Tests.Unit.csproj" 2>/dev/null | head -1)
+
+if [ -z "$TEST_PROJECT" ]; then
+  # Create test project
+  PROJECT_NAME=$(basename *.sln .sln)
+  dotnet new xunit -n "${PROJECT_NAME}.Tests.Unit" -o "tests/${PROJECT_NAME}.Tests.Unit"
+  dotnet add "tests/${PROJECT_NAME}.Tests.Unit" package Moq
+  dotnet add "tests/${PROJECT_NAME}.Tests.Unit" package FluentAssertions
+  for proj in src/*/*.csproj; do
+    dotnet add "tests/${PROJECT_NAME}.Tests.Unit" reference "$proj"
+  done
+  dotnet sln add "tests/${PROJECT_NAME}.Tests.Unit/${PROJECT_NAME}.Tests.Unit.csproj"
+fi
+```
+
+---
+
+## 2. Scaffold Tests via MCP
+
+For each layer that was modified:
+
+### Domain Tests
+```
+Call: mcp__smartstack__scaffold_tests
+  target_layer: "domain"
+  module: "{module_code}"
+  test_type: "unit"
+
+Tests: entity creation, validation, domain events, value objects
+```
+
+### Application Tests
+```
+Call: mcp__smartstack__scaffold_tests
+  target_layer: "application"
+  module: "{module_code}"
+  test_type: "unit"
+
+Tests: service logic, CQRS handlers, FluentValidation
+```
+
+### API Tests
+```
+Call: mcp__smartstack__scaffold_tests
+  target_layer: "api"
+  module: "{module_code}"
+  test_type: "integration"
+
+Tests: controller endpoints, authorization, response DTOs
+```
+
+### Security Tests
+```
+Call: mcp__smartstack__scaffold_tests
+  module: "{module_code}"
+  test_type: "security"
+
+Tests: RequirePermission enforcement, multi-tenant isolation
+```
+
+---
+
+## 3. Suggest Additional Scenarios
+
+```
+Call: mcp__smartstack__suggest_test_scenarios
+  module: "{module_code}"
+
+Review suggestions and add relevant test cases.
+```
+
+---
+
+## 4. Analyze Coverage
+
+```
+Call: mcp__smartstack__analyze_test_coverage
+  module: "{module_code}"
+
+Target: >= 80% coverage
+If under 80%: identify uncovered paths, scaffold additional tests
+```
+
+---
+
+## 5. Test Summary
+
+```
+**APEX SmartStack - Tests Scaffolded**
+
+| Layer | Tests Created | Coverage |
+|-------|--------------|----------|
+| Domain | {count} | {%} |
+| Application | {count} | {%} |
+| API | {count} | {%} |
+| Security | {count} | {%} |
+
+**Total tests:** {count}
+**Estimated coverage:** {%}
+```
+
+---
+
+## 6. Save Output (if save_mode)
+
+Write to `{output_dir}/07-tests.md` with test scaffolding results.
+
+---
+
+## NEXT STEP
+
+Load `steps/step-08-run-tests.md`

package/templates/skills/apex/steps/step-08-run-tests.md

@@ -0,0 +1,115 @@
+---
+name: step-08-run-tests
+description: Run tests until 100% pass — fix CODE not tests
+model: opus
+prev_step: steps/step-07-tests.md
+next_step: COMPLETE
+---
+
+# Step 8: Run Tests (if -t)
+
+**CRITICAL:** Fix the CODE, not the tests. Tests represent expected behavior.
+100% pass required for Sonar quality gate.
+
+---
+
+## 1. Build
+
+```bash
+dotnet build --no-restore
+```
+
+**MUST PASS before running tests.**
+
+---
+
+## 2. Run Full Test Suite
+
+```bash
+dotnet test --no-build --verbosity normal
+```
+
+---
+
+## 3. Analyze Results
+
+**If ALL PASS:** Skip to step 5 (Summary).
+
+**If FAILURES:** For each failing test:
+
+```markdown
+### Failing Test: {test_name}
+**File:** {test_file}:{line}
+**Error:** {error_message}
+
+**Root Cause Analysis:**
+- [ ] Code bug: implementation doesn't match expected behavior
+- [ ] Missing dependency: service/mock not configured
+- [ ] Data issue: test data setup incomplete
+```
+
+---
+
+## 4. Fix Loop (max 5 iterations)
+
+```
+WHILE tests failing AND iteration < 5:
+  1. Identify root cause (ALWAYS code bug, not test bug)
+  2. Fix the production CODE via appropriate skill/MCP
+  3. dotnet build --no-restore
+  4. dotnet test --no-build
+  5. Log result
+```
+
+**Rules:**
+- Fix CODE, never modify test assertions
+- Use the same skill/MCP that created the original code
+- After fix, rebuild before retesting
+- If stuck after 3 iterations on same test, ask user
+
+**If stuck (auto_mode = false):**
+
+```yaml
+questions:
+  - header: "Test Fix"
+    question: "Test is still failing after multiple attempts. How should we proceed?"
+    options:
+      - label: "Try alternative fix (Recommended)"
+        description: "Attempt a different approach to fix the code"
+      - label: "Skip this test"
+        description: "Mark as skipped with TODO comment"
+      - label: "Discuss the issue"
+        description: "Need help understanding the failure"
+    multiSelect: false
+```
+
+---
+
+## 5. Frontend Typecheck (if applicable)
+
+```bash
+npm run typecheck
+```
+
+**MUST PASS.**
+
+---
+
+## 6. Commit Tests
+
+```
+test({module}): add unit and integration tests
+```
+
+---
+
+## 7. Save + Summary
+
+If save_mode: write to `{output_dir}/08-run-tests.md`.
+
+Display: total tests, passing count, iterations to green, fixes applied, coverage %.
+
+## 8. Route to Next Step
+
+If pr_mode: create PR via `gh pr create`, show URL.
+Otherwise: show final summary (task, context, files, quality checks, commits, next steps).

package/templates/skills/application/SKILL.md

@@ -230,3 +230,13 @@ await _workflowService.TriggerAsync("{entity}.created", new Dictionary<string, o
 - [templates-frontend.md](templates-frontend.md) - Frontend patterns reference
 - [templates-i18n.md](templates-i18n.md) - i18n structure reference
 - [templates-seed.md](templates-seed.md) - Seed data patterns reference
+
+<success_criteria>
+- Navigation entries created with correct hierarchy (Context/Application/Module)
+- Permissions generated via MCP with 2-file pattern (constants + seed)
+- Roles assigned with appropriate permission sets
+- Backend layers follow SmartStack conventions (validated by MCP)
+- Frontend pages in correct path structure with i18n
+- EF Core migration created and applied successfully
+- Test suite generated and passing
+</success_criteria>

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

@@ -0,0 +1,227 @@
+# Application Roles Seed Data Template
+
+> Referenced from `core-seed-data.md` and `step-03-roles.md` — C# template for application-scoped roles in client projects.
+
+---
+
+## Problem Statement
+
+When using `IClientSeedDataProvider` (client projects with `seeding_strategy = "provider"`), role-permission mappings reference roles by their `Code`:
+
+```csharp
+var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);  // "admin", "manager", "contributor", "viewer"
+```
+
+**However**, the current templates do NOT create these application-scoped roles. They assume:
+- System roles (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser) exist in Core
+- Application-scoped roles (Admin, Manager, Contributor, Viewer) already exist with valid `Code` values
+
+**Result:** Role-permission mappings fail silently when `role == null`.
+
+---
+
+## Solution: Application Roles Seed Data
+
+Create application-scoped roles with deterministic GUIDs and valid `Code` values.
+
+---
+
+## File Location
+
+**Path:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+This file should be created **ONCE per application** (not per module).
+
+---
+
+## Template
+
+```csharp
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+
+/// <summary>
+/// Application-scoped role seed data for {AppLabel}.
+/// Defines the 4 standard application roles: Admin, Manager, Contributor, Viewer.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class ApplicationRolesSeedData
+{
+    // Deterministic GUIDs for application roles
+    // Generated from: "role-{applicationId}-{roleType}"
+    private static readonly Guid ApplicationId = {ApplicationGuid}; // From NavigationApplicationSeedData
+
+    public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
+    public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
+    public static readonly Guid ContributorRoleId = GenerateRoleGuid("contributor");
+    public static readonly Guid ViewerRoleId = GenerateRoleGuid("viewer");
+
+    /// <summary>
+    /// Returns application-scoped role entries for seeding into core.auth_Roles.
+    /// </summary>
+    public static IEnumerable<ApplicationRoleSeedEntry> GetRoleEntries()
+    {
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = AdminRoleId,
+            Code = "admin",
+            Name = "{AppLabel} Admin",
+            Description = "Full administrative access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 1
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ManagerRoleId,
+            Code = "manager",
+            Name = "{AppLabel} Manager",
+            Description = "Management access to {AppLabel} (Create, Read, Update)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 2
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ContributorRoleId,
+            Code = "contributor",
+            Name = "{AppLabel} Contributor",
+            Description = "Contributor access to {AppLabel} (Create, Read)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 3
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ViewerRoleId,
+            Code = "viewer",
+            Name = "{AppLabel} Viewer",
+            Description = "Read-only access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 4
+        };
+    }
+
+    private static Guid GenerateRoleGuid(string roleType)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"role-{ApplicationId}-{roleType}"));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+/// <summary>Seed entry DTO for application role.</summary>
+public class ApplicationRoleSeedEntry
+{
+    public Guid Id { get; init; }
+    public string Code { get; init; } = null!;
+    public string Name { get; init; } = null!;
+    public string Description { get; init; } = null!;
+    public Guid ApplicationId { get; init; }
+    public bool IsSystem { get; init; }
+    public bool IsActive { get; init; }
+    public int DisplayOrder { get; init; }
+}
+```
+
+---
+
+## Placeholder Replacement
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `{BaseNamespace}` | Root namespace of the client project | `SmartStack.Modules.RessourcesHumaines` |
+| `{AppLabel}` | Human-readable application label (EN) | `Human Resources` |
+| `{ApplicationGuid}` | GUID of the application (from NavigationApplicationSeedData) | `30f1fbba-e8c3-4879-9a49-d18deaa70a83` |
+
+---
+
+## Integration into IClientSeedDataProvider
+
+Add a new method `SeedRolesAsync()` to the provider:
+
+```csharp
+public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+{
+    // Check idempotence
+    var exists = await context.Roles
+        .AnyAsync(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId, ct);
+    if (exists) return;
+
+    // Create application-scoped roles using factory method
+    foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
+    {
+        var role = Role.Create(
+            entry.Code,
+            entry.Name,
+            entry.Description,
+            entry.ApplicationId,
+            entry.IsSystem);
+
+        context.Roles.Add(role);
+    }
+
+    await ((DbContext)context).SaveChangesAsync(ct);
+}
+```
+
+---
+
+## Execution Order in Provider
+
+**CRITICAL:** Roles must be created BEFORE role-permission mappings.
+
+```
+1. SeedNavigationAsync()   → Creates application + modules + translations
+2. SeedRolesAsync()         → Creates application-scoped roles (NEW)
+3. SeedPermissionsAsync()   → Creates permissions
+4. SeedRolePermissionsAsync() → Maps roles to permissions (now succeeds because roles exist)
+```
+
+---
+
+## Verification Checklist
+
+Before marking the task as completed, verify:
+
+- [ ] `ApplicationRolesSeedData.cs` created in `Infrastructure/Persistence/Seeding/Data/`
+- [ ] Deterministic GUIDs used (NEVER `Guid.NewGuid()`)
+- [ ] 4 roles defined: Admin, Manager, Contributor, Viewer
+- [ ] Each role has a valid `Code` value ("admin", "manager", "contributor", "viewer")
+- [ ] Each role has `ApplicationId` set to the application GUID
+- [ ] `SeedRolesAsync()` method added to `IClientSeedDataProvider`
+- [ ] `SeedRolesAsync()` is idempotent (checks existence before inserting)
+- [ ] `Role.Create()` factory method used (NEVER `new Role()`)
+- [ ] `SaveChangesAsync()` called after role creation
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
+- [ ] `dotnet build` passes after generation
+
+---
+
+## Notes
+
+- **Application ID source:** Read from the navigation application created in `SeedNavigationAsync()` or from `{AppPascal}NavigationSeedData.cs`
+- **Role factory method:** Use `Role.Create(code, name, description, applicationId, isSystem)` from SmartStack.Domain
+- **Code uniqueness:** Role codes must be unique within the application scope
+- **System roles:** These are NOT system roles (IsSystem = false) - they are application-scoped roles
+- **Tenant isolation:** Application-scoped roles are automatically tenant-isolated via the Core authorization system
+
+---
+
+## Migration Impact
+
+**For existing projects without application roles:**
+1. Generate `ApplicationRolesSeedData.cs` using this template
+2. Add `SeedRolesAsync()` method to the existing `IClientSeedDataProvider`
+3. Update the provider's execution to call `SeedRolesAsync()` BEFORE `SeedRolePermissionsAsync()`
+4. Run the application - roles will be created on next startup
+5. Role-permission mappings will now succeed