@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/skills/validate-feature/references/api-smoke-tests.md

@@ -0,0 +1,140 @@
+# API Smoke Test Procedure
+
+> **Reference for:** step-04-api-smoke.md
+> **Purpose:** Validate CRUD endpoints with real HTTP requests
+> **Scope:** GET all, POST create, GET by ID, PUT update, DELETE, GET verify deleted
+
+---
+
+## Startup Sequence
+
+```bash
+# Start API on test port
+dotnet run --project {ApiProject} --urls "http://localhost:5099" > /tmp/api-smoke-output.log 2>&1 &
+API_PID=$!
+
+# Wait for readiness (with crash detection)
+API_CRASHED=false
+for i in $(seq 1 30); do
+  if ! kill -0 $API_PID 2>/dev/null; then
+    echo "API PROCESS CRASHED during startup"
+    cat /tmp/api-smoke-output.log 2>/dev/null
+    API_CRASHED=true
+    break
+  fi
+
+  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5099/health 2>/dev/null)
+  if [ "$HTTP_CODE" != "000" ]; then
+    echo "API is ready (HTTP $HTTP_CODE)"
+    break
+  fi
+  sleep 1
+done
+
+# If API_CRASHED=true → Jump to section "Crash Classification" below
+```
+
+---
+
+## CRUD Test Sequence
+
+```bash
+# Get auth token (optional)
+TOKEN=$(curl -s -X POST http://localhost:5099/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@smartstack.io","password":"Admin123!"}' \
+  | jq -r '.token // .accessToken // empty')
+
+# Headers
+AUTH_HEADER="Authorization: Bearer $TOKEN"
+TENANT_HEADER="X-Tenant-Id: 11111111-1111-1111-1111-111111111111"
+CONTENT_TYPE="Content-Type: application/json"
+```
+
+### Test 1: GET All (expect 200)
+```bash
+curl -s -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}
+```
+
+### Test 2: POST Create (expect 201 or 200)
+```bash
+CREATED=$(curl -s -X POST \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" -H "$CONTENT_TYPE" \
+  -d '{"code":"smoke-test-01","name":"Smoke Test Entity"}' \
+  http://localhost:5099/api/{entity_code})
+ENTITY_ID=$(echo "$CREATED" | jq -r '.id // .Id')
+```
+
+### Test 3: GET By ID (expect 200)
+```bash
+curl -s -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+### Test 4: PUT Update (expect 200)
+```bash
+curl -s -X PUT -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" -H "$CONTENT_TYPE" \
+  -d '{"code":"smoke-test-01","name":"Updated Name"}' \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+### Test 5: DELETE (expect 204)
+```bash
+curl -s -X DELETE -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+### Test 6: GET Deleted (expect 404)
+```bash
+curl -s -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+---
+
+## HTTP Error Classification
+
+| Status | Error | Cause | Fix |
+|--------|-------|-------|-----|
+| 401 | Unauthorized | Auth not configured | Check JWT token generation |
+| 403 | Forbidden | Permissions missing | Verify PermissionConfiguration seeding |
+| 404 | Not Found | Route not registered | Check NavRoute attribute on controller |
+| 500 | Internal Server Error | Unhandled exception | Check API startup logs |
+| Connection refused | API won't start | Startup config error | Review appsettings.json |
+
+---
+
+## Crash Classification
+
+If API process dies during startup, classify error from `/tmp/api-smoke-output.log`:
+
+| Error Pattern | Category | Fix |
+|---------------|----------|-----|
+| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | MISSING_PACKAGE | `dotnet add {ApiProject} package {Name} --version {Major.Minor.Patch}` |
+| `FileNotFoundException: Could not load file or assembly '{Name}'` | MISSING_ASSEMBLY | Check .csproj references |
+| `TypeLoadException: Could not load type '{Type}'` | VERSION_MISMATCH | Update package to correct version |
+| `MissingMethodException` | VERSION_MISMATCH | Update package |
+| `InvalidOperationException: Unable to resolve service for type '{Type}'` | MISSING_DI | Add DI registration in Program.cs |
+| `SqlException` or connection errors | DATABASE_ERROR | Check appsettings.json connection string |
+
+**For MISSING_PACKAGE:**
+1. Extract assembly name (text between single quotes)
+2. Extract version (Version=X.X.X.X segment)
+3. Map to NuGet: assembly name usually equals package name
+4. Output: `FIX: dotnet add {ApiProject} package {PackageName} --version {Major.Minor.Patch}`
+
+---
+
+## Cleanup
+
+```bash
+kill $API_PID 2>/dev/null
+wait $API_PID 2>/dev/null
+rm -f /tmp/api-smoke-output.log
+```

package/templates/skills/validate-feature/references/db-validation-checks.md

@@ -0,0 +1,180 @@
+# Database Validation Checks (SQL Server)
+
+> **Reference for:** step-05-db-validation.md
+> **Purpose:** Validate migrations, LINQ→SQL translation, multi-tenant isolation, seed data
+> **Scope:** LocalDB availability, pending changes, migration application, integration tests, seed data config
+
+---
+
+## Check 1: LocalDB Availability
+
+```bash
+sqllocaldb info MSSQLLocalDB
+```
+
+**If NOT available:** Skip DB validation, set `DB_VALIDATION = SKIPPED`
+
+---
+
+## Check 2: Pending Model Changes
+
+```bash
+dotnet ef migrations has-pending-model-changes \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+| Exit Code | Meaning | Action |
+|-----------|---------|--------|
+| 0 | No pending | PASS — continue |
+| Non-zero | Changes not in migration | **FAIL — create migration** |
+
+**If FAIL:**
+```bash
+dotnet ef migrations add {SuggestedName} \
+  --project {InfraProject} \
+  --startup-project {ApiProject} \
+  -o Persistence/Migrations
+```
+
+---
+
+## Check 3: Apply Migrations on Temp DB
+
+```bash
+DB_NAME="SmartStack_Validate_$(date +%s)"
+CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
+
+dotnet ef database update \
+  --connection "$CONN_STRING" \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**Common failures:**
+- `Invalid column name` → migration ordering issue
+- `There is already an object named` → duplicate migration
+- `Cannot insert duplicate key` → seed data conflict
+
+---
+
+## Check 4: Integration Tests vs SQL Server
+
+```bash
+TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
+dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+```
+
+**Validates:**
+- LINQ → SQL translation on real SQL Server (not SQLite)
+- Multi-tenant isolation (global query filters)
+- Soft delete (IsDeleted filter)
+- EF Core configuration (indexes, relationships, constraints)
+
+**SQLite → SQL Server differences caught:**
+- `LIKE` case sensitivity
+- Date functions (`date('now')` vs `GETUTCDATE()`)
+- String concatenation (`||` vs `+`)
+- `LIMIT` vs `TOP`
+- `AUTOINCREMENT` vs `IDENTITY`
+
+---
+
+## Check 5: Dev Seeding Configuration
+
+```bash
+# Check appsettings for EnableDevSeeding
+APPSETTINGS=$(ls appsettings.Development.json 2>/dev/null || ls appsettings.json 2>/dev/null)
+PROGRAM_CS=$(find . -name "Program.cs" -path "*/Api/*" 2>/dev/null | head -1)
+
+# Result: SEEDING_ENABLED = true/false
+```
+
+| Config | Meaning | Action |
+|--------|---------|--------|
+| Program.cs override | PASS | Active in Development |
+| appsettings EnableDevSeeding = true | PASS | Active |
+| appsettings FALSE + no override | WARNING | DevDataSeeder won't run |
+
+**Fix:** Add to Program.cs:
+```csharp
+options.EnableDevSeeding = builder.Environment.IsDevelopment();
+```
+
+---
+
+## Check 6: DefaultTenantId FK Validation
+
+```bash
+SEED_CONSTANTS=$(find . -path "*/SeedConstants.cs" 2>/dev/null | head -1)
+TENANT_GUID=$(grep -oP 'DefaultTenantId\s*=\s*Guid\.Parse\("([^"]+)"\)' "$SEED_CONSTANTS" | grep -oP '"[^"]+"' | tr -d '"')
+
+# Verify GUID exists in database
+sqlcmd -S "(localdb)\MSSQLLocalDB" -d "$DB_NAME" -Q "
+  SET NOCOUNT ON;
+  SELECT COUNT(*) FROM core.tenant_Tenants WHERE Id = '$TENANT_GUID'
+"
+```
+
+| Result | Status | Meaning |
+|--------|--------|---------|
+| COUNT > 0 | PASS | DefaultTenantId is valid |
+| COUNT = 0 | FAIL | FK phantom: DevDataSeeder uses invalid TenantId → 500 errors |
+
+**Fix:** Use a TenantId that is seeded by `InitializeSmartStackAsync()`
+
+---
+
+## Check 7: Seed Data Accessibility
+
+```bash
+# Start API with temp DB
+dotnet run --project "$API_PROJECT" \
+  --urls "http://localhost:5097" \
+  -- --ConnectionStrings:DefaultConnection="$CONN_STRING" &
+SEED_PID=$!
+
+# Verify seed data via API
+TOKEN=$(curl -s -X POST http://localhost:5097/api/auth/login -H "Content-Type: application/json" -d '{"email":"admin@smartstack.io","password":"Admin123!"}' | jq -r '.accessToken')
+
+NAV_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5097/api/platform/navigation/modules \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Tenant-Id: 11111111-1111-1111-1111-111111111111")
+```
+
+| Status | Meaning |
+|--------|---------|
+| 200 | PASS — core seed data verified |
+| 401 | WARNING — authentication issue, seed data check skipped |
+| 404 | WARNING — API endpoint not available |
+
+---
+
+## Check 8: Cleanup
+
+```bash
+# Drop temp database
+sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "
+  IF DB_ID('$DB_NAME') IS NOT NULL
+  BEGIN
+    ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE;
+    DROP DATABASE [$DB_NAME];
+  END
+"
+```
+
+---
+
+## Error Reference Table
+
+| Error Pattern | Category | Fix |
+|---------------|----------|-----|
+| `Invalid column name '{Column}'` | Migration ordering | Reorder migration or split |
+| `Cannot insert duplicate key` | Seed data conflict | Make seed data idempotent |
+| `String or binary data would be truncated` | Column length | Increase MaxLength in EF config |
+| `INSERT conflicted with FOREIGN KEY constraint` | Missing parent | Ensure parent entities seeded first |
+| `NULL into column '{Column}'` | Missing default | Add default value or make nullable |
+| `Login failed for user` | LocalDB auth | Run `sqllocaldb start MSSQLLocalDB` |
+| `A network-related or instance-specific error` | LocalDB not running | Run `sqllocaldb start MSSQLLocalDB` |
+| `DefaultTenantId does NOT exist in core.tenant_Tenants` | Phantom FK | Use valid TenantId from InitializeSmartStackAsync() |
+| `EnableDevSeeding is FALSE` + empty tables | Seeding disabled | Add Program.cs override for Development |

package/templates/skills/validate-feature/steps/step-01-compile.md

@@ -18,10 +18,8 @@ ls *.sln 2>/dev/null || find . -maxdepth 2 -name "*.sln" -type f
 ### 2. Cleanup & Build
 
 ```bash
-# Cleanup corrupted EF Core design-time artifacts (Roslyn BuildHost bug on Windows)
-for d in src/*/bin?Debug; do [ -d "$d" ] && echo "Removing corrupted artifact: $d" && rm -rf "$d"; done
-
 dotnet build {SolutionFile} --verbosity minimal
+# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
 ```
 
 ### 3. Evaluate result

package/templates/skills/validate-feature/steps/step-04-api-smoke.md

@@ -8,122 +8,56 @@ prev_step: steps/step-03-integration-tests.md
 
 ## BLOCKING - All CRUD endpoints must respond correctly
 
+See `references/api-smoke-tests.md` for complete startup, CRUD sequence, and error classification.
+
+---
+
+## Quick Procedure
+
 ### 1. Find the API project
 
 ```bash
-# Find the API project
 ls src/*Api*/*.csproj 2>/dev/null || ls *Api*/*.csproj 2>/dev/null
 ```
 
-### 2. Start the API in the background (with output capture)
+### 2. Start API (see reference for crash detection)
 
 ```bash
-# Start the API on a test port, capturing stdout/stderr for error diagnosis
 dotnet run --project {ApiProject} --urls "http://localhost:5099" > /tmp/api-smoke-output.log 2>&1 &
 API_PID=$!
 ```
 
-### 3. Wait for the API to be ready (with crash detection)
+### 3. CRUD Tests
 
 ```bash
-# Poll the health endpoint, checking for early process death
-API_CRASHED=false
-for i in $(seq 1 30); do
-  # CRITICAL: Check if process is still alive FIRST
-  if ! kill -0 $API_PID 2>/dev/null; then
-    echo "API PROCESS CRASHED during startup"
-    cat /tmp/api-smoke-output.log 2>/dev/null
-    API_CRASHED=true
-    break
-  fi
-
-  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5099/health 2>/dev/null)
-  if [ "$HTTP_CODE" != "000" ]; then
-    echo "API is ready (HTTP $HTTP_CODE)"
-    break
-  fi
-  sleep 1
-done
+# GET all (200)
+# POST create (201)
+# GET by ID (200)
+# PUT update (200)
+# DELETE (204)
+# GET deleted (404) — verify deletion
 ```
 
-**If `API_CRASHED=true`:** Skip directly to section 8b (crash classification). Do NOT attempt CRUD tests.
-
-### 4. Authenticate (if required)
-
-```bash
-# Try to login with default test credentials
-TOKEN=$(curl -s -X POST http://localhost:5099/api/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"admin@smartstack.io","password":"Admin123!"}' \
-  | jq -r '.token // .accessToken // empty')
-```
+See `references/api-smoke-tests.md` section "CRUD Test Sequence" for exact curl commands.
 
-If auth is not configured yet, tests may work without a token (depending on configuration).
+### 4. HTTP Error Handling
 
-### 5. Test CRUD endpoints
+| Status | Cause | Fix |
+|--------|-------|-----|
+| 401 | Auth not configured | Check JWT setup |
+| 403 | Permissions missing | Verify PermissionConfiguration |
+| 404 | Route not registered | Check NavRoute on controller |
+| 500 | Unhandled exception | Check API logs |
+| Connection refused | API won't start | Check appsettings.json |
 
-**Set common headers:**
-```bash
-AUTH_HEADER="Authorization: Bearer $TOKEN"
-TENANT_HEADER="X-Tenant-Id: 11111111-1111-1111-1111-111111111111"
-CONTENT_TYPE="Content-Type: application/json"
-```
+### 5. Crash Classification
 
-#### 5.1 GET all (expect 200)
-```bash
-curl -s -w "\n%{http_code}" \
-  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
-  http://localhost:5099/api/{entity_code}
-```
-Expected: HTTP 200
+If API crashes at startup:
+- Classify error from `/tmp/api-smoke-output.log`
+- See `references/api-smoke-tests.md` section "Crash Classification"
+- Common: MISSING_PACKAGE, VERSION_MISMATCH, MISSING_DI, DATABASE_ERROR
 
-#### 5.2 POST create (expect 201 or 200)
-```bash
-CREATED=$(curl -s -w "\n%{http_code}" \
-  -X POST \
-  -H "$AUTH_HEADER" -H "$TENANT_HEADER" -H "$CONTENT_TYPE" \
-  -d '{"code":"smoke-test-01","name":"Smoke Test Entity"}' \
-  http://localhost:5099/api/{entity_code})
-```
-Expected: HTTP 201 or 200
-Extract the created entity ID from the response.
-
-#### 5.3 GET by ID (expect 200)
-```bash
-curl -s -w "\n%{http_code}" \
-  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
-  http://localhost:5099/api/{entity_code}/{created_id}
-```
-Expected: HTTP 200 with the entity data
-
-#### 5.4 PUT update (expect 200)
-```bash
-curl -s -w "\n%{http_code}" \
-  -X PUT \
-  -H "$AUTH_HEADER" -H "$TENANT_HEADER" -H "$CONTENT_TYPE" \
-  -d '{"code":"smoke-test-01","name":"Updated Smoke Test"}' \
-  http://localhost:5099/api/{entity_code}/{created_id}
-```
-Expected: HTTP 200
-
-#### 5.5 DELETE (expect 204)
-```bash
-curl -s -w "\n%{http_code}" \
-  -X DELETE \
-  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
-  http://localhost:5099/api/{entity_code}/{created_id}
-```
-Expected: HTTP 204
-
-#### 5.6 GET deleted (expect 404)
-```bash
-curl -s -w "\n%{http_code}" \
-  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
-  http://localhost:5099/api/{entity_code}/{created_id}
-```
-Expected: HTTP 404 (confirms deletion)
-
-### 6. Stop the API
+### 6. Stop API
 
 ```bash
 kill $API_PID 2>/dev/null
@@ -131,9 +65,9 @@ wait $API_PID 2>/dev/null
 rm -f /tmp/api-smoke-output.log
 ```
 
-### 7. Evaluate results
+---
 
-Build a report:
+## Report
 
 ```markdown
 ## Feature Validation: {entity_name}
@@ -153,53 +87,8 @@ Build a report:
 ### Overall: {ALL_PASS or FAILURES_DETECTED}
 ```
 
-### 8. Handle HTTP failures
-
-If any smoke test fails:
-- **401 Unauthorized** -> Auth not configured, check JWT setup
-- **403 Forbidden** -> Permissions not seeded, check PermissionConfiguration
-- **404 Not Found** -> Route not registered, check controller NavRoute
-- **500 Internal Server Error** -> Check API logs for exception details
-- **Connection refused** -> API didn't start, check startup configuration
-
-### 8b. Handle startup crash (if API_CRASHED=true)
-
-If the API process died during startup, classify the error from the captured output:
-
-| Error Pattern in Output | Classification | Actionable Fix |
-|------------------------|----------------|----------------|
-| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | **MISSING_PACKAGE** | `dotnet add {ApiProject} package {Name} --version {V.Major}.{V.Minor}.{V.Patch}` |
-| `FileNotFoundException: Could not load file or assembly '{Name}'` | **MISSING_ASSEMBLY** | Check .csproj references, ensure assembly is built |
-| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | **VERSION_MISMATCH** | `dotnet add {ApiProject} package {Asm} --version {CorrectVersion}` |
-| `MissingMethodException` | **VERSION_MISMATCH** | Update package to matching version |
-| `InvalidOperationException: Unable to resolve service for type '{Type}'` | **MISSING_DI** | Add DI registration for `{Type}` in `DependencyInjection.cs` or `Program.cs` |
-| `SqlException` or connection errors | **DATABASE_ERROR** | Check connection string in `appsettings.json` |
-
-**For MISSING_PACKAGE errors:**
-1. Extract assembly name: the text between single quotes after "file or assembly"
-2. Extract version: the `Version=X.X.X.X` part (first 3 segments = NuGet version)
-3. Map to NuGet package: assembly name usually equals package name
-4. Output: `FIX: dotnet add {ApiProject} package {PackageName} --version {Major.Minor.Patch}`
-5. **If assembly starts with `SmartStack.`**: this is a framework bug in SmartStack.csproj, not a client project issue
-
-**Report format for crashed API:**
-```markdown
-## Feature Validation: {entity_name}
-
-| Check | Result | Details |
-|-------|--------|---------|
-| Dependencies | {dependency_check_result} | |
-| Solution build | {build_result} | |
-| Unit tests | {unit_test_result} | {unit_test_count} passed |
-| Integration tests | {integration_test_result} | {integration_test_count} passed |
-| API startup | **CRASHED** | {classification}: {error_summary} |
-
-### Crash Details
-**Classification:** {classification}
-**Error:** {first line of relevant error}
-**Fix:** `{fix_command}`
+---
 
-### Overall: FAILURES_DETECTED (API startup crash)
-```
+## NEXT STEP:
 
-Report all findings to the user with actionable next steps.
+Proceed to `./step-05-db-validation.md`