@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/validate-feature/steps/step-05-db-validation.md

@@ -1,149 +1,149 @@
----
-name: step-05-db-validation
-description: Validate database schema, migrations, seed data, and multi-tenant isolation against real SQL Server
-prev_step: steps/step-04-api-smoke.md
-next_step: null
----
-
-# Step 5: Database Validation (SQL Server LocalDB)
-
-> **Purpose:** Verify migrations apply correctly, seed data inserts, LINQ queries execute on SQL Server, multi-tenant isolation works on REAL SQL Server (not SQLite).
-
-See `references/db-validation-checks.md` for detailed checks, error classification, and fixes.
-
----
-
-## Procedure
-
-### Check 1: LocalDB Available?
-
-```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"
-```
-
-If exit code != 0 → Create missing migration:
-```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"
-```
-
-If FAIL → Check for: migration ordering, duplicate migration, seed data conflict (see reference)
-
-### Check 4: Integration Tests (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, multi-tenant isolation, soft delete, EF configs, repositories on real SQL Server
-
-### Check 5: Dev Seeding Enabled?
-
-```bash
-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)
-
-# Check for Program.cs override or appsettings EnableDevSeeding = true
-```
-
-If not enabled → 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 '"')
-
-sqlcmd -S "(localdb)\MSSQLLocalDB" -d "$DB_NAME" -Q "
-  SET NOCOUNT ON;
-  SELECT COUNT(*) FROM core.tenant_Tenants WHERE Id = '$TENANT_GUID'
-"
-```
-
-If COUNT = 0 → Use a TenantId seeded by `InitializeSmartStackAsync()`
-
-### Check 7: Seed Data Accessible?
-
-```bash
-dotnet run --project "$API_PROJECT" --urls "http://localhost:5097" \
-  -- --ConnectionStrings:DefaultConnection="$CONN_STRING" &
-
-# Verify seed data via API endpoint
-# (See reference for full commands)
-```
-
-### Check 8: Cleanup
-
-```bash
-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
-"
-```
-
----
-
-## Validation Summary
-
-```
-## DB Validation: {EntityName}
-
-| Check | Result | Details |
-|-------|--------|---------|
-| LocalDB available | PASS/SKIP | sqllocaldb info MSSQLLocalDB |
-| Pending model changes | PASS/FAIL | dotnet ef migrations has-pending |
-| Migrations apply cleanly | PASS/FAIL | dotnet ef database update on temp DB |
-| Integration tests (SQL Server) | PASS/FAIL | dotnet test --filter Integration |
-| EnableDevSeeding active | PASS/WARN | Program.cs override or appsettings |
-| DefaultTenantId FK valid | PASS/FAIL | SeedConstants GUID exists in tenant_Tenants |
-| Seed data accessible | PASS/WARN | API endpoints return seeded data |
-| Temp DB cleanup | PASS/WARN | Database dropped |
-
-DB Validation Result: {PASS / FAIL / SKIPPED}
-```
-
-**Interpretation:**
-- **PASS** — All checks covered: migrations, SQL Server, LINQ→SQL, isolation, seeding config
-- **FAIL** — Fix before committing
-- **SKIPPED** — LocalDB unavailable; tests ran on SQLite only (partial coverage)
-
----
-
-## Error Reference
-
-See `references/db-validation-checks.md` for complete error classification and fixes including:
-- Migration ordering issues
-- Seed data conflicts
-- ForeignKey constraint violations
-- LocalDB connectivity
-- EnableDevSeeding configuration
-- DefaultTenantId phantom FK
-
----
-
-## NEXT STEP:
-
-DB validation complete. Review all step results and generate final report.
+---
+name: step-05-db-validation
+description: Validate database schema, migrations, seed data, and multi-tenant isolation against real SQL Server
+prev_step: steps/step-04-api-smoke.md
+next_step: null
+---
+
+# Step 5: Database Validation (SQL Server LocalDB)
+
+> **Purpose:** Verify migrations apply correctly, seed data inserts, LINQ queries execute on SQL Server, multi-tenant isolation works on REAL SQL Server (not SQLite).
+
+See `references/db-validation-checks.md` for detailed checks, error classification, and fixes.
+
+---
+
+## Procedure
+
+### Check 1: LocalDB Available?
+
+```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"
+```
+
+If exit code != 0 → Create missing migration:
+```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"
+```
+
+If FAIL → Check for: migration ordering, duplicate migration, seed data conflict (see reference)
+
+### Check 4: Integration Tests (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, multi-tenant isolation, soft delete, EF configs, repositories on real SQL Server
+
+### Check 5: Dev Seeding Enabled?
+
+```bash
+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)
+
+# Check for Program.cs override or appsettings EnableDevSeeding = true
+```
+
+If not enabled → 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 '"')
+
+sqlcmd -S "(localdb)\MSSQLLocalDB" -d "$DB_NAME" -Q "
+  SET NOCOUNT ON;
+  SELECT COUNT(*) FROM core.tenant_Tenants WHERE Id = '$TENANT_GUID'
+"
+```
+
+If COUNT = 0 → Use a TenantId seeded by `InitializeSmartStackAsync()`
+
+### Check 7: Seed Data Accessible?
+
+```bash
+dotnet run --project "$API_PROJECT" --urls "http://localhost:5097" \
+  -- --ConnectionStrings:DefaultConnection="$CONN_STRING" &
+
+# Verify seed data via API endpoint
+# (See reference for full commands)
+```
+
+### Check 8: Cleanup
+
+```bash
+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
+"
+```
+
+---
+
+## Validation Summary
+
+```
+## DB Validation: {EntityName}
+
+| Check | Result | Details |
+|-------|--------|---------|
+| LocalDB available | PASS/SKIP | sqllocaldb info MSSQLLocalDB |
+| Pending model changes | PASS/FAIL | dotnet ef migrations has-pending |
+| Migrations apply cleanly | PASS/FAIL | dotnet ef database update on temp DB |
+| Integration tests (SQL Server) | PASS/FAIL | dotnet test --filter Integration |
+| EnableDevSeeding active | PASS/WARN | Program.cs override or appsettings |
+| DefaultTenantId FK valid | PASS/FAIL | SeedConstants GUID exists in tenant_Tenants |
+| Seed data accessible | PASS/WARN | API endpoints return seeded data |
+| Temp DB cleanup | PASS/WARN | Database dropped |
+
+DB Validation Result: {PASS / FAIL / SKIPPED}
+```
+
+**Interpretation:**
+- **PASS** — All checks covered: migrations, SQL Server, LINQ→SQL, isolation, seeding config
+- **FAIL** — Fix before committing
+- **SKIPPED** — LocalDB unavailable; tests ran on SQLite only (partial coverage)
+
+---
+
+## Error Reference
+
+See `references/db-validation-checks.md` for complete error classification and fixes including:
+- Migration ordering issues
+- Seed data conflicts
+- ForeignKey constraint violations
+- LocalDB connectivity
+- EnableDevSeeding configuration
+- DefaultTenantId phantom FK
+
+---
+
+## NEXT STEP:
+
+DB validation complete. Review all step results and generate final report.

package/templates/skills/validation/conventions/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: conventions
+description: >
+  Audits a SmartStack project for convention violations — namespace prefixes
+  by Clean Architecture layer, entity patterns (BaseEntity + tenant interfaces
+  + private ctor + factory), and controller routing (NavRoute vs hardcoded
+  Route). Produces a structured JSON report of findings. Use when the user
+  asks to audit, validate or check a project's conformance with SmartStack
+  conventions. Keywords: audit, conventions, conformance, check project,
+  validate structure, namespace, NavRoute, entity compliance.
+phase: validation
+cli: validate-conventions
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# conventions
+
+Scans a SmartStack project and reports convention violations across three
+categories. Delegates all logic to a CLI invoked via Bash.
+
+## When to use this skill
+
+Activate when the user asks to:
+
+- Audit a project for SmartStack conformance
+- Check whether an entity / controller / namespace follows the conventions
+- Validate the structure before a PR / deployment
+- Understand which parts of the project drift from the framework patterns
+
+### When NOT to use
+
+- For runtime tests (unit / integration) → use the project's test runner
+- For lint / style issues (formatting, unused imports) → use ESLint / StyleCop
+- For architectural diagrams → use dedicated diagramming tools
+
+---
+
+## Invocation
+
+Invoke via **Bash**. The CLI accepts the project path as an argument (or uses
+the current working directory) and runs a selection of checks:
+
+```bash
+npx tsx skills/validation/conventions/cli/validate-conventions/index.ts \
+  [--project-path <abs-path>] \
+  [--checks <list>] \
+  [--base-namespace <name>]
+```
+
+### Arguments
+
+- `--project-path` (optional) — absolute path of the SmartStack project. If
+  omitted, the CLI uses `process.cwd()`.
+- `--checks` (optional) — comma-separated list of checks to run. Valid values:
+  `namespaces`, `entities`, `controllers`, `all`. Default: `all`.
+- `--base-namespace` (optional) — override the auto-detected base namespace
+  (e.g. `--base-namespace Acme.Corp`). Use when the CLI cannot detect the
+  expected namespace from `.csproj` files.
+
+### Examples
+
+Full audit of the default project:
+```bash
+npx tsx skills/validation/conventions/cli/validate-conventions/index.ts \
+  --project-path "D:/01 - projets/SmartStack.app/features/IA-Workflow"
+```
+
+Only check controller routes:
+```bash
+npx tsx skills/validation/conventions/cli/validate-conventions/index.ts \
+  --project-path "D:/..." --checks controllers
+```
+
+---
+
+## Reading the result
+
+The CLI prints a JSON envelope on stdout:
+
+```json
+{
+  "success": true,
+  "command": "validate-conventions",
+  "data": {
+    "valid": true,
+    "summary": "All checks passed (47 files inspected, 3 warnings, 0 infos)"
+  },
+  "report": {
+    "projectPath": "...",
+    "structure": { "domain": "...", "application": "...", ... },
+    "checksRun": ["namespaces", "entities", "controllers"],
+    "filesInspected": 47,
+    "findings": [
+      {
+        "severity": "warning",
+        "category": "entities",
+        "message": "Entity \"Foo\" is missing a factory method",
+        "file": "src/Domain/Foo.cs",
+        "suggestion": "Add: public static Foo Create(...)"
+      }
+    ],
+    "counts": { "errors": 0, "warnings": 3, "infos": 0 },
+    "byCategory": { "namespaces": 0, "entities": 3, "controllers": 0 }
+  },
+  "errors": [],
+  "warnings": [],
+  "nextSteps": ["Review the warnings — they indicate drift..."]
+}
+```
+
+### Interpretation
+
+- `data.valid` — `true` when `counts.errors === 0`. Warnings don't block.
+- `report.findings` — the authoritative list of violations. Each finding has
+  a `severity`, `category`, `message`, optional `file` path (relative to the
+  project root), and `suggestion` for how to fix it.
+- `report.counts` — quick totals for a summary.
+- `report.byCategory` — violations grouped by category — useful to decide
+  which layer to focus on first.
+
+### What to tell the user
+
+- If `valid === true` and `counts.warnings === 0`: celebrate.
+- If `valid === true` and `counts.warnings > 0`: report the warnings grouped
+  by category and suggest reviewing the most severe ones first.
+- If `valid === false`: show the errors FIRST (group by category), then the
+  warnings. Highlight files that appear in multiple findings.
+
+---
+
+## Checks implemented in this version
+
+### 1. `namespaces`
+
+Scans `.cs` files in each Clean Architecture layer and verifies the namespace
+starts with the expected prefix:
+
+- `{BaseNamespace}.Domain` for files in Domain
+- `{BaseNamespace}.Application` for files in Application
+- `{BaseNamespace}.Infrastructure` for files in Infrastructure
+- `{BaseNamespace}.Api` for files in Api
+
+Findings are downgraded from `error` to `warning` when the namespace still
+follows the Clean Architecture pattern (`{Base}.{Layer}`) but with a different
+base (common in client extension projects).
+
+### 2. `entities`
+
+For every class / record in the Domain layer that inherits `BaseEntity`:
+
+- **Warning** if no tenant interface is declared (ITenantEntity,
+  IOptionalTenantEntity, IScopedTenantEntity)
+- **Warning** if there is no private parameterless constructor (required by EF)
+- **Warning** if there is no `public static {Name} Create(...)` factory method
+
+Value objects and classes that do not inherit BaseEntity are skipped.
+
+### 3. `controllers`
+
+For every controller in the API layer (excluding a whitelist of system
+controllers):
+
+- **Error** if the controller declares BOTH `[NavRoute(...)]` and a hardcoded
+  `[Route(...)]` — these conflict at runtime
+- **Error** if a NavRoute has fewer than 2 dot-separated segments
+- **Error** if a NavRoute contains uppercase characters
+- **Warning** if the controller uses hardcoded `[Route(...)]` instead of
+  `[NavRoute]`
+
+---
+
+## Checks not yet implemented (future)
+
+The legacy MCP tool `validate_conventions` shipped 16 checks. This first version
+ports 3 of them. The remaining 13 will be added in upcoming waves:
+
+`tables`, `migrations`, `services`, `tenants`, `layouts`, `tabs`, `hierarchies`,
+`protected-actions`, `permissions`, `frontend-routes`, `feature-json`,
+`code-patterns`, `architecture`.
+
+If the user asks for one of these, inform them it's not yet available as a
+CLI check — suggest manual review or wait for the next wave.
+
+---
+
+## Rules
+
+- Never invoke the CLI without first confirming the project path with the user.
+- Parse the stdout JSON — ignore stderr.
+- If the CLI exits non-zero, treat it as a failure (errors found OR internal
+  error). Read `errors[]` first, then `report.findings` if any.
+- Progressive disclosure: `patterns.md` contains deeper context on why these
+  conventions exist and how to fix common violations.