@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/skills/application/references/nav-fallback-procedure.md

@@ -1,200 +1,199 @@
-# Navigation: Fallback Procedure (When MCP Unavailable)
-
-> Reference for step-01-navigation.md — generates navigation seeds following SmartStack.app patterns.
-> Reference: `templates-seed.md` for code templates.
->
-> **Branch by Project Type:**
-> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below
-> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** in step file
-
-## F1. Read Existing Configuration Files
-
-**CRITICAL:** Before generating any code, read existing files to determine state:
-
-1. **Find the Navigation Configuration directory:**
-   ```
-   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
-   ```
-
-2. **Read NavigationTranslationConfiguration.cs** - Find the last GUID index:
-   ```
-   Search for: the last call to GenerateGuid(index++)
-   The index variable starts at 1 and increments per translation entry.
-   Your new translations MUST continue from the next index value.
-   ```
-
-3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
-   ```
-   Read the Configuration for the target level (Context, Application, Module, Section).
-   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
-   If yes: Read the corresponding SeedData class to find existing entries.
-   If no: You will need to add HasData() call.
-   ```
-
-4. **Read existing SeedData files** (if they exist):
-   ```
-   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
-   Check for existing entity IDs to avoid collisions.
-   ```
-
-## F2. Determine Parent GUID
-
-For non-context levels, find the parent entity GUID:
-
-| Level | Parent | Where to Find Parent GUID |
-|-------|--------|---------------------------|
-| application | context | `NavigationContextSeedData.cs` → e.g. `PlatformContextId` |
-| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
-| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
-
-Read the parent SeedData class and find the GUID matching `{parent_path}`.
-
-## F3. Generate Navigation Entity GUID
-
-Generate a deterministic GUID for the new navigation entity:
-
-```csharp
-// Use SHA256 hash of the full_path for deterministic generation
-using var sha256 = System.Security.Cryptography.SHA256.Create();
-var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes("navigation-{level}-{full_path}"));
-var guid = new Guid(hash.Take(16).ToArray());
-```
-
-**Rules:**
-- NEVER use `Guid.NewGuid()`
-- Read existing SeedData GUIDs to verify no collision
-- Store result as `{navigation_guid}`
-
-## F4. Write Navigation Entity Seed
-
-Based on `{level}`, write the seed entry.
-
-**Option A: Project uses SeedData classes (SmartStack.app pattern)**
-
-If `Navigation{Level}SeedData.cs` exists, add the new entity:
-
-```csharp
-// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
-
-// Add static GUID field
-public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");
-
-// Add to GetSeedData() return array
-new {
-    Id = {PascalCode}Id,
-    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
-    Code = "{code}",
-    Label = "{labels.en}",
-    Description = "{descriptions.en}",
-    Icon = "{icon}",
-    IconType = IconType.Lucide,
-    Route = "/{full_path_with_slashes}",
-    DisplayOrder = {display_order},
-    IsActive = true,
-    CreatedAt = SeedConstants.SeedDate
-}
-```
-
-**FK property by level:**
-
-| Level | FK Property | References |
-|-------|-------------|------------|
-| context | (none) | - |
-| application | `ContextId` | NavigationContextSeedData.{Parent}Id |
-| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
-| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
-
-**Option B: Project uses inline HasData**
-
-If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:
-
-```csharp
-// In Configure method, add:
-builder.HasData(new {
-    Id = Guid.Parse("{navigation_guid}"),
-    // ... same properties as Option A
-});
-```
-
-## F5. Write Translation Entries
-
-Add 4 translation entries to `NavigationTranslationConfiguration.cs`:
-
-1. Read the file to find the current highest `index` value
-2. Continue from `index + 1`
-3. Use the SAME `GenerateGuid` method already defined in the file:
-
-```csharp
-// In GetSeedData() method, add at the end before return:
-
-// {level}: {code} translations
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
-    LanguageCode = "fr",
-    Label = "{labels.fr}",
-    Description = "{descriptions.fr}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "en",
-    Label = "{labels.en}",
-    Description = "{descriptions.en}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "it",
-    Label = "{labels.it}",
-    Description = "{descriptions.it}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "de",
-    Label = "{labels.de}",
-    Description = "{descriptions.de}",
-    CreatedAt = seedDate
-});
-```
-
-## F6. Store Result
-
-```
-{navigation_guid} = [generated GUID]
-{seed_method} = "fallback"  // Indicates MCP was not used
-```
-
-## F7. Validation Checklist
-
-Before proceeding, verify:
-- [ ] Deterministic GUID generated (not NewGuid())
-- [ ] 4 languages present (fr, en, it, de)
-- [ ] Translation index continues existing sequence (no gaps, no collisions)
-- [ ] Parent GUID correctly references existing entity
-- [ ] Route path matches `/{context}/{app}/{module}` pattern
-- [ ] DisplayOrder is consistent with existing entities
-- [ ] Code is WRITTEN to files, not just displayed
-
-## F8. Present Summary
-
-```markdown
-## Navigation Seeds Generated (Fallback)
-
-**Entity:** {level} - {code}
-**GUID:** {navigation_guid}
-**Path:** {full_path}
-
-### Files Updated
-
-1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
-2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
-```
+# Navigation: Fallback Procedure (When MCP Unavailable)
+
+> Reference for step-01-navigation.md — generates navigation seeds following SmartStack.app patterns.
+> Reference: `templates-seed.md` for code templates.
+>
+> **Branch by Project Type:**
+> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below
+> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** in step file
+
+## F1. Read Existing Configuration Files
+
+**CRITICAL:** Before generating any code, read existing files to determine state:
+
+1. **Find the Navigation Configuration directory:**
+   ```
+   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
+   ```
+
+2. **Read NavigationTranslationConfiguration.cs** - Find the last GUID index:
+   ```
+   Search for: the last call to GenerateGuid(index++)
+   The index variable starts at 1 and increments per translation entry.
+   Your new translations MUST continue from the next index value.
+   ```
+
+3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
+   ```
+   Read the Configuration for the target level (Application, Module, Section, Resource).
+   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
+   If yes: Read the corresponding SeedData class to find existing entries.
+   If no: You will need to add HasData() call.
+   ```
+
+4. **Read existing SeedData files** (if they exist):
+   ```
+   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
+   Check for existing entity IDs to avoid collisions.
+   ```
+
+## F2. Determine Parent GUID
+
+For non-application levels, find the parent entity GUID:
+
+| Level | Parent | Where to Find Parent GUID |
+|-------|--------|---------------------------|
+| application | (none — top level) | — |
+| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
+| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
+
+Read the parent SeedData class and find the GUID matching `{parent_path}`.
+
+## F3. Generate Navigation Entity GUID
+
+Generate a deterministic GUID for the new navigation entity:
+
+```csharp
+// Use SHA256 hash of the full_path for deterministic generation
+using var sha256 = System.Security.Cryptography.SHA256.Create();
+var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes("navigation-{level}-{full_path}"));
+var guid = new Guid(hash.Take(16).ToArray());
+```
+
+**Rules:**
+- NEVER use `Guid.NewGuid()`
+- Read existing SeedData GUIDs to verify no collision
+- Store result as `{navigation_guid}`
+
+## F4. Write Navigation Entity Seed
+
+Based on `{level}`, write the seed entry.
+
+**Option A: Project uses SeedData classes (SmartStack.app pattern)**
+
+If `Navigation{Level}SeedData.cs` exists, add the new entity:
+
+```csharp
+// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
+
+// Add static GUID field
+public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");
+
+// Add to GetSeedData() return array
+new {
+    Id = {PascalCode}Id,
+    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
+    Code = "{code}",
+    Label = "{labels.en}",
+    Description = "{descriptions.en}",
+    Icon = "{icon}",
+    IconType = IconType.Lucide,
+    Route = "/{full_path_with_slashes}",
+    DisplayOrder = {display_order},
+    IsActive = true,
+    CreatedAt = SeedConstants.SeedDate
+}
+```
+
+**FK property by level:**
+
+| Level | FK Property | References |
+|-------|-------------|------------|
+| application | (none — top level) | — |
+| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
+| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
+
+**Option B: Project uses inline HasData**
+
+If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:
+
+```csharp
+// In Configure method, add:
+builder.HasData(new {
+    Id = Guid.Parse("{navigation_guid}"),
+    // ... same properties as Option A
+});
+```
+
+## F5. Write Translation Entries
+
+Add 4 translation entries to `NavigationTranslationConfiguration.cs`:
+
+1. Read the file to find the current highest `index` value
+2. Continue from `index + 1`
+3. Use the SAME `GenerateGuid` method already defined in the file:
+
+```csharp
+// In GetSeedData() method, add at the end before return:
+
+// {level}: {code} translations
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
+    LanguageCode = "fr",
+    Label = "{labels.fr}",
+    Description = "{descriptions.fr}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "en",
+    Label = "{labels.en}",
+    Description = "{descriptions.en}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "it",
+    Label = "{labels.it}",
+    Description = "{descriptions.it}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "de",
+    Label = "{labels.de}",
+    Description = "{descriptions.de}",
+    CreatedAt = seedDate
+});
+```
+
+## F6. Store Result
+
+```
+{navigation_guid} = [generated GUID]
+{seed_method} = "fallback"  // Indicates MCP was not used
+```
+
+## F7. Validation Checklist
+
+Before proceeding, verify:
+- [ ] Deterministic GUID generated (not NewGuid())
+- [ ] 4 languages present (fr, en, it, de)
+- [ ] Translation index continues existing sequence (no gaps, no collisions)
+- [ ] Parent GUID correctly references existing entity
+- [ ] Route path matches `/{app}/{module}` pattern
+- [ ] DisplayOrder is consistent with existing entities
+- [ ] Code is WRITTEN to files, not just displayed
+
+## F8. Present Summary
+
+```markdown
+## Navigation Seeds Generated (Fallback)
+
+**Entity:** {level} - {code}
+**GUID:** {navigation_guid}
+**Path:** {full_path}
+
+### Files Updated
+
+1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
+2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
+```

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

@@ -31,7 +31,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
     {
         // --- Application (idempotent — reuse if already exists) ---
-        var appEntry = NavigationApplicationSeedData.GetApplicationEntry(Guid.Empty);
+        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
         var existingApp = await context.NavigationApplications
             .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
 
@@ -42,12 +42,8 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         }
         else
         {
-            var parentContext = await context.NavigationContexts
-                .FirstAsync(c => c.Code == "{context_code}", ct);
-
-            appEntry = NavigationApplicationSeedData.GetApplicationEntry(parentContext.Id);
             app = NavigationApplication.Create(
-                appEntry.ContextId, appEntry.Code, appEntry.Label,
+                appEntry.Code, appEntry.Label,
                 appEntry.Description, appEntry.Icon, appEntry.IconType,
                 appEntry.Route, appEntry.DisplayOrder);
             context.NavigationApplications.Add(app);

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

@@ -0,0 +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

package/templates/skills/application/references/roles-fallback-procedure.md

@@ -0,0 +1,149 @@
+# Role-Permission Generation: Fallback Procedure (When MCP Unavailable)
+
+> Reference for step-03-roles.md — Generates role-permission HasData entries following SmartStack.app patterns.
+
+---
+
+## F1. Read Existing RolePermissionConfiguration.cs
+
+```
+Glob: **/Persistence/Configurations/Authorization/RolePermissionConfiguration.cs
+```
+
+Read the file to determine:
+- Existing role-permission mappings
+- The GetSeedData() method structure
+- Which roles already have which permissions
+- The GUID generation method used (deterministic or hardcoded)
+
+---
+
+## F2. Read Role GUIDs
+
+**System-level roles** (well-known GUIDs):
+
+| Role | GUID |
+|------|------|
+| SuperAdmin | `11111111-1111-1111-1111-111111111111` |
+| PlatformAdmin | `22222222-2222-2222-2222-222222222222` |
+| TenantAdmin | `33333333-3333-3333-3333-333333333333` |
+| StandardUser | `44444444-4444-4444-4444-444444444444` |
+
+**IMPORTANT:** Read the actual `RoleSeedData.cs` or `RoleConfiguration.cs` in the target project to confirm the actual role GUIDs. The above are defaults; the project may use different values.
+
+**Application-scoped roles** (deterministic GUIDs based on application):
+
+```csharp
+// Read the existing GenerateDeterministicGuid method in RolePermissionConfiguration.cs
+// Typically uses MD5 hash:
+private static Guid GenerateDeterministicGuid(Guid applicationId, string roleType)
+{
+    using var md5 = System.Security.Cryptography.MD5.Create();
+    var input = $"{applicationId}-{roleType}";
+    var hash = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(input));
+    return new Guid(hash);
+}
+// roleType values: "admin", "manager", "contributor", "viewer"
+```
+
+Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
+
+---
+
+## F3. Determine Application-Based Default Mappings
+
+Based on `{full_path}` application prefix:
+
+| Application Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
+|----------------|------------|---------------|-----------|-------------|-----------------|------------|
+| `administration.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `*` (business apps) | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `myspace.*` | wildcard | None | Full CRUD | CRU | CR | R |
+
+---
+
+## F4. Generate RolePermission HasData Entries
+
+Using `{permission_guids}` from step-02:
+
+```csharp
+// In RolePermissionConfiguration.cs - GetSeedData() method
+var seedDate = SeedConstants.SeedDate;
+
+// ============================================================
+// {MODULE_NAME} PERMISSIONS
+// ============================================================
+
+// SuperAdmin: already has *.* wildcard - no individual entries needed
+
+// PlatformAdmin (for platform.* context)
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.delete}, AssignedAt = seedDate });
+
+// Application-scoped: Admin → wildcard
+rolePermissions.Add(new { RoleId = appAdminRoleId, PermissionId = {permission_guids.wildcard}, AssignedAt = seedDate });
+
+// Application-scoped: Manager → CRU (read + create + update — no delete)
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
+
+// Application-scoped: Contributor → CR
+rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
+
+// Application-scoped: Viewer → R
+rolePermissions.Add(new { RoleId = appViewerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
+```
+
+---
+
+## F5. Write Code to RolePermissionConfiguration.cs
+
+**CRITICAL:** Do NOT just display code. WRITE it to the actual file.
+
+1. Open `RolePermissionConfiguration.cs`
+2. Find the `GetSeedData()` method
+3. Add the new role-permission entries to the list
+4. Add necessary permission GUID references (import from PermissionConfiguration or use inline)
+5. Add comments grouping the new entries: `// {MODULE_NAME} PERMISSIONS`
+
+---
+
+## F6. Present Summary
+
+```markdown
+## Role-Permission Mappings Generated (Fallback)
+
+| Role | Permissions |
+|------|-------------|
+| SuperAdmin | Already has wildcard access |
+| PlatformAdmin | {full_path}.read, .create, .update, .delete |
+| App Admin | {full_path}.* (wildcard) |
+| App Manager | {full_path}.read, .create, .update |
+| App Contributor | {full_path}.read, .create |
+| App Viewer | {full_path}.read |
+
+Written to: RolePermissionConfiguration.cs
+```
+
+---
+
+## F7. Offer User Adjustment
+
+If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
+
+---
+
+## Validation Checklist
+
+Before marking as completed, verify:
+
+- [ ] All role GUIDs correctly identified (system and application-scoped)
+- [ ] Role-permission mappings follow application hierarchy
+- [ ] Code WRITTEN to files (not just displayed)
+- [ ] Permission GUID references correct
+- [ ] Comments added for module grouping
+- [ ] No gaps or missing permissions