@atlashub/smartstack-cli 3.13.0 → 3.15.0

package/templates/skills/ralph-loop/references/error-classification.md

@@ -0,0 +1,143 @@
+# Error Classification Reference
+
+> **Loaded by:** compact-loop.md (build failure analysis) and category-rules.md (validation section)
+> **Purpose:** Classify build and runtime errors to apply the correct fix strategy.
+> **Key insight:** Not all errors are code errors. Package/config errors require different fixes than code errors.
+
+---
+
+## Error Categories
+
+### Category A: Missing NuGet Package (FIX = `dotnet add package`)
+
+> **These errors CANNOT be fixed by editing source code. Do NOT waste iterations trying.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | `Could not load file or assembly 'Microsoft.Extensions.Http.Resilience, Version=10.2.0.0'` | `dotnet add package {Name} --version {V.Major}.{V.Minor}.{V.Patch}` |
+| `error CS0246: The type or namespace name '{Type}' could not be found` (after restore) | `The type or namespace name 'Polly' could not be found` | `dotnet add package {PackageName}` |
+| `error NU1101: Unable to find package {Name}` | Package source misconfigured | Check `nuget.config` sources |
+
+**Detection heuristic:** If `dotnet build` fails with CS0246 and the missing type is NOT in any project file (grep across `src/`), it is a missing package, not a missing `using` statement.
+
+**Fix procedure:**
+1. Extract package name from error message
+2. Run `dotnet add {TargetProject} package {PackageName}`
+3. Run `dotnet restore`
+4. Rebuild -- if still failing, the version may need to be pinned
+
+---
+
+### Category B: Version Mismatch (FIX = update package version)
+
+> **These errors CANNOT be fixed by editing source code.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | Type exists in different version | `dotnet add package {Asm} --version {CorrectVersion}` |
+| `MissingMethodException: Method not found: '{Method}'` | Method signature changed between versions | Update to version that has the method |
+| `NU1605: Detected package downgrade` | Version conflict in dependency tree | Align all references to same version |
+| `FileLoadException: Could not load file or assembly '{Name}'. The located assembly's manifest definition does not match the assembly reference.` | Wrong version loaded | Pin correct version in .csproj |
+
+**Fix procedure:**
+1. Identify the assembly/package name
+2. Run `dotnet list package --include-transitive` to see actual resolved version
+3. If conflict: add explicit `<PackageReference>` with correct version
+4. Rebuild
+
+---
+
+### Category C: Missing DI Registration (FIX = edit DI configuration)
+
+> **These errors require editing `DependencyInjection.cs` or `Program.cs`, NOT the service/interface code.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `InvalidOperationException: Unable to resolve service for type '{Interface}'` | Missing `services.AddScoped<IFoo, Foo>()` | Add DI registration |
+| `InvalidOperationException: No service for type '{Type}' has been registered` | Same as above | Same |
+| `InvalidOperationException: Unable to resolve service for type '{Type}' while attempting to activate '{Consumer}'` | Consumer's dependency not registered | Register the missing dependency |
+
+**Fix procedure:**
+1. Extract the interface/type name from error
+2. Find the implementation class (grep for `class.*: {Interface}`)
+3. Add `services.AddScoped<{Interface}, {Implementation}>()` to appropriate DI file
+4. Rebuild
+
+---
+
+### Category D: Database/Migration (FIX = run migration commands)
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `SqlException: Invalid object name '{TableName}'` | Table does not exist | `dotnet ef database update` |
+| `SqlException: Invalid column name '{Column}'` | Column not in schema | Create and apply migration |
+| `RelationalEventId.PendingModelChangesWarning` | Model changed, no migration | `dotnet ef migrations add {Name}` |
+
+---
+
+### Category E: Configuration (FIX = edit appsettings.json)
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `InvalidOperationException: The ConnectionString property has not been initialized` | Missing connection string | Add to `appsettings.json` |
+| `ArgumentNullException: Value cannot be null. (Parameter 'connectionString')` | Same | Same |
+| `OptionsValidationException: Validation failed for '{Section}'` | Missing required config section | Add section to `appsettings.json` |
+
+---
+
+### Category F: Code Error (FIX = edit source code)
+
+> **Only this category should trigger code editing in ralph-loop iterations.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `error CS0246` + type IS in a project file | Missing `using` statement | Add `using {Namespace};` |
+| `error CS1061` | Method does not exist on type | Fix method call or add method |
+| `error CS0103` | Name does not exist in current context | Fix variable/method reference |
+| `error CS0029` | Cannot implicitly convert type | Fix type mismatch |
+| Test assertion failures | `Assert.Equal` fails | Fix source code (not tests) |
+
+---
+
+## Decision Tree
+
+When a build or runtime error occurs, follow this tree:
+
+```
+BUILD/RUNTIME ERROR
+  |
+  +-- Contains "Could not load file or assembly" ?
+  |     YES -> Category A or B (NEVER edit source code)
+  |     Extract package name -> dotnet add package -> rebuild
+  |
+  +-- Contains "Unable to resolve service" ?
+  |     YES -> Category C (edit DI config ONLY)
+  |     Find implementation -> add registration -> rebuild
+  |
+  +-- Contains "SqlException" or "Invalid object name" ?
+  |     YES -> Category D (run migrations)
+  |     dotnet ef migrations add / database update
+  |
+  +-- Contains "ConnectionString" or "OptionsValidation" ?
+  |     YES -> Category E (edit config files)
+  |
+  +-- error CS#### (C# compiler error) ?
+  |     YES -> Is the missing type in ANY project file?
+  |           NO  -> Category A (missing package)
+  |           YES -> Category F (fix source code)
+  |
+  +-- Test failure (Assert/Expected) ?
+        YES -> Category F (fix source code, NOT tests)
+```
+
+---
+
+## Ralph-Loop Integration Rules
+
+1. **Before ANY code fix attempt:** Classify the error using the decision tree above
+2. **Categories A, B:** Run package commands IMMEDIATELY. Do NOT count as a "fix iteration"
+3. **Category C:** Edit DI file only. One targeted fix, rebuild, verify
+4. **Category D:** Run migration commands. Do NOT edit code
+5. **Category E:** Edit config file only
+6. **Category F:** Normal ralph-loop code fix iteration
+7. **If 2+ consecutive iterations fail on same error after code fixes -> re-classify** (likely wrong category)

package/templates/skills/ralph-loop/steps/step-05-report.md

@@ -70,6 +70,60 @@ if [ -d "$TEST_PROJECT" ]; then
 fi
 ```
 
+### 1e. Final DB Validation (if infrastructure/migration tasks were executed)
+
+```bash
+INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
+API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
+
+if [ -n "$INFRA_PROJECT" ] && [ -n "$API_PROJECT" ]; then
+  echo "FINAL DB VALIDATION: Applying all migrations on fresh SQL Server LocalDB..."
+
+  # 1. Check no pending model changes
+  dotnet ef migrations has-pending-model-changes \
+    --project "$INFRA_PROJECT" \
+    --startup-project "$API_PROJECT"
+  PENDING_RESULT=$?
+
+  # 2. Apply all migrations on temp database
+  DB_NAME="SmartStack_FinalCheck_$(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"
+  MIGRATION_RESULT=$?
+
+  # 3. Run integration tests against real SQL Server
+  INT_TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
+  INT_TEST_RESULT=0
+  if [ -n "$INT_TEST_PROJECT" ]; then
+    dotnet test "$INT_TEST_PROJECT" --no-build --verbosity minimal
+    INT_TEST_RESULT=$?
+  fi
+
+  # 4. Cleanup
+  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" 2>/dev/null
+
+  # Record results
+  DB_VALIDATION="PASS"
+  [ $PENDING_RESULT -ne 0 ] && DB_VALIDATION="FAIL (pending model changes)"
+  [ $MIGRATION_RESULT -ne 0 ] && DB_VALIDATION="FAIL (migration apply failed)"
+  [ $INT_TEST_RESULT -ne 0 ] && DB_VALIDATION="FAIL (integration tests failed on SQL Server)"
+fi
+```
+
+Include DB validation results in report section:
+```markdown
+## DB Validation (SQL Server LocalDB)
+| Check | Result |
+|-------|--------|
+| Pending model changes | {PENDING_RESULT == 0 ? "PASS" : "FAIL"} |
+| Migrations apply cleanly | {MIGRATION_RESULT == 0 ? "PASS" : "FAIL"} |
+| Integration tests (real SQL Server) | {INT_TEST_RESULT == 0 ? "PASS" : "N/A"} |
+| Overall | {DB_VALIDATION} |
+```
+
 ## 2. Generate Report
 
 Write to `.ralph/reports/{feature-slug}.md`:

package/templates/skills/review-code/references/smartstack-conventions.md

@@ -291,6 +291,22 @@ builder.ToTable("auth_users", SchemaConstants.Core);
 | `doc_` | Documents | doc_files, doc_versions |
 | `tkt_` | Tickets/Support | tkt_tickets, tkt_comments |
 
+**Custom Application Prefixes:**
+
+Business applications define their own table prefix during `/business-analyse` cadrage phase.
+Format: `{2-5 lowercase letters}_` — stored in `feature.json` → `metadata.tablePrefix`.
+
+| Application | Prefix | Examples |
+|-------------|--------|----------|
+| Human Resources | `rh_` | rh_Employees, rh_Contracts |
+| Finance | `fi_` | fi_Invoices, fi_Payments |
+| CRM | `crm_` | crm_Contacts, crm_Opportunities |
+
+Rules:
+- Must not collide with platform prefixes
+- Registered in MCP config via `conventions.customTablePrefixes`
+- All entities in the same application share the same prefix
+
 **Schemas:**
 - `core` (SchemaConstants.Core): SmartStack platform tables
 - `extensions` (SchemaConstants.Extensions): Client-specific tables

package/templates/skills/validate-feature/SKILL.md

@@ -11,10 +11,12 @@ tags: [testing, validation, smoke-test, integration]
 ## PURPOSE
 
 Validates that a scaffolded SmartStack feature **actually works** by running:
+0. Dependency pre-flight check (restore, transitive deps, quick startup test)
 1. Compilation check (`dotnet build`)
 2. Unit tests (`dotnet test`)
 3. Integration tests (`dotnet test --filter`)
 4. API smoke test (start API, hit CRUD endpoints, verify responses)
+5. DB validation (SQL Server: migrations, seed data, tenant isolation, LINQ→SQL)
 
 ## WHEN TO USE
 
@@ -50,14 +52,16 @@ Validates that a scaffolded SmartStack feature **actually works** by running:
 
 ## EXECUTION
 
-This skill follows a 4-step sequential workflow:
+This skill follows a 6-step sequential workflow:
 
 | Step | File | Description | Blocking |
 |------|------|-------------|----------|
+| 0 | `steps/step-00-dependencies.md` | Pre-flight dependency check (restore, runtime assembly validation) | YES |
 | 1 | `steps/step-01-compile.md` | Build the full solution | YES |
 | 2 | `steps/step-02-unit-tests.md` | Run unit tests | YES |
 | 3 | `steps/step-03-integration-tests.md` | Run integration tests | YES |
 | 4 | `steps/step-04-api-smoke.md` | Start API and test CRUD endpoints | YES |
+| 5 | `steps/step-05-db-validation.md` | SQL Server validation (migrations, seed data, tenant isolation, LINQ→SQL) | YES |
 
 Each step must PASS before proceeding to the next.
 
@@ -78,6 +82,9 @@ A validation report showing pass/fail for each check:
 | API smoke: GET /api/{entity}/{id} | PASS (200) |
 | API smoke: PUT /api/{entity}/{id} | PASS (200) |
 | API smoke: DELETE /api/{entity}/{id} | PASS (204) |
+| DB: Migrations apply (SQL Server) | PASS |
+| DB: Integration tests (SQL Server) | PASS |
+| DB: Seed data accessible | PASS |
 
 Result: ALL CHECKS PASSED
 ```
@@ -87,5 +94,8 @@ Result: ALL CHECKS PASSED
 - All unit tests pass
 - All integration tests pass
 - API smoke tests return expected HTTP status codes (200, 201, 204)
+- Migrations apply cleanly on SQL Server LocalDB
+- Integration tests pass against real SQL Server (LINQ→SQL, tenant isolation)
+- Seed data is accessible via API endpoints
 - Validation report displayed with per-check results
 </success_criteria>

package/templates/skills/validate-feature/steps/step-00-dependencies.md

@@ -0,0 +1,121 @@
+---
+name: step-00-dependencies
+description: Pre-flight dependency check - verify NuGet packages and runtime assembly resolution
+next_step: steps/step-01-compile.md
+---
+
+# Step 0: Dependency Pre-Flight Check
+
+## BLOCKING - Must pass before proceeding to compilation
+
+### 1. Locate the solution file
+
+```bash
+ls *.sln 2>/dev/null || find . -maxdepth 2 -name "*.sln" -type f
+```
+
+Store as `{solution_file}`.
+
+### 2. Restore packages with diagnostic output
+
+```bash
+dotnet restore {SolutionFile} --verbosity normal 2>&1
+```
+
+**Parse the output for these NuGet warnings:**
+
+| Warning Code | Meaning | Action |
+|-------------|---------|--------|
+| `NU1603` | Package version resolved to different version than requested | Version mismatch -- verify package versions in .csproj |
+| `NU1605` | Downgrade detected | Package version conflict -- update to consistent version |
+| `NU1608` | Package version outside dependency constraint | Incompatible dependency versions |
+| `NU1701` | Package restored using fallback target framework | Potential runtime incompatibility |
+| `NU1902` | Package version range could not be satisfied | Missing package source |
+
+**If ANY NU1603/NU1605/NU1608 warnings are found:**
+- List each warning with the affected package name and versions
+- Suggest fix command: `dotnet add {ProjectFile} package {PackageName} --version {CorrectVersion}`
+- This is a WARNING (proceed with caution, may cause runtime errors)
+
+### 3. Quick startup smoke test (runtime assembly validation)
+
+> **CRITICAL:** This step catches errors that `dotnet build` alone misses.
+> A successful build does NOT guarantee all assemblies are resolvable at runtime.
+> Example: `FileNotFoundException: Could not load file or assembly 'X'` only appears at runtime.
+
+```bash
+# Find the API project
+API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
+
+if [ -n "$API_PROJECT" ]; then
+  # Build first (quick, no restore)
+  dotnet build "$API_PROJECT" --no-restore --verbosity quiet 2>&1
+
+  # Start the API and capture output
+  dotnet run --project "$API_PROJECT" --urls "http://localhost:5098" > /tmp/ss-dep-check.log 2>&1 &
+  STARTUP_PID=$!
+
+  # Wait up to 10 seconds for either: process exits (crash) or health responds (success)
+  STARTUP_OK=false
+  for i in $(seq 1 10); do
+    # Check if process is still alive
+    if ! kill -0 $STARTUP_PID 2>/dev/null; then
+      # Process died - read the output for error classification
+      echo "API STARTUP CRASH DETECTED"
+      cat /tmp/ss-dep-check.log
+      break
+    fi
+
+    # Check if health endpoint responds
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5098/health 2>/dev/null)
+    if [ "$HTTP_CODE" != "000" ]; then
+      STARTUP_OK=true
+      break
+    fi
+    sleep 1
+  done
+
+  # Cleanup
+  kill $STARTUP_PID 2>/dev/null
+  wait $STARTUP_PID 2>/dev/null
+  rm -f /tmp/ss-dep-check.log
+fi
+```
+
+### 4. Classify startup errors (if crash detected)
+
+If the API process crashed, read the output and classify:
+
+| Error Pattern | Classification | Fix Command |
+|--------------|----------------|-------------|
+| `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}'` (no version) | **MISSING_ASSEMBLY** | Check .csproj references and `PrivateAssets` settings |
+| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | **VERSION_MISMATCH** | `dotnet add {ApiProject} package {Asm} --version {CorrectVersion}` |
+| `MissingMethodException: Method not found: '{Method}'` | **VERSION_MISMATCH** | Update package to matching version |
+| `InvalidOperationException: Unable to resolve service for type '{Type}'` | **MISSING_DI** | Add `services.AddScoped<{Interface}, {Implementation}>()` in DI setup |
+| `InvalidOperationException: The ConnectionString property has not been initialized` | **MISSING_CONFIG** | Add connection string to `appsettings.json` |
+
+**For MISSING_PACKAGE specifically:**
+1. Extract the assembly name from the error (text between quotes after "file or assembly")
+2. The NuGet package name is usually identical to the assembly name (e.g., `Microsoft.Extensions.Http.Resilience`)
+3. Extract the version: `Version=X.X.X.X` -> take first 3 segments as NuGet version
+4. Provide exact 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
+
+### 5. Evaluate result
+
+| Scenario | Action |
+|----------|--------|
+| No warnings, startup OK | PASS -> proceed to step 1 (compile) |
+| Warnings only, startup OK | WARNING -> display warnings, proceed to step 1 |
+| Startup crash with classified error | **FAIL** -> display classification + fix command, **STOP** |
+| Startup crash with unclassified error | **FAIL** -> display full output, **STOP** for investigation |
+
+### 6. Store state
+
+```
+{dependency_check_result} = PASS | WARNING | FAIL
+{dependency_warnings} = list of warnings (if any)
+{startup_error_class} = classification (if crash detected)
+{startup_fix_command} = suggested fix command (if crash detected)
+```

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

@@ -15,32 +15,38 @@ prev_step: steps/step-03-integration-tests.md
 ls src/*Api*/*.csproj 2>/dev/null || ls *Api*/*.csproj 2>/dev/null
 ```
 
-### 2. Start the API in the background
+### 2. Start the API in the background (with output capture)
 
 ```bash
-# Start the API on a test port
-dotnet run --project {ApiProject} --urls "http://localhost:5099" &
+# 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
+### 3. Wait for the API to be ready (with crash detection)
 
 ```bash
-# Poll the health endpoint (or root) until it responds
+# Poll the health endpoint, checking for early process death
+API_CRASHED=false
 for i in $(seq 1 30); do
-  curl -s -o /dev/null -w "%{http_code}" http://localhost:5099/health 2>/dev/null
-  if [ $? -eq 0 ]; then
-    echo "API is ready"
+  # 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
 ```
 
-If no `/health` endpoint exists, try:
-```bash
-curl -s -o /dev/null -w "%{http_code}" http://localhost:5099/api/{entity_code}
-```
+**If `API_CRASHED=true`:** Skip directly to section 8b (crash classification). Do NOT attempt CRUD tests.
 
 ### 4. Authenticate (if required)
 
@@ -121,6 +127,8 @@ Expected: HTTP 404 (confirms deletion)
 
 ```bash
 kill $API_PID 2>/dev/null
+wait $API_PID 2>/dev/null
+rm -f /tmp/api-smoke-output.log
 ```
 
 ### 7. Evaluate results
@@ -145,7 +153,7 @@ Build a report:
 ### Overall: {ALL_PASS or FAILURES_DETECTED}
 ```
 
-### 8. Handle failures
+### 8. Handle HTTP failures
 
 If any smoke test fails:
 - **401 Unauthorized** -> Auth not configured, check JWT setup
@@ -154,4 +162,44 @@ If any smoke test fails:
 - **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)
+```
+
 Report all findings to the user with actionable next steps.