@atlashub/smartstack-cli 1.36.0 → 2.0.0

package/templates/skills/application/steps/step-01-navigation.md

@@ -1,6 +1,6 @@
 ---
 name: step-01-navigation
-description: Generate navigation entity seeds using MCP scaffold_navigation
+description: Generate navigation entity seeds using MCP scaffold_navigation (with fallback)
 prev_step: steps/step-00-init.md
 next_step: steps/step-02-permissions.md
 ---
@@ -9,16 +9,17 @@ next_step: steps/step-02-permissions.md
 
 ## MANDATORY EXECUTION RULES
 
-- ALWAYS use MCP `scaffold_navigation` tool - NEVER use templates
-- NEVER generate code manually - let MCP handle it
-- ALWAYS verify the output includes translations for 4 languages
-- YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+- PREFER MCP `scaffold_navigation` tool as the primary method
+- If MCP is unavailable (`{mcp_available}` = false) or the call fails, use the FALLBACK PROCEDURE below
+- ALWAYS verify the output includes translations for 4 languages (fr, en, it, de)
+- ALWAYS WRITE generated code to the actual Configuration files (not just display)
+- Store navigation GUID for use in subsequent steps
 
 ## YOUR TASK
 
-Call the SmartStack MCP `scaffold_navigation` tool to generate:
-1. Navigation entity HasData() code
-2. NavigationTranslation entries (4 languages)
+Generate navigation entity seeds:
+1. Navigation entity HasData() code in the appropriate Configuration.cs
+2. NavigationTranslation entries (4 languages) in NavigationTranslationConfiguration.cs
 
 ---
 
@@ -36,10 +37,11 @@ From step-00-init:
 | `{descriptions}` | Object with fr, en, it, de |
 | `{icon}` | Lucide icon name |
 | `{display_order}` | Numeric display order |
+| `{mcp_available}` | Boolean - MCP connectivity status |
 
 ---
 
-## EXECUTION SEQUENCE
+## EXECUTION SEQUENCE (MCP Primary)
 
 ### 1. Call MCP scaffold_navigation
 
@@ -71,38 +73,19 @@ The tool returns:
 - HasData() code for NavigationTranslationConfiguration.cs
 - SeedData class template (optional)
 
-### 3. Present Output to User
+### 3. Write Code to Files
 
-```markdown
-## Navigation Seeds Generated
-
-**Entity:** {level} - {code}
-**GUID:** {generated_guid}
-**Path:** {full_path}
-
-### Files to Update
-
-1. **{NavigationLevelConfiguration}.cs**
-   [Show HasData code from MCP response]
-
-2. **NavigationTranslationConfiguration.cs**
-   [Show translation HasData code from MCP response]
-
-### Recommended: Create SeedData Class
+**CRITICAL:** WRITE the generated code to the actual Configuration files.
 
-[Show SeedData class from MCP response]
-```
+1. Update `Navigation{Level}Configuration.cs` with the new HasData entry
+2. Update `NavigationTranslationConfiguration.cs` with the 4 translation entries
 
 ### 4. Store Generated GUID
 
-**CRITICAL:** Store the navigation entity GUID for use in step-02-permissions:
-
 ```
 {navigation_guid} = [GUID from MCP response]
 ```
 
-This GUID will be referenced when creating permissions.
-
 ---
 
 ## MCP RESPONSE HANDLING
@@ -110,35 +93,235 @@ This GUID will be referenced when creating permissions.
 ### Success Case
 
 If MCP returns successfully:
-- Extract and display all HasData code
+- Write HasData code to Configuration files
 - Store `{navigation_guid}` for next step
 - Proceed to step-02-permissions.md
 
 ### Error Case
 
-If MCP call fails:
-- Display error message
-- Suggest manual alternatives
-- Do NOT proceed automatically
+If MCP call fails or `{mcp_available}` = false:
+- Log the error for reference
+- Proceed to FALLBACK PROCEDURE below
+- Do NOT stop the workflow
+
+---
+
+## FALLBACK PROCEDURE (When MCP Unavailable)
+
+> This procedure generates navigation seeds following SmartStack.app patterns.
+> Reference: `templates-seed.md` for code templates.
+
+### 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
+```
 
 ---
 
 ## SUCCESS METRICS
 
-- MCP scaffold_navigation called successfully
-- Navigation entity GUID obtained
-- HasData code displayed to user
-- Translation code displayed (4 languages)
+- Navigation entity GUID obtained (via MCP or fallback)
+- HasData code WRITTEN to Configuration files
+- Translation code WRITTEN (4 languages)
+- `{navigation_guid}` stored for step-02
 - Proceeded to step-02-permissions.md
 
 ## FAILURE MODES
 
-- MCP call failed (display error, stop)
 - Missing parent path for non-context level (return to step-00)
 - Invalid level (return to step-00)
+- Parent entity not found in existing seeds (ask user for parent GUID)
 
 ---
 
 ## NEXT STEP
 
-After displaying navigation seeds, proceed to `./step-02-permissions.md`
+After navigation seeds are generated (via MCP or fallback) and written to files,
+proceed to `./step-02-permissions.md`

package/templates/skills/application/steps/step-03-roles.md

@@ -1,6 +1,6 @@
 ---
 name: step-03-roles
-description: Generate role-permission mappings using MCP scaffold_role_permissions
+description: Generate role-permission mappings using MCP scaffold_role_permissions (with fallback)
 prev_step: steps/step-02-permissions.md
 next_step: steps/step-04-backend.md
 ---
@@ -9,16 +9,18 @@ next_step: steps/step-04-backend.md
 
 ## MANDATORY EXECUTION RULES
 
-- ALWAYS use MCP `scaffold_role_permissions` tool - NEVER use templates
+- PREFER MCP `scaffold_role_permissions` tool as the primary method
+- If MCP is unavailable or the call fails, use the FALLBACK PROCEDURE below
 - ALWAYS assign permissions to default roles
 - NEVER leave permissions without role assignments
-- YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+- ALWAYS WRITE generated code to the actual RolePermissionConfiguration.cs file
 
 ## YOUR TASK
 
-Call the SmartStack MCP `scaffold_role_permissions` tool to generate:
+Generate role-permission mappings:
 1. RolePermissionConfiguration.cs HasData() entries
-2. Default role assignments (PlatformAdmin, TenantAdmin, StandardUser)
+2. Default role assignments (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser)
+3. Application-scoped role assignments (Admin, Manager, Contributor, Viewer)
 
 ---
 
@@ -31,10 +33,11 @@ From previous steps:
 | `{full_path}` | Complete navigation path (navRoute) |
 | `{level}` | context, application, module, or section |
 | `{permission_guids}` | GUIDs for generated permissions |
+| `{mcp_available}` | Boolean - MCP connectivity status |
 
 ---
 
-## EXECUTION SEQUENCE
+## EXECUTION SEQUENCE (MCP Primary)
 
 ### 1. Determine Default Role Assignments
 
@@ -66,30 +69,24 @@ The tool returns:
 - Permission ID variable references
 - Role ID variable references
 
-### 4. Present Output to User
+### 4. Write Code to Files
+
+**CRITICAL:** WRITE the generated code to the actual RolePermissionConfiguration.cs file.
+
+### 5. Present Summary
 
 ```markdown
 ## Role-Permission Mappings
 
-### Assigned Permissions
-
 | Role | Permissions |
 |------|-------------|
 | SuperAdmin | `{full_path}.*` (via wildcard) |
 | PlatformAdmin | `{full_path}.read`, `.create`, `.update`, `.delete` |
 | TenantAdmin | `{full_path}.read`, `.create`, `.update` |
 | StandardUser | `{full_path}.read` |
-
-### RolePermissionConfiguration.cs HasData
-
-Add to `Infrastructure/Persistence/Configurations/RolePermissionConfiguration.cs`:
-
-[Show HasData entries from MCP response]
 ```
 
-### 5. Confirm with User (Optional)
-
-If the default role assignments don't match the user's needs:
+### 6. Confirm with User (Optional)
 
 ```yaml
 questions:
@@ -107,9 +104,43 @@ questions:
 
 ---
 
-## DEFAULT ROLE GUIDS
+## MCP RESPONSE HANDLING
 
-SmartStack uses well-known GUIDs for default roles:
+### Success Case
+
+If MCP returns successfully:
+- Write RolePermission HasData code to file
+- Show role-permission summary table
+- Proceed to step-04-backend.md
+
+### Error Case
+
+If MCP call fails or `{mcp_available}` = false:
+- Log the error for reference
+- Proceed to FALLBACK PROCEDURE below
+- Do NOT stop the workflow
+
+---
+
+## FALLBACK PROCEDURE (When MCP Unavailable)
+
+> This procedure 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 |
 |------|------|
@@ -118,41 +149,132 @@ SmartStack uses well-known GUIDs for default roles:
 | 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"
+```
 
-## MCP RESPONSE HANDLING
+Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
 
-### Success Case
+### F3. Determine Context-Based Default Mappings
 
-If MCP returns successfully:
-- Display RolePermission HasData code
-- Show role-permission summary table
-- Proceed to step-04-backend.md
+Based on `{full_path}` prefix:
 
-### Error Case
+| Context Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
+|----------------|------------|---------------|-----------|-------------|-----------------|------------|
+| `platform.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `business.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
+| `personal.*` | 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 → CRUD
+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
+
+```yaml
+questions:
+  - header: "Role Access"
+    question: "Default role-permission mappings have been applied. Adjust?"
+    options:
+      - label: "Keep defaults (Recommended)"
+        description: "Standard role hierarchy applied"
+      - label: "Custom adjustments"
+        description: "I want to change specific role permissions"
+    multiSelect: false
+```
 
-If MCP call fails:
-- Display error message
-- Suggest checking permission GUIDs
-- Provide manual template as fallback
+If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
 
 ---
 
 ## SUCCESS METRICS
 
-- MCP scaffold_role_permissions called successfully
-- Role-permission mappings displayed
+- Role-permission mappings generated (via MCP or fallback)
+- RolePermissionConfiguration.cs WRITTEN with new entries
 - All default roles have appropriate access
 - Proceeded to step-04-backend.md
 
 ## FAILURE MODES
 
-- MCP call failed (display error, suggest fallback)
-- Permission GUIDs not available (return to step-02)
-- Invalid navRoute (return to step-00)
+- Permission GUIDs not available from step-02 (return to step-02)
+- Role GUIDs not found in project (ask user, use well-known defaults)
+- Invalid navRoute format (return to step-00)
 
 ---
 
 ## NEXT STEP
 
-After displaying role-permission mappings, proceed to `./step-04-backend.md`
+After role-permission mappings are generated (via MCP or fallback) and written to files,
+proceed to `./step-04-backend.md`