@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/application/references/application-roles-template.md

@@ -1,227 +1,227 @@
-# Application Roles Seed Data Template
-
-> Referenced from `core-seed-data.md` and `step-03-roles.md` — C# template for application-scoped roles in client projects.
-
----
-
-## Problem Statement
-
-When using `IClientSeedDataProvider` (client projects with `seeding_strategy = "provider"`), role-permission mappings reference roles by their `Code`:
-
-```csharp
-var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);  // "admin", "manager", "contributor", "viewer"
-```
-
-**However**, the current templates do NOT create these application-scoped roles. They assume:
-- System roles (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser) exist in Core
-- Application-scoped roles (Admin, Manager, Contributor, Viewer) already exist with valid `Code` values
-
-**Result:** Role-permission mappings fail silently when `role == null`.
-
----
-
-## Solution: Application Roles Seed Data
-
-Create application-scoped roles with deterministic GUIDs and valid `Code` values.
-
----
-
-## File Location
-
-**Path:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
-
-This file should be created **ONCE per application** (not per module).
-
----
-
-## Template
-
-```csharp
-using SmartStack.Domain.Platform.Administration.Roles;
-
-namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
-
-/// <summary>
-/// Application-scoped role seed data for {AppLabel}.
-/// Defines the 4 standard application roles: Admin, Manager, Contributor, Viewer.
-/// Consumed by IClientSeedDataProvider at application startup.
-/// </summary>
-public static class ApplicationRolesSeedData
-{
-    // Deterministic GUIDs for application roles
-    // Generated from: "role-{applicationId}-{roleType}"
-    public static readonly Guid ApplicationId = NavigationApplicationSeedData.ApplicationId;
-
-    public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
-    public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
-    public static readonly Guid ContributorRoleId = GenerateRoleGuid("contributor");
-    public static readonly Guid ViewerRoleId = GenerateRoleGuid("viewer");
-
-    /// <summary>
-    /// Returns application-scoped role entries for seeding into core.auth_Roles.
-    /// </summary>
-    public static IEnumerable<ApplicationRoleSeedEntry> GetRoleEntries()
-    {
-        yield return new ApplicationRoleSeedEntry
-        {
-            Id = AdminRoleId,
-            Code = "admin",
-            Name = "{AppLabel} Admin",
-            Description = "Full administrative access to {AppLabel}",
-            ApplicationId = ApplicationId,
-            IsSystem = false,
-            IsActive = true,
-            DisplayOrder = 1
-        };
-
-        yield return new ApplicationRoleSeedEntry
-        {
-            Id = ManagerRoleId,
-            Code = "manager",
-            Name = "{AppLabel} Manager",
-            Description = "Management access to {AppLabel} (Create, Read, Update)",
-            ApplicationId = ApplicationId,
-            IsSystem = false,
-            IsActive = true,
-            DisplayOrder = 2
-        };
-
-        yield return new ApplicationRoleSeedEntry
-        {
-            Id = ContributorRoleId,
-            Code = "contributor",
-            Name = "{AppLabel} Contributor",
-            Description = "Contributor access to {AppLabel} (Create, Read)",
-            ApplicationId = ApplicationId,
-            IsSystem = false,
-            IsActive = true,
-            DisplayOrder = 3
-        };
-
-        yield return new ApplicationRoleSeedEntry
-        {
-            Id = ViewerRoleId,
-            Code = "viewer",
-            Name = "{AppLabel} Viewer",
-            Description = "Read-only access to {AppLabel}",
-            ApplicationId = ApplicationId,
-            IsSystem = false,
-            IsActive = true,
-            DisplayOrder = 4
-        };
-    }
-
-    private static Guid GenerateRoleGuid(string roleType)
-    {
-        using var sha256 = System.Security.Cryptography.SHA256.Create();
-        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"role-{ApplicationId}-{roleType}"));
-        return new Guid(hash.Take(16).ToArray());
-    }
-}
-
-/// <summary>Seed entry DTO for application role.</summary>
-public class ApplicationRoleSeedEntry
-{
-    public Guid Id { get; init; }
-    public string Code { get; init; } = null!;
-    public string Name { get; init; } = null!;
-    public string Description { get; init; } = null!;
-    public Guid ApplicationId { get; init; }
-    public bool IsSystem { get; init; }
-    public bool IsActive { get; init; }
-    public int DisplayOrder { get; init; }
-}
-```
-
----
-
-## Placeholder Replacement
-
-| Placeholder | Description | Example |
-|-------------|-------------|---------|
-| `{BaseNamespace}` | Root namespace of the client project | `SmartStack.Modules.RessourcesHumaines` |
-| `{AppLabel}` | Human-readable application label (EN) | `Human Resources` |
-| `ApplicationId` | Deterministic GUID from `NavigationApplicationSeedData.ApplicationId` — NO placeholder needed | Auto-resolved |
-
----
-
-## Integration into IClientSeedDataProvider
-
-Add a new method `SeedRolesAsync()` to the provider:
-
-```csharp
-public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
-{
-    // Check idempotence
-    var exists = await context.Roles
-        .AnyAsync(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId, ct);
-    if (exists) return;
-
-    // Create application-scoped roles using factory method
-    foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
-    {
-        var role = Role.Create(
-            entry.Code,
-            entry.Name,
-            entry.Description,
-            entry.ApplicationId,
-            entry.IsSystem);
-
-        context.Roles.Add(role);
-    }
-
-    await ((DbContext)context).SaveChangesAsync(ct);
-}
-```
-
----
-
-## Execution Order in Provider
-
-**CRITICAL:** Roles must be created BEFORE role-permission mappings.
-
-```
-1. SeedNavigationAsync()   → Creates application + modules + translations
-2. SeedRolesAsync()         → Creates application-scoped roles (NEW)
-3. SeedPermissionsAsync()   → Creates permissions
-4. SeedRolePermissionsAsync() → Maps roles to permissions (now succeeds because roles exist)
-```
-
----
-
-## Verification Checklist
-
-Before marking the task as completed, verify:
-
-- [ ] `ApplicationRolesSeedData.cs` created in `Infrastructure/Persistence/Seeding/Data/`
-- [ ] Deterministic GUIDs used (NEVER `Guid.NewGuid()`)
-- [ ] 4 roles defined: Admin, Manager, Contributor, Viewer
-- [ ] Each role has a valid `Code` value ("admin", "manager", "contributor", "viewer")
-- [ ] Each role has `ApplicationId` set to the application GUID
-- [ ] `SeedRolesAsync()` method added to `IClientSeedDataProvider`
-- [ ] `SeedRolesAsync()` is idempotent (checks existence before inserting)
-- [ ] `Role.Create()` factory method used (NEVER `new Role()`)
-- [ ] `SaveChangesAsync()` called after role creation
-- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
-- [ ] `dotnet build` passes after generation
-
----
-
-## Notes
-
-- **Application ID source:** Read from the navigation application created in `SeedNavigationAsync()` or from `{AppPascal}NavigationSeedData.cs`
-- **Role factory method:** Use `Role.Create(code, name, description, applicationId, isSystem)` from SmartStack.Domain
-- **Code uniqueness:** Role codes must be unique within the application scope
-- **System roles:** These are NOT system roles (IsSystem = false) - they are application-scoped roles
-- **Tenant isolation:** Application-scoped roles are automatically tenant-isolated via the Core authorization system
-
----
-
-## Migration Impact
-
-**For existing projects without application roles:**
-1. Generate `ApplicationRolesSeedData.cs` using this template
-2. Add `SeedRolesAsync()` method to the existing `IClientSeedDataProvider`
-3. Update the provider's execution to call `SeedRolesAsync()` BEFORE `SeedRolePermissionsAsync()`
-4. Run the application - roles will be created on next startup
-5. Role-permission mappings will now succeed
+# Application Roles Seed Data Template
+
+> Referenced from `core-seed-data.md` and `step-03-roles.md` — C# template for application-scoped roles in client projects.
+
+---
+
+## Problem Statement
+
+When using `IClientSeedDataProvider` (client projects with `seeding_strategy = "provider"`), role-permission mappings reference roles by their `Code`:
+
+```csharp
+var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);  // "admin", "manager", "contributor", "viewer"
+```
+
+**However**, the current templates do NOT create these application-scoped roles. They assume:
+- System roles (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser) exist in Core
+- Application-scoped roles (Admin, Manager, Contributor, Viewer) already exist with valid `Code` values
+
+**Result:** Role-permission mappings fail silently when `role == null`.
+
+---
+
+## Solution: Application Roles Seed Data
+
+Create application-scoped roles with deterministic GUIDs and valid `Code` values.
+
+---
+
+## File Location
+
+**Path:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+This file should be created **ONCE per application** (not per module).
+
+---
+
+## Template
+
+```csharp
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+
+/// <summary>
+/// Application-scoped role seed data for {AppLabel}.
+/// Defines the 4 standard application roles: Admin, Manager, Contributor, Viewer.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class ApplicationRolesSeedData
+{
+    // Deterministic GUIDs for application roles
+    // Generated from: "role-{applicationId}-{roleType}"
+    public static readonly Guid ApplicationId = NavigationApplicationSeedData.ApplicationId;
+
+    public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
+    public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
+    public static readonly Guid ContributorRoleId = GenerateRoleGuid("contributor");
+    public static readonly Guid ViewerRoleId = GenerateRoleGuid("viewer");
+
+    /// <summary>
+    /// Returns application-scoped role entries for seeding into core.auth_Roles.
+    /// </summary>
+    public static IEnumerable<ApplicationRoleSeedEntry> GetRoleEntries()
+    {
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = AdminRoleId,
+            Code = "admin",
+            Name = "{AppLabel} Admin",
+            Description = "Full administrative access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 1
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ManagerRoleId,
+            Code = "manager",
+            Name = "{AppLabel} Manager",
+            Description = "Management access to {AppLabel} (Create, Read, Update)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 2
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ContributorRoleId,
+            Code = "contributor",
+            Name = "{AppLabel} Contributor",
+            Description = "Contributor access to {AppLabel} (Create, Read)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 3
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ViewerRoleId,
+            Code = "viewer",
+            Name = "{AppLabel} Viewer",
+            Description = "Read-only access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 4
+        };
+    }
+
+    private static Guid GenerateRoleGuid(string roleType)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"role-{ApplicationId}-{roleType}"));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+/// <summary>Seed entry DTO for application role.</summary>
+public class ApplicationRoleSeedEntry
+{
+    public Guid Id { get; init; }
+    public string Code { get; init; } = null!;
+    public string Name { get; init; } = null!;
+    public string Description { get; init; } = null!;
+    public Guid ApplicationId { get; init; }
+    public bool IsSystem { get; init; }
+    public bool IsActive { get; init; }
+    public int DisplayOrder { get; init; }
+}
+```
+
+---
+
+## Placeholder Replacement
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `{BaseNamespace}` | Root namespace of the client project | `SmartStack.Modules.RessourcesHumaines` |
+| `{AppLabel}` | Human-readable application label (EN) | `Human Resources` |
+| `ApplicationId` | Deterministic GUID from `NavigationApplicationSeedData.ApplicationId` — NO placeholder needed | Auto-resolved |
+
+---
+
+## Integration into IClientSeedDataProvider
+
+Add a new method `SeedRolesAsync()` to the provider:
+
+```csharp
+public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+{
+    // Check idempotence
+    var exists = await context.Roles
+        .AnyAsync(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId, ct);
+    if (exists) return;
+
+    // Create application-scoped roles using factory method
+    foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
+    {
+        var role = Role.Create(
+            entry.Code,
+            entry.Name,
+            entry.Description,
+            entry.ApplicationId,
+            entry.IsSystem);
+
+        context.Roles.Add(role);
+    }
+
+    await ((DbContext)context).SaveChangesAsync(ct);
+}
+```
+
+---
+
+## Execution Order in Provider
+
+**CRITICAL:** Roles must be created BEFORE role-permission mappings.
+
+```
+1. SeedNavigationAsync()   → Creates application + modules + translations
+2. SeedRolesAsync()         → Creates application-scoped roles (NEW)
+3. SeedPermissionsAsync()   → Creates permissions
+4. SeedRolePermissionsAsync() → Maps roles to permissions (now succeeds because roles exist)
+```
+
+---
+
+## Verification Checklist
+
+Before marking the task as completed, verify:
+
+- [ ] `ApplicationRolesSeedData.cs` created in `Infrastructure/Persistence/Seeding/Data/`
+- [ ] Deterministic GUIDs used (NEVER `Guid.NewGuid()`)
+- [ ] 4 roles defined: Admin, Manager, Contributor, Viewer
+- [ ] Each role has a valid `Code` value ("admin", "manager", "contributor", "viewer")
+- [ ] Each role has `ApplicationId` set to the application GUID
+- [ ] `SeedRolesAsync()` method added to `IClientSeedDataProvider`
+- [ ] `SeedRolesAsync()` is idempotent (checks existence before inserting)
+- [ ] `Role.Create()` factory method used (NEVER `new Role()`)
+- [ ] `SaveChangesAsync()` called after role creation
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
+- [ ] `dotnet build` passes after generation
+
+---
+
+## Notes
+
+- **Application ID source:** Read from the navigation application created in `SeedNavigationAsync()` or from `{AppPascal}NavigationSeedData.cs`
+- **Role factory method:** Use `Role.Create(code, name, description, applicationId, isSystem)` from SmartStack.Domain
+- **Code uniqueness:** Role codes must be unique within the application scope
+- **System roles:** These are NOT system roles (IsSystem = false) - they are application-scoped roles
+- **Tenant isolation:** Application-scoped roles are automatically tenant-isolated via the Core authorization system
+
+---
+
+## Migration Impact
+
+**For existing projects without application roles:**
+1. Generate `ApplicationRolesSeedData.cs` using this template
+2. Add `SeedRolesAsync()` method to the existing `IClientSeedDataProvider`
+3. Update the provider's execution to call `SeedRolesAsync()` BEFORE `SeedRolePermissionsAsync()`
+4. Run the application - roles will be created on next startup
+5. Role-permission mappings will now succeed

package/templates/skills/application/references/backend-controller-hierarchy.md

@@ -1,58 +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 **application** (matching SmartStack.app pattern):
-
-```
-Api/Controllers/
-├── Administration/            ← administration.*
-│   ├── {Module}/              ← Module sub-folder (e.g., AI/, Communications/, Tenants/)
-│   │   └── {EntityName}Controller.cs
-│   └── {EntityName}Controller.cs  ← Direct controllers (no module sub-folder)
-├── Support/                   ← support.*
-│   └── {EntityName}Controller.cs
-├── {ApplicationPascal}/       ← Other applications (e.g., Sales/, HumanResources/)
-│   └── {EntityName}Controller.cs
-├── MySpace/                   ← myspace.*
-│   └── {EntityName}Controller.cs
-└── {SharedControllers}.cs     ← Root-level (Auth, Config, Navigation, etc.)
-```
-
-## Application-to-Folder Mapping
-
-| NavRoute Application | Controller Folder | Example |
-|-----------------|-------------------|---------|
-| `administration` | `Administration` | `Controllers/Administration/TenantsController.cs` |
-| `administration.{module}` | `Administration/{Module}` | `Controllers/Administration/AI/AiPromptsController.cs` |
-| `support` | `Support` | `Controllers/Support/TicketsController.cs` |
-| `{application}` | `{ApplicationPascal}` | `Controllers/Sales/ProductsController.cs` |
-| `myspace` | `MySpace` | `Controllers/MySpace/PreferencesController.cs` |
-
-## Controller Attributes
-
-The generated controller uses NavRoute attribute:
-
-```csharp
-[NavRoute("{full_path}")]
-[ApiController]
-[Authorize]
-public class {EntityName}Controller : ControllerBase
-{
-    [HttpGet]
-    [RequirePermission(Permissions.{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 application folder
+# 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 **application** (matching SmartStack.app pattern):
+
+```
+Api/Controllers/
+├── Administration/            ← administration.*
+│   ├── {Module}/              ← Module sub-folder (e.g., AI/, Communications/, Tenants/)
+│   │   └── {EntityName}Controller.cs
+│   └── {EntityName}Controller.cs  ← Direct controllers (no module sub-folder)
+├── Support/                   ← support.*
+│   └── {EntityName}Controller.cs
+├── {ApplicationPascal}/       ← Other applications (e.g., Sales/, HumanResources/)
+│   └── {EntityName}Controller.cs
+├── MySpace/                   ← myspace.*
+│   └── {EntityName}Controller.cs
+└── {SharedControllers}.cs     ← Root-level (Auth, Config, Navigation, etc.)
+```
+
+## Application-to-Folder Mapping
+
+| NavRoute Application | Controller Folder | Example |
+|-----------------|-------------------|---------|
+| `administration` | `Administration` | `Controllers/Administration/TenantsController.cs` |
+| `administration.{module}` | `Administration/{Module}` | `Controllers/Administration/AI/AiPromptsController.cs` |
+| `support` | `Support` | `Controllers/Support/TicketsController.cs` |
+| `{application}` | `{ApplicationPascal}` | `Controllers/Sales/ProductsController.cs` |
+| `myspace` | `MySpace` | `Controllers/MySpace/PreferencesController.cs` |
+
+## Controller Attributes
+
+The generated controller uses NavRoute attribute:
+
+```csharp
+[NavRoute("{full_path}")]
+[ApiController]
+[Authorize]
+public class {EntityName}Controller : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.{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 application folder