@atlashub/smartstack-cli 3.39.0 → 3.41.0

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

@@ -1,177 +1,177 @@
-# IClientSeedDataProvider Template
-
-> Referenced from `steps/step-03b-provider.md` — C# template for client project seed data providers.
-
----
-
-## Provider Class Template
-
-**Location:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
-
-Where `{AppPascalName}` is derived from the application code (e.g., `free-bike` → `FreeBike`).
-
-```csharp
-using Microsoft.EntityFrameworkCore;
-using SmartStack.Application.Common.Interfaces;
-using SmartStack.Domain.Navigation;
-using SmartStack.Domain.Platform.Administration.Roles;
-
-namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
-
-/// <summary>
-/// Seeds {AppLabel} navigation, roles, permissions, and role-permission data
-/// into the SmartStack Core schema at application startup.
-/// Implements <see cref="IClientSeedDataProvider"/> for runtime seeding
-/// (no Core migrations required).
-/// </summary>
-public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
-{
-    public int Order => 100;
-
-    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // --- Application (idempotent — reuse if already exists) ---
-        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
-        var existingApp = await context.NavigationApplications
-            .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
-
-        NavigationApplication app;
-        if (existingApp != null)
-        {
-            app = existingApp; // Reuse existing for module seeding below
-        }
-        else
-        {
-            app = NavigationApplication.Create(
-                appEntry.Code, appEntry.Label,
-                appEntry.Description, appEntry.Icon, appEntry.IconType,
-                appEntry.Route, appEntry.DisplayOrder);
-            context.NavigationApplications.Add(app);
-            await ((DbContext)context).SaveChangesAsync(ct);
-
-            // Application translations (only when creating new application)
-            foreach (var t in NavigationApplicationSeedData.GetTranslationEntries())
-            {
-                context.NavigationTranslations.Add(
-                    NavigationTranslation.Create(t.EntityType, t.EntityId, t.LanguageCode, t.Label, t.Description));
-            }
-            await ((DbContext)context).SaveChangesAsync(ct);
-        }
-
-        // --- Modules (idempotent per-module) ---
-        // var mod1Exists = await context.NavigationModules.AnyAsync(
-        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
-        // if (!mod1Exists) { context.NavigationModules.Add(NavigationModule.Create(...)); }
-        // Repeat per module...
-        await ((DbContext)context).SaveChangesAsync(ct);
-
-        // Resolve module entities
-        // var mod1Entity = await context.NavigationModules.FirstAsync(
-        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
-
-        // --- Module translations (IDEMPOTENT — check before inserting) ---
-        // CRITICAL: nav_Translations has unique index IX_nav_Translations_EntityType_EntityId_LanguageCode
-        // Always guard with AnyAsync to prevent duplicate key errors on re-runs.
-        // if (!await context.NavigationTranslations.AnyAsync(
-        //     t => t.EntityId == {Module}NavigationSeedData.{Module}ModuleId
-        //          && t.EntityType == NavigationEntityType.Module, ct))
-        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries()) { ... } }
-        await ((DbContext)context).SaveChangesAsync(ct);
-
-        // --- Sections (idempotent per-section) ---
-        // Check each section before inserting: AnyAsync(s => s.Code == secEntry.Code && s.ModuleId == ...)
-
-        // --- Section translations (IDEMPOTENT — same guard pattern as module translations) ---
-        // if (!await context.NavigationTranslations.AnyAsync(
-        //     t => t.EntityId == secEntry.Id && t.EntityType == NavigationEntityType.Section, ct))
-
-        // --- Resources (idempotent — use ACTUAL section IDs from DB) ---
-        // CRITICAL: NavigationSection.Create() generates its own ID. Deterministic seed GUIDs
-        // do NOT match actual SectionId in DB → FK_nav_Resources_nav_Sections_SectionId violation.
-        // MUST query actual section: var actualSection = await context.NavigationSections
-        //     .FirstAsync(s => s.Code == secEntry.Code && s.ModuleId == modEntity.Id, ct);
-        // Then use actualSection.Id (NOT secEntry.Id) for NavigationResource.Create() and AnyAsync
-    }
-
-    public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // Check idempotence
-        var applicationId = ApplicationRolesSeedData.ApplicationId;
-        var exists = await context.Roles
-            .AnyAsync(r => r.ApplicationId == applicationId, ct);
-        if (exists) return;
-
-        // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
-        // Use data from ApplicationRolesSeedData.cs
-        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);
-    }
-
-    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // Check idempotence
-        var exists = await context.Permissions
-            .AnyAsync(p => p.Path == "{full_path}.*", ct);
-        if (exists) return;
-
-        // Retrieve modules by Code for FK resolution
-        // Use data from {Module}PermissionSeedData.cs
-        // Create via Permission.CreateForModule(...) and Permission.CreateWildcard(...)
-        // ...
-        await ((DbContext)context).SaveChangesAsync(ct);
-    }
-
-    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
-    {
-        // Check idempotence
-        var exists = await context.RolePermissions
-            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{full_path}."), ct);
-        if (exists) return;
-
-        // Retrieve existing roles and created permissions
-        // Use data from {Module}RolePermissionSeedData.cs
-        // Create via RolePermission.Create(roleId, permissionId, "system")
-        // ...
-        await ((DbContext)context).SaveChangesAsync(ct);
-    }
-
-    // Private helper methods fed by SeedData classes
-    // ...
-}
-```
-
----
-
-## DI Registration
-
-Modify `Infrastructure/DependencyInjection.cs` of the client project:
-
-```csharp
-// Add using:
-using SmartStack.Application.Common.Interfaces;
-
-// In the registration method:
-services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
-```
-
----
-
-## Critical Rules
-
-1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
-2. **Idempotence**: Each Seed method checks existence before inserting. **Translations require explicit `AnyAsync` guard** — unique index `IX_nav_Translations_EntityType_EntityId_LanguageCode` causes crashes on duplicate inserts
-3. **Translation guard pattern**: `if (!await context.NavigationTranslations.AnyAsync(t => t.EntityId == {id} && t.EntityType == ..., ct))` — MANDATORY before every translation batch insert
-4. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
-4. **Execution order**: `SeedRolesAsync()` MUST be called BEFORE `SeedRolePermissionsAsync()` (roles must exist before mapping)
-5. **Deterministic GUIDs**: Use IDs from SeedData classes (not `Guid.NewGuid()`)
-6. **Resolve FK by Code**: Parent modules and roles are found by `Code`, not hardcoded GUID
-7. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence
+# IClientSeedDataProvider Template
+
+> Referenced from `steps/step-03b-provider.md` — C# template for client project seed data providers.
+
+---
+
+## Provider Class Template
+
+**Location:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
+
+Where `{AppPascalName}` is derived from the application code (e.g., `free-bike` → `FreeBike`).
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using SmartStack.Application.Common.Interfaces;
+using SmartStack.Domain.Navigation;
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
+
+/// <summary>
+/// Seeds {AppLabel} navigation, roles, permissions, and role-permission data
+/// into the SmartStack Core schema at application startup.
+/// Implements <see cref="IClientSeedDataProvider"/> for runtime seeding
+/// (no Core migrations required).
+/// </summary>
+public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
+{
+    public int Order => 100;
+
+    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // --- Application (idempotent — reuse if already exists) ---
+        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
+        var existingApp = await context.NavigationApplications
+            .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
+
+        NavigationApplication app;
+        if (existingApp != null)
+        {
+            app = existingApp; // Reuse existing for module seeding below
+        }
+        else
+        {
+            app = NavigationApplication.Create(
+                appEntry.Code, appEntry.Label,
+                appEntry.Description, appEntry.Icon, appEntry.IconType,
+                appEntry.Route, appEntry.DisplayOrder);
+            context.NavigationApplications.Add(app);
+            await ((DbContext)context).SaveChangesAsync(ct);
+
+            // Application translations (only when creating new application)
+            foreach (var t in NavigationApplicationSeedData.GetTranslationEntries())
+            {
+                context.NavigationTranslations.Add(
+                    NavigationTranslation.Create(t.EntityType, t.EntityId, t.LanguageCode, t.Label, t.Description));
+            }
+            await ((DbContext)context).SaveChangesAsync(ct);
+        }
+
+        // --- Modules (idempotent per-module) ---
+        // var mod1Exists = await context.NavigationModules.AnyAsync(
+        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
+        // if (!mod1Exists) { context.NavigationModules.Add(NavigationModule.Create(...)); }
+        // Repeat per module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // Resolve module entities
+        // var mod1Entity = await context.NavigationModules.FirstAsync(
+        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
+
+        // --- Module translations (IDEMPOTENT — check before inserting) ---
+        // CRITICAL: nav_Translations has unique index IX_nav_Translations_EntityType_EntityId_LanguageCode
+        // Always guard with AnyAsync to prevent duplicate key errors on re-runs.
+        // if (!await context.NavigationTranslations.AnyAsync(
+        //     t => t.EntityId == {Module}NavigationSeedData.{Module}ModuleId
+        //          && t.EntityType == NavigationEntityType.Module, ct))
+        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries()) { ... } }
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Sections (idempotent per-section) ---
+        // Check each section before inserting: AnyAsync(s => s.Code == secEntry.Code && s.ModuleId == ...)
+
+        // --- Section translations (IDEMPOTENT — same guard pattern as module translations) ---
+        // if (!await context.NavigationTranslations.AnyAsync(
+        //     t => t.EntityId == secEntry.Id && t.EntityType == NavigationEntityType.Section, ct))
+
+        // --- Resources (idempotent — use ACTUAL section IDs from DB) ---
+        // CRITICAL: NavigationSection.Create() generates its own ID. Deterministic seed GUIDs
+        // do NOT match actual SectionId in DB → FK_nav_Resources_nav_Sections_SectionId violation.
+        // MUST query actual section: var actualSection = await context.NavigationSections
+        //     .FirstAsync(s => s.Code == secEntry.Code && s.ModuleId == modEntity.Id, ct);
+        // Then use actualSection.Id (NOT secEntry.Id) for NavigationResource.Create() and AnyAsync
+    }
+
+    public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var applicationId = ApplicationRolesSeedData.ApplicationId;
+        var exists = await context.Roles
+            .AnyAsync(r => r.ApplicationId == applicationId, ct);
+        if (exists) return;
+
+        // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
+        // Use data from ApplicationRolesSeedData.cs
+        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);
+    }
+
+    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.Permissions
+            .AnyAsync(p => p.Path == "{full_path}.*", ct);
+        if (exists) return;
+
+        // Retrieve modules by Code for FK resolution
+        // Use data from {Module}PermissionSeedData.cs
+        // Create via Permission.CreateForModule(...) and Permission.CreateWildcard(...)
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.RolePermissions
+            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{full_path}."), ct);
+        if (exists) return;
+
+        // Retrieve existing roles and created permissions
+        // Use data from {Module}RolePermissionSeedData.cs
+        // Create via RolePermission.Create(roleId, permissionId, "system")
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    // Private helper methods fed by SeedData classes
+    // ...
+}
+```
+
+---
+
+## DI Registration
+
+Modify `Infrastructure/DependencyInjection.cs` of the client project:
+
+```csharp
+// Add using:
+using SmartStack.Application.Common.Interfaces;
+
+// In the registration method:
+services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
+```
+
+---
+
+## Critical Rules
+
+1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
+2. **Idempotence**: Each Seed method checks existence before inserting. **Translations require explicit `AnyAsync` guard** — unique index `IX_nav_Translations_EntityType_EntityId_LanguageCode` causes crashes on duplicate inserts
+3. **Translation guard pattern**: `if (!await context.NavigationTranslations.AnyAsync(t => t.EntityId == {id} && t.EntityType == ..., ct))` — MANDATORY before every translation batch insert
+4. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
+4. **Execution order**: `SeedRolesAsync()` MUST be called BEFORE `SeedRolePermissionsAsync()` (roles must exist before mapping)
+5. **Deterministic GUIDs**: Use IDs from SeedData classes (not `Guid.NewGuid()`)
+6. **Resolve FK by Code**: Parent modules and roles are found by `Code`, not hardcoded GUID
+7. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence

package/templates/skills/application/references/roles-client-project-handling.md

@@ -1,55 +1,55 @@
-# Step 3: Client Project Handling (seeding_strategy = "provider")
-
-> Referenced from `steps/step-03-roles.md` — Specific handling for client projects.
-
----
-
-## ApplicationRolesSeedData.cs (ONCE per application)
-
-**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
-
-**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
-
-**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
-
-See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
-
-**Key requirements:**
-- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
-- 4 roles: Admin, Manager, Contributor, Viewer
-- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
-- `ApplicationId` references the navigation application GUID
-- `IsSystem = false` (application-scoped, not system roles)
-
-**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
-
----
-
-## {Module}RolePermissionSeedData.cs (PER module)
-
-**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
-
-**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
-
-Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
-These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
-
----
-
-## Default Role Mapping Table
-
-Based on navigation application prefix:
-
-| Application prefix | PlatformAdmin | TenantAdmin | StandardUser |
-|---------|---------------|-------------|--------------|
-| `administration.*` | Full CRUD | Read only | None |
-| `*` (business apps) | Full CRUD | Full CRUD | Read only |
-| `myspace.*` | None | Full CRUD | Full CRUD |
-
----
-
-## Summary
-
-After creating both files:
-- Proceed to step-03b-provider.md (which will skip for core projects)
-- The provider will consume these SeedData files to seed roles and permissions at runtime
+# Step 3: Client Project Handling (seeding_strategy = "provider")
+
+> Referenced from `steps/step-03-roles.md` — Specific handling for client projects.
+
+---
+
+## ApplicationRolesSeedData.cs (ONCE per application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
+
+**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
+
+See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
+
+**Key requirements:**
+- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
+- 4 roles: Admin, Manager, Contributor, Viewer
+- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
+- `ApplicationId` references the navigation application GUID
+- `IsSystem = false` (application-scoped, not system roles)
+
+**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
+
+---
+
+## {Module}RolePermissionSeedData.cs (PER module)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
+
+Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
+These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
+
+---
+
+## Default Role Mapping Table
+
+Based on navigation application prefix:
+
+| Application prefix | PlatformAdmin | TenantAdmin | StandardUser |
+|---------|---------------|-------------|--------------|
+| `administration.*` | Full CRUD | Read only | None |
+| `*` (business apps) | Full CRUD | Full CRUD | Read only |
+| `myspace.*` | None | Full CRUD | Full CRUD |
+
+---
+
+## Summary
+
+After creating both files:
+- Proceed to step-03b-provider.md (which will skip for core projects)
+- The provider will consume these SeedData files to seed roles and permissions at runtime