@atlashub/smartstack-cli 3.4.1 → 3.6.0

package/templates/skills/ralph-loop/references/core-seed-data.md

@@ -0,0 +1,538 @@
+# Core Seed Data - Execution Reference
+
+> **Loaded by:** step-02-execute and step-04 compact loop
+> **Condition:** Infrastructure task involves core seed data or IClientSeedDataProvider
+> **Applies to:** Client projects only (seeding_strategy = "provider", ExtensionsDbContext)
+>
+> **Source of truth:** `/application` skill `templates-seed.md` (lines 608-916)
+
+---
+
+## 1. Parameter Extraction
+
+Extract navigation hierarchy from the task's `_seedDataMeta` (populated by guardrail 1e):
+
+```javascript
+const task = currentTask;
+const meta = task._seedDataMeta || task._providerMeta || {};
+const coreSeedData = meta.coreSeedData || {};
+
+// Navigation hierarchy
+const navModules = coreSeedData.navigationModules || coreSeedData.navigation || [];
+const permissions = coreSeedData.permissions || [];
+const rolePerms = coreSeedData.rolePermissions || [];
+
+// Derived context (from guardrail or PRD)
+const navRoute = meta.navRoute;         // e.g. "business.humanresources.projects"
+const contextCode = meta.contextCode;   // e.g. "business"
+const appCode = meta.appCode;           // e.g. "humanresources"
+const moduleCode = task.module;         // e.g. "projects"
+
+// If _seedDataMeta is absent, fallback to PRD source
+if (!navRoute) {
+  const prd = readJSON('.ralph/prd.json');
+  const navRoute = `${prd.source?.context || 'business'}.${prd.source?.application || prd.metadata?.module}.${task.module}`;
+}
+```
+
+**State variables after extraction:**
+
+| Variable | Example | Source |
+|----------|---------|--------|
+| `navRoute` | `business.humanresources.projects` | `_seedDataMeta.navRoute` |
+| `contextCode` | `business` | `_seedDataMeta.contextCode` |
+| `appCode` | `humanresources` | `_seedDataMeta.appCode` |
+| `moduleCode` | `projects` | `task.module` |
+| `navModules[]` | `[{code, label, icon, route, translations}]` | `coreSeedData.navigationModules` |
+| `permissions[]` | `[{path, action, description}]` | `coreSeedData.permissions` |
+| `rolePerms[]` | `[{role, permissions[]}]` | `coreSeedData.rolePermissions` |
+
+---
+
+## 2. NavigationModuleSeedData.cs
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/NavigationModuleSeedData.cs`
+
+### GUID Generation Rule
+
+```csharp
+// NEVER use Guid.NewGuid() — ALWAYS deterministic
+private static Guid GenerateDeterministicGuid(string seed)
+{
+    using var sha256 = System.Security.Cryptography.SHA256.Create();
+    var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(seed));
+    return new Guid(hash.Take(16).ToArray());
+}
+
+// Usage: GUIDs are derived from the navigation path
+public static readonly Guid ModuleId = GenerateDeterministicGuid("navigation-module-{navRoute}");
+// Example: GenerateDeterministicGuid("navigation-module-business.humanresources.projects")
+```
+
+### Template
+
+```csharp
+using SmartStack.Domain.Navigation;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{ModulePascal};
+
+/// <summary>
+/// Navigation seed data for {ModuleLabel} module.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class {ModulePascal}NavigationSeedData
+{
+    // Deterministic GUID for this module
+    public static readonly Guid {ModulePascal}ModuleId =
+        GenerateDeterministicGuid("navigation-module-{navRoute}");
+
+    /// <summary>
+    /// Returns navigation module entry for seeding into core.nav_Modules.
+    /// </summary>
+    public static NavigationModuleSeedEntry GetModuleEntry(Guid applicationId)
+    {
+        return new NavigationModuleSeedEntry
+        {
+            Id = {ModulePascal}ModuleId,
+            ApplicationId = applicationId,
+            Code = "{moduleCode}",
+            Label = "{label_en}",
+            Description = "{desc_en}",
+            Icon = "{icon}",              // Lucide React icon name
+            IconType = IconType.Lucide,
+            Route = "/{contextCode}/{appCode}/{moduleCode}",
+            DisplayOrder = {displayOrder},
+            IsActive = true
+        };
+    }
+
+    /// <summary>
+    /// Returns 4-language translations for this module.
+    /// </summary>
+    public static IEnumerable<NavigationTranslationSeedEntry> GetTranslationEntries()
+    {
+        var moduleId = {ModulePascal}ModuleId;
+        return new[]
+        {
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "fr",
+                Label = "{label_fr}",
+                Description = "{desc_fr}"
+            },
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "en",
+                Label = "{label_en}",
+                Description = "{desc_en}"
+            },
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "it",
+                Label = "{label_it}",
+                Description = "{desc_it}"
+            },
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "de",
+                Label = "{label_de}",
+                Description = "{desc_de}"
+            }
+        };
+    }
+
+    private static Guid GenerateDeterministicGuid(string seed)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(seed));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+/// <summary>Seed entry DTO for navigation module.</summary>
+public class NavigationModuleSeedEntry
+{
+    public Guid Id { get; init; }
+    public Guid ApplicationId { get; init; }
+    public string Code { get; init; } = null!;
+    public string Label { get; init; } = null!;
+    public string Description { get; init; } = null!;
+    public string Icon { get; init; } = null!;
+    public IconType IconType { get; init; }
+    public string Route { get; init; } = null!;
+    public int DisplayOrder { get; init; }
+    public bool IsActive { get; init; }
+}
+
+/// <summary>Seed entry DTO for navigation translation.</summary>
+public class NavigationTranslationSeedEntry
+{
+    public NavigationEntityType EntityType { get; init; }
+    public Guid EntityId { get; init; }
+    public string LanguageCode { get; init; } = null!;
+    public string Label { get; init; } = null!;
+    public string Description { get; init; } = null!;
+}
+```
+
+**Replace placeholders** with values from `navModules[]` and PRD `project` metadata.
+
+---
+
+## 3. PermissionsSeedData.cs — MCP-First
+
+### Step A: Call MCP (PRIMARY)
+
+```
+Tool: mcp__smartstack__generate_permissions
+Args:
+  navRoute: "{navRoute}"
+  includeStandardActions: true
+  includeWildcard: true
+```
+
+MCP returns:
+- `Permissions.cs` nested class (Application layer constants)
+- Permission seed entries with deterministic GUIDs
+
+### Step B: Write Permissions.cs (Application layer)
+
+```csharp
+// Add to Application/Common/Authorization/Permissions.cs
+public static class {ContextPascal}
+{
+    public const string Access = "{contextCode}.{appCode}";
+
+    public static class {ModulePascal}
+    {
+        public const string View = "{navRoute}.read";
+        public const string Create = "{navRoute}.create";
+        public const string Update = "{navRoute}.update";
+        public const string Delete = "{navRoute}.delete";
+    }
+}
+```
+
+### Step C: Write PermissionsSeedData.cs (Infrastructure layer)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/PermissionsSeedData.cs`
+
+```csharp
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{ModulePascal};
+
+/// <summary>
+/// Permission seed data for {ModuleLabel} module.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class {ModulePascal}PermissionsSeedData
+{
+    // Deterministic GUIDs for permissions
+    public static readonly Guid WildcardPermId = GenerateGuid("{navRoute}.*");
+    public static readonly Guid ReadPermId = GenerateGuid("{navRoute}.read");
+    public static readonly Guid CreatePermId = GenerateGuid("{navRoute}.create");
+    public static readonly Guid UpdatePermId = GenerateGuid("{navRoute}.update");
+    public static readonly Guid DeletePermId = GenerateGuid("{navRoute}.delete");
+
+    public static IEnumerable<PermissionSeedEntry> GetPermissionEntries(Guid moduleId)
+    {
+        return new[]
+        {
+            new PermissionSeedEntry { Id = WildcardPermId, Path = "{navRoute}.*", Level = PermissionLevel.Module, Action = PermissionAction.Access, IsWildcard = true, ModuleId = moduleId, Description = "Full {moduleLabel} access" },
+            new PermissionSeedEntry { Id = ReadPermId, Path = "{navRoute}.read", Level = PermissionLevel.Module, Action = PermissionAction.Read, IsWildcard = false, ModuleId = moduleId, Description = "View {moduleLabel}" },
+            new PermissionSeedEntry { Id = CreatePermId, Path = "{navRoute}.create", Level = PermissionLevel.Module, Action = PermissionAction.Create, IsWildcard = false, ModuleId = moduleId, Description = "Create {moduleLabel}" },
+            new PermissionSeedEntry { Id = UpdatePermId, Path = "{navRoute}.update", Level = PermissionLevel.Module, Action = PermissionAction.Update, IsWildcard = false, ModuleId = moduleId, Description = "Update {moduleLabel}" },
+            new PermissionSeedEntry { Id = DeletePermId, Path = "{navRoute}.delete", Level = PermissionLevel.Module, Action = PermissionAction.Delete, IsWildcard = false, ModuleId = moduleId, Description = "Delete {moduleLabel}" }
+        };
+    }
+
+    private static Guid GenerateGuid(string path)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"permission-{path}"));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+public class PermissionSeedEntry
+{
+    public Guid Id { get; init; }
+    public string Path { get; init; } = null!;
+    public PermissionLevel Level { get; init; }
+    public PermissionAction Action { get; init; }
+    public bool IsWildcard { get; init; }
+    public Guid ModuleId { get; init; }
+    public string Description { get; init; } = null!;
+}
+```
+
+### Step D: MCP Fallback
+
+If MCP `generate_permissions` fails, use the template above directly with values derived from the PRD `coreSeedData.permissions[]`.
+
+---
+
+## 4. RolesSeedData.cs
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/RolesSeedData.cs`
+
+### Context-Based Role Mapping
+
+| Context | Admin | Manager | Contributor | Viewer |
+|---------|-------|---------|-------------|--------|
+| `platform.*` | CRUD | CRU | CR | R |
+| `business.*` | CRUD | CRU | CR | R |
+| `personal.*` | CRUD | CRU | CR | R |
+
+### Template
+
+```csharp
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{ModulePascal};
+
+/// <summary>
+/// Role-permission mapping seed data for {ModuleLabel} module.
+/// Maps permissions to application-scoped roles (Admin, Manager, Contributor, Viewer).
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class {ModulePascal}RolesSeedData
+{
+    /// <summary>
+    /// Returns role-permission mappings for this module.
+    /// Roles are resolved at runtime by Code (not hardcoded GUIDs).
+    /// </summary>
+    public static IEnumerable<RolePermissionSeedEntry> GetRolePermissionEntries()
+    {
+        // Admin: wildcard access
+        yield return new RolePermissionSeedEntry { RoleCode = "admin", PermissionPath = "{navRoute}.*" };
+
+        // Manager: CRUD
+        yield return new RolePermissionSeedEntry { RoleCode = "manager", PermissionPath = "{navRoute}.read" };
+        yield return new RolePermissionSeedEntry { RoleCode = "manager", PermissionPath = "{navRoute}.create" };
+        yield return new RolePermissionSeedEntry { RoleCode = "manager", PermissionPath = "{navRoute}.update" };
+
+        // Contributor: CR
+        yield return new RolePermissionSeedEntry { RoleCode = "contributor", PermissionPath = "{navRoute}.read" };
+        yield return new RolePermissionSeedEntry { RoleCode = "contributor", PermissionPath = "{navRoute}.create" };
+
+        // Viewer: R
+        yield return new RolePermissionSeedEntry { RoleCode = "viewer", PermissionPath = "{navRoute}.read" };
+    }
+}
+
+public class RolePermissionSeedEntry
+{
+    public string RoleCode { get; init; } = null!;
+    public string PermissionPath { get; init; } = null!;
+}
+```
+
+---
+
+## 5. IClientSeedDataProvider Implementation
+
+**File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
+
+### Critical Rules
+
+| Rule | Description |
+|------|-------------|
+| Factory methods | `NavigationModule.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()` |
+| Idempotence | Each Seed method checks existence before inserting |
+| SaveChanges per group | Navigation -> save -> Permissions -> save -> RolePermissions -> save |
+| FK resolution by Code | Parent entities found by `Code`, not hardcoded GUID |
+| DI registration | `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()` |
+
+### Template
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using SmartStack.Application.Common.Interfaces;
+using SmartStack.Application.Common.Interfaces.Seeding;
+using SmartStack.Domain.Navigation;
+using SmartStack.Domain.Platform.Administration.Roles;
+using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{Module1Pascal};
+// using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{Module2Pascal}; // Add per module
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
+
+/// <summary>
+/// Seeds {AppLabel} navigation, permissions, and role-permission data
+/// into the SmartStack Core schema at application startup.
+/// </summary>
+public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
+{
+    public int Order => 100;
+
+    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // --- Application ---
+        var exists = await context.NavigationApplications
+            .AnyAsync(a => a.Code == "{appCode}", ct);
+        if (exists) return;
+
+        var parentContext = await context.NavigationContexts
+            .FirstAsync(c => c.Code == "{contextCode}", ct);
+
+        var app = NavigationApplication.Create(
+            parentContext.Id, "{appCode}", "{appLabel_en}",
+            "{appDesc_en}", "{appIcon}", IconType.Lucide,
+            "/{contextCode}/{appCode}", 1);
+        context.NavigationApplications.Add(app);
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Application translations (4 languages) ---
+        var appTranslations = new[]
+        {
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "fr", "{appLabel_fr}", "{appDesc_fr}"),
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "en", "{appLabel_en}", "{appDesc_en}"),
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "it", "{appLabel_it}", "{appDesc_it}"),
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "de", "{appLabel_de}", "{appDesc_de}")
+        };
+        foreach (var t in appTranslations) context.NavigationTranslations.Add(t);
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Modules ---
+        // Module: {Module1}
+        var mod1Entry = {Module1Pascal}NavigationSeedData.GetModuleEntry(app.Id);
+        var mod1 = NavigationModule.Create(
+            mod1Entry.ApplicationId, mod1Entry.Code, mod1Entry.Label,
+            mod1Entry.Description, mod1Entry.Icon, mod1Entry.IconType,
+            mod1Entry.Route, mod1Entry.DisplayOrder);
+        context.NavigationModules.Add(mod1);
+
+        // Repeat for each module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Module translations ---
+        foreach (var t in {Module1Pascal}NavigationSeedData.GetTranslationEntries())
+        {
+            context.NavigationTranslations.Add(
+                NavigationTranslation.Create(t.EntityType, t.EntityId, t.LanguageCode, t.Label, t.Description));
+        }
+        // Repeat for each module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        var exists = await context.Permissions
+            .AnyAsync(p => p.Path == "{contextCode}.{appCode}.*", ct);
+        if (exists) return;
+
+        // Application-level wildcard
+        var appWildcard = Permission.CreateWildcard(
+            "{contextCode}.{appCode}.*", PermissionLevel.Application,
+            "Full {appLabel_en} access");
+        context.Permissions.Add(appWildcard);
+
+        // Module permissions
+        var mod1 = await context.NavigationModules
+            .FirstAsync(m => m.Code == "{module1Code}", ct);
+        foreach (var entry in {Module1Pascal}PermissionsSeedData.GetPermissionEntries(mod1.Id))
+        {
+            var perm = entry.IsWildcard
+                ? Permission.CreateWildcard(entry.Path, entry.Level, entry.Description)
+                : Permission.CreateForModule(entry.Path, entry.Level, entry.Action, false, entry.ModuleId, entry.Description);
+            context.Permissions.Add(perm);
+        }
+
+        // Repeat for each module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        var exists = await context.RolePermissions
+            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{contextCode}.{appCode}."), ct);
+        if (exists) return;
+
+        // Resolve roles by Code
+        var roles = await context.Roles
+            .Where(r => r.ApplicationId != null || r.IsSystem)
+            .ToListAsync(ct);
+
+        // Resolve permissions
+        var permissions = await context.Permissions
+            .Where(p => p.Path.StartsWith("{contextCode}.{appCode}."))
+            .ToListAsync(ct);
+
+        // Apply role-permission mappings from all modules
+        var allMappings = new List<RolePermissionSeedEntry>();
+        allMappings.AddRange({Module1Pascal}RolesSeedData.GetRolePermissionEntries());
+        // allMappings.AddRange({Module2Pascal}RolesSeedData.GetRolePermissionEntries()); // per module
+
+        foreach (var mapping in allMappings)
+        {
+            var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);
+            var perm = permissions.FirstOrDefault(p => p.Path == mapping.PermissionPath);
+            if (role != null && perm != null)
+            {
+                context.RolePermissions.Add(RolePermission.Create(role.Id, perm.Id, "system"));
+            }
+        }
+
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+}
+```
+
+### DI Registration
+
+```csharp
+// In Infrastructure/DependencyInjection.cs — add:
+using SmartStack.Application.Common.Interfaces.Seeding;
+
+// In the registration method:
+services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
+```
+
+---
+
+## 6. Multi-Module Handling
+
+When processing multiple modules in the same ralph-loop run:
+
+### Module 1 (first): Creates everything from scratch
+
+1. `{Module1}NavigationSeedData.cs`
+2. `{Module1}PermissionsSeedData.cs`
+3. `{Module1}RolesSeedData.cs`
+4. `{AppPascalName}SeedDataProvider.cs` (new)
+5. DI registration (new)
+
+### Module 2+ (subsequent): Append to existing provider
+
+1. `{Module2}NavigationSeedData.cs` (new file)
+2. `{Module2}PermissionsSeedData.cs` (new file)
+3. `{Module2}RolesSeedData.cs` (new file)
+4. `{AppPascalName}SeedDataProvider.cs` (**modify** — add using, add entries in each Seed method)
+5. DI registration (already exists — skip)
+
+**Detection:** Check if `{AppPascalName}SeedDataProvider.cs` exists. If yes, READ it and ADD the new module's entries to each of the 3 methods.
+
+---
+
+## 7. Verification Checklist (BLOCKING)
+
+Before marking the task as completed, verify ALL:
+
+- [ ] Deterministic GUIDs (NEVER `Guid.NewGuid()`) — SHA256 of path
+- [ ] 4 languages for each navigation entity (fr, en, it, de)
+- [ ] `Permissions.cs` constants match seed data paths
+- [ ] MCP `generate_permissions` called (or fallback used)
+- [ ] Role-permission mappings assigned (Admin, Manager, Contributor, Viewer)
+- [ ] `IClientSeedDataProvider` generated with 3 methods
+- [ ] Each Seed method is idempotent (checks existence before inserting)
+- [ ] Factory methods used throughout (NEVER `new Entity()`)
+- [ ] `SaveChangesAsync` called per group (Navigation → Permissions → RolePermissions)
+- [ ] DI registration added: `services.AddScoped<IClientSeedDataProvider, ...>()`
+- [ ] `dotnet build` passes after generation
+
+**If ANY check fails, the task status = 'failed'.**

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -14,6 +14,8 @@ next_step: steps/step-01-task.md
 - YOU ARE AN INITIALIZER, not an executor
 - FORBIDDEN to load step-01 until init is complete
 - ALWAYS check prd.json version is v2
+- **CONTEXT BUDGET**: Keep init output COMPACT. Do NOT dump verbose MCP responses or long file listings. Every token saved here = more tokens for actual code generation in the COMPACT LOOP.
+- **NEVER DELEGATE**: Do NOT use the Task tool to delegate the Ralph loop to a sub-agent. The loop MUST run in the main agent context. Sub-agents lose skill context and stop prematurely.
 
 ## YOUR TASK: