@atlashub/smartstack-cli 2.0.0 → 2.2.0

package/templates/skills/business-analyse/templates/tpl-handoff.md

@@ -1,7 +1,7 @@
 # Template Development Handoff
 
-> **Usage:** Template for 4-development-handoff.md
-> **Loaded in:** step-05-handoff.md
+> **Usage:** Template for step-04-handoff.md
+> **Data source:** feature.json (sections: metadata, analysis, specification, handoff)
 
 ---
 
@@ -9,8 +9,9 @@
 # Development Handoff - {FEAT-XXX} {Feature Name}
 
 > **Module:** business/{application}/{module}
-> **Version:** 1.0
-> **Validated Specs:** FRD v1.0 (validation.json)
+> **Version:** {version}
+> **Validated Specs:** feature.json (validation.decision = APPROVED)
+> **Source:** `docs/business/{app}/{module}/business-analyse/v{version}/feature.json`
 > **Implementation:** `/ralph-loop -r` (iterative) | `/feature-full business/{app}/{module}` (one-shot)
 
 ## DEVELOPER INSTRUCTIONS
@@ -34,10 +35,13 @@ This document is a self-contained prompt for Claude Code.
 
 | Attribute | Value |
 |----------|--------|
-| Feature ID | {FEAT-XXX} |
-| Module | business/{application}/{module} |
+| Feature ID | {feature.id} |
+| Module | business/{feature.metadata.application}/{feature.metadata.module} |
 | Base Permission | `business.{app}.{module}` |
-| Complexity | {Simple/Medium/Complex} |
+| Project Namespace | {feature.metadata.projectNamespace} |
+| DB Schema | `extensions` (client entities) / `core` (navigation, permissions) |
+| Table Prefix | `{prefix}_` |
+| Complexity | {feature.handoff.complexity} |
 
 ## 2. [EXPLORE] EXISTING PATTERNS
 
@@ -45,59 +49,91 @@ BEFORE coding, explore these files to understand the patterns:
 
 ```
 BACKEND:
-- src/SmartStack.Domain/Entities/ → Entity structure
-- src/SmartStack.Application/Features/ → CQRS pattern
-- src/SmartStack.Infrastructure/Persistence/Configurations/ → EF Core
+- src/{project_namespace}.Domain/Business/ -> Entity structure + folder hierarchy
+- src/{project_namespace}.Application/Business/ -> DTOs + service interfaces
+- src/{project_namespace}.Application/Common/Interfaces/ -> Service contracts
+- src/{project_namespace}.Infrastructure/Persistence/Configurations/ -> EF Core configs (subfolder per module)
+- src/{project_namespace}.Infrastructure/Services/ -> Service implementations (subfolder per module)
+- src/{project_namespace}.Infrastructure/Persistence/Seeding/Data/ -> SeedData patterns
+
+SEED DATA (CRITICAL):
+- NavigationModuleConfiguration.cs -> How modules are seeded (HasData)
+- NavigationTranslationConfiguration.cs -> How translations are seeded (4 languages)
+- PermissionConfiguration.cs -> How permissions are seeded (HasData)
+- RolePermissionConfiguration.cs -> How role-permission mappings are seeded
 
 FRONTEND:
-- web/smartstack-web/src/pages/business/ → Existing pages
-- web/smartstack-web/src/components/ → Reusable components
-- web/smartstack-web/src/services/api/ → API calls
+- web/src/pages/business/ -> Existing pages
+- web/src/components/ -> Reusable components
+- web/src/services/api/ -> API calls
 ```
 
 ## 3. FILES TO CREATE
 
-### 3.1 Backend
-
-| File | Template | Description |
-|------|----------|-------------|
-| `Domain/Entities/{Entity}.cs` | Domain Entity | Properties + rules |
-| `Application/Features/{Module}/` | CQRS | MediatR handlers |
-| `Infrastructure/.../Configurations/` | EF Core | Config + HasData |
-| `Api/Controllers/Business/` | Controller | REST endpoints |
+> **Source:** `feature.handoff.filesToCreate[]` in feature.json
 
-### 3.2 Frontend
+### 3.1 Backend
 
-| File | Template | Description |
-|------|----------|-------------|
-| `pages/business/{app}/{module}/` | React Page | List + detail |
-| `services/api/{module}Api.ts` | API Service | Axios calls |
-| `i18n/locales/{lang}/{module}.json` | Translations | FR, EN, IT, DE |
+| File | Path Pattern | Description |
+|------|-------------|-------------|
+| Domain Entity | `Domain/Business/{Application}/{Module}/{Entity}.cs` | BaseEntity + IAuditableEntity |
+| Service Interface | `Application/Common/Interfaces/I{Entity}Service.cs` | Service contract |
+| DTOs | `Application/Business/{Application}/{Module}/DTOs/{Entity}Dto.cs` | Response, Create, Update records |
+| Mapping | `Application/Business/{Application}/{Module}/DTOs/{Entity}MappingExtensions.cs` | Entity <-> DTO mapping |
+| Permission Constants | `Application/Business/{Application}/{Module}/Permissions.cs` | Compile-time constants |
+| EF Configuration | `Infrastructure/Persistence/Configurations/{Module}/{Entity}Configuration.cs` | Table + indexes + HasData |
+| Service Implementation | `Infrastructure/Services/{Module}/{Entity}Service.cs` | Business logic |
+| Controller | `Api/Controllers/Business/{Application}/{Module}Controller.cs` | NavRoute + RequirePermission |
+
+### 3.2 SeedData Core (CRITICAL -- without these, module is invisible and returns 403)
+
+> **5 mandatory files** for every new module (4 EF Core HasData + 1 Application code):
+
+| # | File | Layer | Content |
+|---|------|-------|---------|
+| 1 | `NavigationModuleConfiguration.cs` | Infrastructure (HasData) | Module entry in `nav_Modules` |
+| 2 | `NavigationTranslationConfiguration.cs` | Infrastructure (HasData) | 4 translations (fr, en, it, de) per nav entity |
+| 3 | `PermissionConfiguration.cs` | Infrastructure (HasData) | Wildcard + CRUD permissions in `nav_Permissions` |
+| 4 | `Permissions.cs` | Application (code) | Compile-time constants for `[RequirePermission]` |
+| 5 | `RolePermissionConfiguration.cs` | Infrastructure (HasData) | Role->Permission for {App} Admin, {App} Manager, {App} Contributor, {App} Viewer |
+
+### 3.3 Frontend
+
+| File | Path Pattern | Description |
+|------|-------------|-------------|
+| Main Page | `pages/business/{app}/{module}/page.tsx` | List + actions |
+| Components | `components/business/{module}/` | Entity-specific components |
+| API Service | `services/api/{module}Api.ts` | Typed Axios calls |
+| Translations | `i18n/locales/{lang}/{module}.json` | FR, EN, IT, DE |
 
 ## 4. DETAILED SPECIFICATIONS
 
+> **Source:** Read from feature.json sections: `analysis.entities[]`, `specification.apiEndpoints[]`, `analysis.businessRules[]`, `specification.navigation`, `specification.permissionMatrix`
+
 ### 4.1 Entity
 
-| Attribute | Description | Required | Rules |
-|-----------|-------------|----------|-------|
-| Id | Unique identifier | Yes | GUID |
-| {attr} | {description} | {Yes/No} | {validation} |
+**Base class:** `BaseEntity` + `IAuditableEntity`
+**Table name:** `{prefix}_{EntityPlural}` in schema `extensions`
+**Schema:** `extensions` for business entities, `core` for system entities (navigation, permissions)
+> DO NOT add Id, TenantId, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy -- these are automatic via BaseEntity + IAuditableEntity.
+
+Attributes from: `feature.analysis.entities[].attributes[]`
 
 ### 4.2 API Endpoints
 
-| Endpoint | Method | Permission | Body | Response |
-|----------|--------|------------|------|----------|
-| `/api/business/{module}` | GET | `.read` | - | List |
-| `/api/business/{module}` | POST | `.create` | CreateDto | 201 |
-| `/api/business/{module}/{id}` | GET | `.read` | - | Entity |
-| `/api/business/{module}/{id}` | PUT | `.update` | UpdateDto | 200 |
-| `/api/business/{module}/{id}` | DELETE | `.delete` | - | 204 |
+From: `feature.specification.apiEndpoints[]`
 
-### 4.3 Business Rules → Code
+### 4.3 Business Rules -> Code
+
+From: `feature.handoff.brToCodeMapping[]`
 
 | BR-ID | Rule | Implementation |
 |-------|------|----------------|
-| BR-001 | {rule} | {where to implement} |
+| {id} | {rule from analysis.businessRules[]} | {implementation from handoff.brToCodeMapping[]} |
+
+### 4.4 SeedData Specifications
+
+From: `feature.specification.navigation` and `feature.specification.permissionMatrix`
 
 ## 5. REQUIRED TESTS
 
@@ -108,13 +144,29 @@ FRONTEND:
 
 ## 6. POST-IMPLEMENTATION CHECKLIST
 
+**Build & Tests:**
 - [ ] Backend build OK
 - [ ] Frontend build OK
 - [ ] Tests passing
-- [ ] EF Core migration created
-- [ ] Permissions in PermissionConfiguration.cs
+
+**Folder Conventions:**
+- [ ] Domain entities in `Domain/Business/{Application}/{Module}/`
+- [ ] Application DTOs in `Application/Business/{Application}/{Module}/DTOs/`
+- [ ] Infrastructure configs in `Configurations/{Module}/`
+- [ ] Infrastructure services in `Services/{Module}/`
+- [ ] Controller in `Controllers/Business/{Application}/`
+
+**SeedData Core (CRITICAL):**
+- [ ] Navigation module entry (HasData in NavigationModuleConfiguration.cs)
+- [ ] Navigation translations (4 languages in NavigationTranslationConfiguration.cs)
+- [ ] Permissions (HasData in PermissionConfiguration.cs: wildcard + CRUD)
+- [ ] Permission constants (Permissions.cs in Application layer)
+- [ ] Role-Permission assignments (HasData in RolePermissionConfiguration.cs: 4 roles)
+- [ ] EF Core migration created (includes all HasData seeds)
+
+**Frontend & i18n:**
 - [ ] i18n complete (4 languages)
-- [ ] Documentation: `/business-analyse:6-doc-html {FEAT-XXX}`
+- [ ] Nested routes (NOT flat)
 
 ---
 

package/templates/skills/controller/templates.md

@@ -1461,8 +1461,90 @@ public record BulkUpdate{Entity}Request(
   □ EF Core Migration created
   □ Migration applied
 
+□ API Versioning (if applicable)
+  □ See API Versioning section below
+
 □ Correct Permission Level
   □ Module (Level 3) - For main CRUD
   □ Section (Level 4) - If sub-pages with different permissions
   □ Resource (Level 5) - If sub-resources with distinct permissions
 ```
+
+---
+
+## API Versioning
+
+**SmartStack convention:** Header-based versioning using `Asp.Versioning.Mvc`.
+
+### Setup
+
+```csharp
+// Program.cs
+builder.Services.AddApiVersioning(options =>
+{
+    options.DefaultApiVersion = new ApiVersion(1, 0);
+    options.AssumeDefaultVersionWhenUnspecified = true;
+    options.ReportApiVersions = true; // Adds api-supported-versions header
+    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
+})
+.AddApiExplorer(options =>
+{
+    options.GroupNameFormat = "'v'VVV";
+    options.SubstituteApiVersionInUrl = true;
+});
+```
+
+### Controller Usage
+
+```csharp
+// v1 - Default (no attribute needed if only one version exists)
+[ApiController]
+[ApiVersion("1.0")]
+[NavRoute("business.crm.contacts")]
+public class ContactsController : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.Business.Crm.Contacts.Read)]
+    public async Task<ActionResult<PagedResult<ContactDto>>> GetAll(...) { ... }
+}
+
+// v2 - Breaking changes only
+[ApiController]
+[ApiVersion("2.0")]
+[NavRoute("business.crm.contacts")]
+public class ContactsV2Controller : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.Business.Crm.Contacts.Read)]
+    public async Task<ActionResult<PagedResult<ContactV2Dto>>> GetAll(...) { ... }
+}
+```
+
+### Deprecation
+
+```csharp
+[ApiVersion("1.0", Deprecated = true)] // Adds api-deprecated-versions header
+[ApiVersion("2.0")]
+public class ContactsController : ControllerBase
+{
+    [HttpGet]
+    [MapToApiVersion("1.0")]
+    public async Task<ActionResult<PagedResult<ContactDto>>> GetAllV1(...) { ... }
+
+    [HttpGet]
+    [MapToApiVersion("2.0")]
+    public async Task<ActionResult<PagedResult<ContactV2Dto>>> GetAllV2(...) { ... }
+}
+```
+
+### SmartStack Versioning Rules
+
+| Rule | Detail |
+|------|--------|
+| Default version | `1.0` (assumed when no header sent) |
+| Version header | `api-version: 2.0` |
+| When to version | Breaking changes only (field removal, type change, behavior change) |
+| Non-breaking changes | Add to existing version (new fields, new endpoints) |
+| Naming | `V2Controller` suffix or `[MapToApiVersion]` in same controller |
+| Deprecation | Mark old version deprecated, maintain for 2 releases minimum |
+| Documentation | Both versions documented via `[ProducesResponseType]` |

package/templates/skills/efcore/references/zero-downtime-patterns.md

@@ -0,0 +1,227 @@
+<overview>
+Zero-downtime migration patterns for EF Core. Use when a migration contains destructive operations (column rename, type change, column drop) that could cause downtime during deployment.
+
+These patterns apply to production deployments where the application runs continuously. For development environments, standard migrations are sufficient.
+</overview>
+
+<when_to_use>
+## When These Patterns Apply
+
+**Destructive operations requiring zero-downtime strategy:**
+- `RenameColumn` / `RenameTable`
+- `DropColumn` / `DropTable`
+- `AlterColumn` (type change, nullability change)
+
+**Safe operations (no special handling needed):**
+- `AddColumn` (nullable or with default value)
+- `CreateTable`
+- `CreateIndex`
+- `AddForeignKey`
+</when_to_use>
+
+<column_rename>
+## Pattern 1: Column Rename (5 phases)
+
+A column rename cannot be done atomically without downtime. Use a phased approach across multiple deployments.
+
+### Phase 1 - Add New Column (Migration 1)
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.AddColumn<string>(
+        name: "FullName",
+        table: "auth_users",
+        schema: "core",
+        type: "nvarchar(256)",
+        nullable: true); // Must be nullable initially
+
+    // Backfill existing data
+    migrationBuilder.Sql(
+        "UPDATE core.auth_users SET FullName = DisplayName WHERE FullName IS NULL");
+}
+
+protected override void Down(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.DropColumn(name: "FullName", table: "auth_users", schema: "core");
+}
+```
+
+### Phase 2 - Dual-Write Code (Application deployment)
+```csharp
+// Entity writes to BOTH columns during transition
+public void UpdateName(string name)
+{
+    DisplayName = name;  // Old column
+    FullName = name;     // New column
+}
+```
+
+### Phase 3 - Backfill Remaining Data (Migration 2, optional)
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    // Catch any rows missed during dual-write transition
+    migrationBuilder.Sql(
+        "UPDATE core.auth_users SET FullName = DisplayName WHERE FullName IS NULL");
+
+    // Make new column non-nullable
+    migrationBuilder.AlterColumn<string>(
+        name: "FullName",
+        table: "auth_users",
+        schema: "core",
+        type: "nvarchar(256)",
+        nullable: false,
+        defaultValue: "");
+}
+```
+
+### Phase 4 - Switch Reads (Application deployment)
+```csharp
+// Entity now reads from new column only
+public string Name => FullName;
+```
+
+### Phase 5 - Drop Old Column (Migration 3)
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.DropColumn(name: "DisplayName", table: "auth_users", schema: "core");
+}
+
+protected override void Down(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.AddColumn<string>(
+        name: "DisplayName",
+        table: "auth_users",
+        schema: "core",
+        type: "nvarchar(256)",
+        nullable: false,
+        defaultValue: "");
+
+    migrationBuilder.Sql(
+        "UPDATE core.auth_users SET DisplayName = FullName");
+}
+```
+</column_rename>
+
+<column_type_change>
+## Pattern 2: Column Type Change (4 phases)
+
+Changing a column type (e.g., `int` to `string`, `string` to `decimal`) follows the same dual-column approach.
+
+### Phase 1 - Add New Typed Column
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.AddColumn<decimal>(
+        name: "PriceDecimal",
+        table: "extensions_products",
+        schema: "extensions",
+        type: "decimal(18,2)",
+        nullable: true);
+
+    migrationBuilder.Sql(
+        "UPDATE extensions.extensions_products SET PriceDecimal = CAST(Price AS decimal(18,2))");
+}
+```
+
+### Phase 2 - Dual-Write in Code
+### Phase 3 - Make Non-Nullable + Switch Reads
+### Phase 4 - Drop Old Column
+
+Same phased pattern as column rename.
+</column_type_change>
+
+<large_table_operations>
+## Pattern 3: Large Table Backfill
+
+For tables with millions of rows, batch the backfill to avoid lock escalation.
+
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.AddColumn<string>(
+        name: "NormalizedEmail",
+        table: "auth_users",
+        schema: "core",
+        type: "nvarchar(256)",
+        nullable: true);
+
+    // Batched backfill to avoid table locks
+    migrationBuilder.Sql(@"
+        DECLARE @BatchSize INT = 5000;
+        DECLARE @RowsAffected INT = 1;
+
+        WHILE @RowsAffected > 0
+        BEGIN
+            UPDATE TOP (@BatchSize) core.auth_users
+            SET NormalizedEmail = UPPER(Email)
+            WHERE NormalizedEmail IS NULL;
+
+            SET @RowsAffected = @@ROWCOUNT;
+        END
+    ");
+}
+```
+
+**Rules:**
+- Batch size: 1,000-10,000 rows depending on table width
+- Always include a `WHERE` clause to avoid re-processing
+- Monitor transaction log growth during execution
+- Run during low-traffic windows if possible
+</large_table_operations>
+
+<rollback_strategy>
+## Rollback Strategies
+
+### Migration Down() Method
+Every migration MUST have a functional `Down()` method for rollback:
+
+```csharp
+protected override void Down(MigrationBuilder migrationBuilder)
+{
+    // Reverse the operation
+    migrationBuilder.DropColumn(name: "NewColumn", table: "auth_users", schema: "core");
+}
+```
+
+### Rollback Command
+```bash
+# Rollback to specific migration
+dotnet ef database update {PreviousMigrationName} \
+  --context $DBCONTEXT \
+  --project $INFRA_PROJECT \
+  --startup-project $STARTUP_PROJECT
+```
+
+### Pre-Deployment Checklist
+- [ ] `Down()` method tested locally
+- [ ] Database backup taken before deployment
+- [ ] Application compatible with both old and new schema (dual-write phase)
+- [ ] Rollback procedure documented in deployment notes
+- [ ] Monitoring alerts configured for error spike
+</rollback_strategy>
+
+<decision_guide>
+## Decision Guide
+
+| Operation | Risk | Strategy |
+|-----------|------|----------|
+| Add nullable column | Low | Standard migration |
+| Add column with default | Low | Standard migration |
+| Create table | Low | Standard migration |
+| Create index | Medium | `CREATE INDEX CONCURRENTLY` if supported |
+| Rename column | High | 5-phase pattern |
+| Change column type | High | 4-phase pattern |
+| Drop column | High | Verify no reads, then drop |
+| Drop table | High | Verify no references, then drop |
+| Make column non-nullable | Medium | Ensure no NULL values exist first |
+
+**Rule of thumb:** If the operation would cause a `SqlException` on running code, use a phased approach.
+</decision_guide>
+
+<sources>
+- EF Core Migrations documentation
+- Zero-Downtime Deployments with EF Core (Microsoft patterns)
+- Blue-Green Deployment pattern (Martin Fowler)
+</sources>

package/templates/skills/efcore/steps/migration/step-03-validate.md

@@ -51,6 +51,25 @@ echo "  Tables:      $UP_TABLES"
 echo "  Columns:     $UP_COLUMNS"
 echo "  Indexes:     $UP_INDEXES"
 echo "  Foreign Keys:$UP_FOREIGN"
+
+# Detect destructive operations
+DROP_COL=$(grep -c "DropColumn" "$MIGRATION_FILE" || echo "0")
+RENAME_COL=$(grep -c "RenameColumn" "$MIGRATION_FILE" || echo "0")
+ALTER_COL=$(grep -c "AlterColumn" "$MIGRATION_FILE" || echo "0")
+DROP_TABLE=$(grep -c "DropTable" "$MIGRATION_FILE" || echo "0")
+DESTRUCTIVE=$((DROP_COL + RENAME_COL + ALTER_COL + DROP_TABLE))
+
+if [ "$DESTRUCTIVE" -gt 0 ]; then
+  echo ""
+  echo "WARNING: Destructive operations detected:"
+  [ "$DROP_COL" -gt 0 ] && echo "  DropColumn:   $DROP_COL"
+  [ "$RENAME_COL" -gt 0 ] && echo "  RenameColumn: $RENAME_COL"
+  [ "$ALTER_COL" -gt 0 ] && echo "  AlterColumn:  $ALTER_COL"
+  [ "$DROP_TABLE" -gt 0 ] && echo "  DropTable:    $DROP_TABLE"
+  echo ""
+  echo "For production deployments, consider zero-downtime migration patterns."
+  echo "See: references/zero-downtime-patterns.md"
+fi
 ```
 
 ### 3. Ask User to Validate

package/templates/skills/review-code/SKILL.md

@@ -151,7 +151,8 @@ The MCP tool returns a structured report. Display it as-is or integrate key find
 - Authorization checks on every endpoint
 - No `eval()`, `exec()`, dangerous functions
 
-See [references/security-checklist.md](references/security-checklist.md) for OWASP Top 10 patterns.
+See [references/security-checklist.md](references/security-checklist.md) for OWASP Top 10 patterns (web application vulnerabilities).
+See [references/owasp-api-top10.md](references/owasp-api-top10.md) for OWASP API Security Top 10 (API-specific threats: BOLA, mass assignment, SSRF, resource consumption).
 </category>
 
 <category name="logic" priority="critical">
@@ -322,7 +323,8 @@ A good code review:
 <reference_guides>
 For detailed guidance and patterns:
 
-- **`references/security-checklist.md`** - OWASP Top 10, authentication patterns, input validation, common vulnerabilities
+- **`references/security-checklist.md`** - OWASP Top 10, authentication patterns, input validation, rate limiting, security headers
+- **`references/owasp-api-top10.md`** - OWASP API Security Top 10: BOLA, mass assignment, SSRF, resource consumption, SmartStack-specific detection patterns
 - **`references/clean-code-principles.md`** - SOLID principles, naming conventions, function design, code smell detection
 - **`references/feedback-patterns.md`** - Valuable vs wasteful feedback patterns, communication strategies, priority labeling
 - **`references/code-quality-metrics.md`** - Complexity calculations, maintainability index, measurement techniques