@atlashub/smartstack-cli 3.8.0 → 3.9.0

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/backend-controller-hierarchy.md

@@ -0,0 +1,58 @@
+# Controller NavRoute and Folder Hierarchy
+
+> Referenced from `steps/step-04-backend.md` — Controller file organization and NavRoute conventions.
+
+---
+
+## Controller File Location
+
+Controllers are organized by **context short name** and **application** (matching SmartStack.app pattern):
+
+```
+Api/Controllers/
+├── Admin/                     ← platform.administration
+│   ├── {Application}/         ← Application sub-folder (e.g., AI/, Communications/, Tenants/)
+│   │   └── {EntityName}Controller.cs
+│   └── {EntityName}Controller.cs  ← Direct controllers (no application sub-folder)
+├── Business/                  ← business.*
+│   └── {EntityName}Controller.cs
+├── Support/                   ← platform.support
+│   └── {EntityName}Controller.cs
+├── User/                      ← personal.*
+│   └── {EntityName}Controller.cs
+└── {SharedControllers}.cs     ← Root-level (Auth, Config, Navigation, etc.)
+```
+
+## Context-to-Folder Mapping
+
+| NavRoute Context | Controller Folder | Example |
+|-----------------|-------------------|---------|
+| `platform.administration` | `Admin` | `Controllers/Admin/TenantsController.cs` |
+| `platform.administration.{app}` | `Admin/{App}` | `Controllers/Admin/AI/AiPromptsController.cs` |
+| `platform.support` | `Support` | `Controllers/Support/TicketsController.cs` |
+| `business.*` | `Business` | `Controllers/Business/MyTicketsController.cs` |
+| `personal.*` | `User` | `Controllers/User/PreferencesController.cs` |
+
+## Controller Attributes
+
+The generated controller uses NavRoute attribute:
+
+```csharp
+[NavRoute("{full_path}")]
+[ApiController]
+[Authorize]
+public class {EntityName}Controller : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.{Context}.{Application}.{Module}.Read)]
+    public async Task<ActionResult<IEnumerable<{EntityName}Dto>>> GetAll() { ... }
+
+    // ... other CRUD methods
+}
+```
+
+This ensures:
+- API route is derived from navigation path
+- Permissions use the constants from Permissions.cs
+- Frontend can discover API path from NavRoute registry
+- Controller file is in the correct context/application folder

package/templates/skills/application/references/backend-entity-seeding.md

@@ -0,0 +1,72 @@
+# Entity Seeding Pattern
+
+> Reference: See `templates-seed.md` section "TEMPLATE: ENTITY SEED DATA (SeedData Provider)"
+
+## SeedData File
+
+**`Infrastructure/Persistence/Seeding/Data/{Domain}/{EntityName}SeedData.cs`**
+
+Follow SmartStack.app pattern:
+- Static class with `internal static IEnumerable<{EntityName}SeedItem> GetAll{EntityName}s()`
+- Use deterministic GUIDs (NEVER `Guid.NewGuid()`)
+- Include 3-5 sample entities with varied, realistic data
+- For multi-tenant: organize by tenant using `GetTenant1{EntityName}s()` helpers
+
+```csharp
+public static class {EntityName}SeedData
+{
+    public static readonly Guid Sample1Id = Guid.Parse("...");
+    public static readonly Guid Sample2Id = Guid.Parse("...");
+    public static readonly Guid Sample3Id = Guid.Parse("...");
+
+    internal static IEnumerable<{EntityName}SeedItem> GetAll{EntityName}s()
+    {
+        return new[]
+        {
+            new {EntityName}SeedItem { Id = Sample1Id, /* ... */ },
+            new {EntityName}SeedItem { Id = Sample2Id, /* ... */ },
+            new {EntityName}SeedItem { Id = Sample3Id, /* ... */ }
+        };
+    }
+}
+
+internal class {EntityName}SeedItem
+{
+    public Guid Id { get; init; }
+    // ... all required entity properties
+}
+```
+
+## DevDataSeeder Update
+
+Add to `Infrastructure/Persistence/Seeding/DevDataSeeder.cs`:
+- `using` for the new SeedData namespace
+- `await Seed{EntityName}sAsync(cancellationToken);` in `SeedAsync()` method
+
+```csharp
+private async Task Seed{EntityName}sAsync(CancellationToken cancellationToken)
+{
+    _logger.LogInformation("Seeding demo {EntityName}s...");
+
+    var existingCount = await _context.{EntityName}s.CountAsync(cancellationToken);
+    if (existingCount > 0)
+    {
+        _logger.LogWarning("{EntityName}s already seeded ({Count} exist), skipping.", existingCount);
+        return;
+    }
+
+    var createdCount = 0;
+    foreach (var seedItem in {EntityName}SeedData.GetAll{EntityName}s())
+    {
+        var entity = {EntityName}.Create(/* map seedItem properties */);
+        typeof({EntityName}).GetProperty("Id")?.SetValue(entity, seedItem.Id);
+        _context.{EntityName}s.Add(entity);
+        createdCount++;
+    }
+
+    if (createdCount > 0)
+        await _context.SaveChangesAsync(cancellationToken);
+
+    _logger.LogInformation("Created {Count} demo {EntityName}s.", createdCount);
+}
+```

package/templates/skills/application/references/backend-verification.md

@@ -0,0 +1,88 @@
+# Backend Post-Generation Verification
+
+**Run ALL checks before proceeding to next step.**
+
+## Check 1: Backend Build (BLOCKING)
+
+```bash
+dotnet build {SolutionName}.sln --no-restore
+```
+
+IF build fails: Read errors, fix compilation issues, re-run until success.
+
+## Check 2: DbSet Registration (BLOCKING)
+
+Search for `DbSet<{EntityName}>` in `I{DbContextName}.cs` or `{DbContextName}.cs`.
+
+IF NOT found, add:
+```csharp
+public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();
+```
+
+## Check 3: DI Registration (BLOCKING)
+
+Search for `I{EntityName}Service` in `DependencyInjection.cs`.
+
+IF NOT found, add:
+```csharp
+services.AddScoped<I{EntityName}Service, {EntityName}Service>();
+```
+
+## Check 4: RequirePermission Attributes (BLOCKING)
+
+Each HTTP action MUST have `[RequirePermission(Permissions.{Context}.{Application}.{Module}.{Action})]`.
+
+## Check 5: Entity Configuration (BLOCKING)
+
+Verify:
+- `builder.ToTable("{table_prefix}{EntityName}s")` uses correct prefix
+- `builder.HasKey(e => e.Id)` present
+- `builder.HasIndex` for unique fields
+
+## Check 5b: Seeding Infrastructure (first entity only)
+
+**If this is the FIRST entity (no existing DevDataSeeder):**
+
+1. **`Infrastructure/Persistence/Seeding/Data/SeedConstants.cs`**
+```csharp
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+public static class SeedConstants
+{
+    public static readonly DateTime SeedDate = new(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+}
+```
+
+2. **`Infrastructure/Persistence/Seeding/DevDataSeeder.cs`**
+```csharp
+public class DevDataSeeder : IDevDataSeeder
+{
+    private readonly ExtensionsDbContext _context;
+    private readonly ILogger<DevDataSeeder> _logger;
+    public DevDataSeeder(ExtensionsDbContext context, ILogger<DevDataSeeder> logger) { _context = context; _logger = logger; }
+    public async Task SeedAsync(CancellationToken cancellationToken = default)
+    {
+        _logger.LogInformation("Starting development data seeding...");
+        // Add Seed{Entity}sAsync calls here
+        _logger.LogInformation("Development data seeding complete.");
+    }
+}
+```
+
+3. Register: `services.AddScoped<IDevDataSeeder, DevDataSeeder>();`
+
+## Check 5c: SqlObjects Directory (first entity only)
+
+**If no existing SqlObjectHelper:**
+
+1. **`Infrastructure/Persistence/SqlObjects/SqlObjectHelper.cs`** - Helper for embedded SQL resources
+2. Create `Infrastructure/Persistence/SqlObjects/Functions/` directory
+3. Ensure `.csproj` has: `<EmbeddedResource Include="Persistence\SqlObjects\**\*.sql" />`
+
+## Check 6: Convention Validation (RECOMMENDED)
+
+```
+Tool: mcp__smartstack__validate_conventions
+Args: target: "backend", scope: "{entity_name}"
+```
+
+Verifies naming conventions, architecture layers, required attributes, DTO patterns.

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

@@ -0,0 +1,111 @@
+# Frontend: Routing Rules & Post-Generation Verification
+
+> Reference for step-05-frontend.md — routing rules and mandatory verification checks.
+
+## Routing Rules
+
+### Rule 1: Routes MUST be inside Layout wrappers
+
+**CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
+
+```tsx
+// CORRECT - Inside BusinessLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/business" element={<BusinessLayout />}>
+  <Route path="sales/products" element={<ProductsPage />} />
+</Route>
+
+// FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
+<Route path="/business/sales/products" element={<ProductsPage />} />
+```
+
+### Rule 2: Use nested routes (not flat)
+
+**CRITICAL:** SmartStack requires NESTED routes within the layout:
+
+```tsx
+// CORRECT - Nested routes inside layout
+<Route path="/business" element={<BusinessLayout />}>
+  <Route path="sales">
+    <Route index element={<Navigate to="products" replace />} />
+    <Route path="products" element={<ProductsPage />} />
+    <Route path="orders" element={<OrdersPage />} />
+  </Route>
+</Route>
+
+// FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
+<Route path="/business/sales" element={<Navigate to="products" />} />
+<Route path="/business/sales/products" element={<ProductsPage />} />
+```
+
+## Post-Generation Verification (MANDATORY)
+
+**Before proceeding to step-06, run these checks on ALL generated frontend files:**
+
+### 1. CSS Variables Check (BLOCKING)
+
+Scan all generated `.tsx` files for hardcoded Tailwind colors:
+
+```
+FORBIDDEN patterns: bg-blue-, bg-red-, bg-green-, bg-gray-, bg-amber-,
+                    text-blue-, text-red-, text-green-, text-gray-, text-amber-,
+                    border-blue-, border-red-, border-green-, border-gray-
+```
+
+If ANY hardcoded color is found → **FIX IT** using CSS variables from style-guide.md before continuing.
+
+### 2. API Client Check (BLOCKING)
+
+Verify all API service files use the configured client:
+- **CORRECT:** `import { api } from '@/services/api/apiClient'` or `import api from '../api'`
+- **FORBIDDEN:** `import axios from 'axios'`
+
+### 3. EntityCard Check
+
+If a grid/card view is generated, verify it uses `EntityCard` component (not custom divs).
+
+### 4. i18n Check (BLOCKING)
+
+Verify exactly **4 language files** exist with identical key structures:
+- `fr/{entityCode}.json`
+- `en/{entityCode}.json`
+- `it/{entityCode}.json`
+- `de/{entityCode}.json`
+
+### 5. Route Check (BLOCKING)
+
+Verify routes are:
+- **INSIDE** the Layout wrapper (`BusinessLayout`, `AdminLayout`, or `UserLayout`)
+- **NESTED** (not flat)
+- Following path convention: `/{context}/{application}/{module}`
+
+### 6. States Check
+
+Verify the list page includes:
+- Loading state (spinner)
+- Error state (icon + message + retry button)
+- Empty state (icon + message)
+
+### 7. TypeScript Build Check (BLOCKING)
+
+Run the frontend type check to verify all generated files compile:
+
+```bash
+cd web && npx tsc --noEmit 2>&1 | head -50
+```
+
+OR if the project uses a build script:
+
+```bash
+cd web && npm run build 2>&1 | head -80
+```
+
+IF type errors exist **in generated files**: Fix them before proceeding.
+Common issues: missing imports, wrong interface names, incorrect prop types, missing hook return types.
+
+IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.
+
+**Focus only on errors in files generated by this step:**
+- `pages/{context}/{application}/{module}/*.tsx`
+- `services/api/{entityCode}Api.ts`
+- `types/{entityName}.types.ts`
+- `hooks/use{EntityName}*.ts`