@atlashub/smartstack-cli 2.7.3 → 2.8.0

package/templates/skills/application/templates-seed.md

@@ -960,3 +960,154 @@ Level 5: RESOURCE (finest granularity)
 └─ Path: {context}.{application}.{module}.{section}.{resource}.{action}
    └─ E.g.: platform.administration.ai.prompts.blocks.delete
 ```
+
+---
+
+## SQL OBJECTS INFRASTRUCTURE
+
+> **Usage:** SQL Server functions (TVFs, scalar), views, and stored procedures managed as embedded resources
+> **Pattern:** Same as SmartStack.app — `CREATE OR ALTER` for idempotency, applied via migrations
+> **Location:** `Infrastructure/Persistence/SqlObjects/`
+
+### Directory Structure
+
+```
+Infrastructure/Persistence/SqlObjects/
+├── SqlObjectHelper.cs              ← Helper to apply SQL from embedded resources
+├── Functions/                       ← Table-Valued & Scalar functions
+│   └── fn_{FunctionName}.sql       ← CREATE OR ALTER FUNCTION [schema].[fn_Name]
+├── Views/                           ← Future: SQL views
+│   └── vw_{ViewName}.sql
+└── StoredProcedures/                ← Future: Stored procedures
+    └── sp_{ProcName}.sql
+```
+
+### SqlObjectHelper Pattern
+
+```csharp
+// Infrastructure/Persistence/SqlObjects/SqlObjectHelper.cs
+
+using System.Reflection;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.SqlObjects;
+
+/// <summary>
+/// Helper for applying SQL objects from embedded resources.
+/// SQL files use CREATE OR ALTER for idempotency — safe to re-run on any migration or squash.
+/// </summary>
+public static class SqlObjectHelper
+{
+    private static readonly Assembly Assembly = typeof(SqlObjectHelper).Assembly;
+    private const string ResourcePrefix = "{BaseNamespace}.Infrastructure.Persistence.SqlObjects.";
+
+    /// <summary>
+    /// Applies all SQL objects (functions, views, stored procedures).
+    /// Call in Up() method of a migration, especially after a squash.
+    /// </summary>
+    public static void ApplyAll(MigrationBuilder migrationBuilder)
+    {
+        ApplyAllFunctions(migrationBuilder);
+    }
+
+    public static void ApplyAllFunctions(MigrationBuilder migrationBuilder)
+    {
+        ApplyCategory(migrationBuilder, "Functions");
+    }
+
+    public static void ApplyOne(MigrationBuilder migrationBuilder, string resourceName)
+    {
+        var sql = ReadSqlObject(resourceName);
+        migrationBuilder.Sql(sql);
+    }
+
+    public static string ReadSqlObject(string resourceName)
+    {
+        var fullName = ResourcePrefix + resourceName;
+        using var stream = Assembly.GetManifestResourceStream(fullName)
+            ?? throw new InvalidOperationException(
+                $"SQL object resource '{fullName}' not found. " +
+                $"Ensure the .sql file is marked as EmbeddedResource in the .csproj. " +
+                $"Available: {string.Join(", ", Assembly.GetManifestResourceNames().Where(n => n.EndsWith(".sql")))}");
+        using var reader = new StreamReader(stream);
+        return reader.ReadToEnd();
+    }
+
+    private static void ApplyCategory(MigrationBuilder migrationBuilder, string category)
+    {
+        var prefix = ResourcePrefix + category + ".";
+        var resources = Assembly.GetManifestResourceNames()
+            .Where(n => n.StartsWith(prefix, StringComparison.Ordinal)
+                     && n.EndsWith(".sql", StringComparison.Ordinal))
+            .OrderBy(n => n, StringComparer.Ordinal);
+
+        foreach (var resource in resources)
+        {
+            using var stream = Assembly.GetManifestResourceStream(resource)!;
+            using var reader = new StreamReader(stream);
+            migrationBuilder.Sql(reader.ReadToEnd());
+        }
+    }
+}
+```
+
+### .csproj Configuration (REQUIRED)
+
+```xml
+<ItemGroup>
+  <EmbeddedResource Include="Persistence\SqlObjects\**\*.sql" />
+</ItemGroup>
+```
+
+### SQL File Convention
+
+All `.sql` files MUST use `CREATE OR ALTER` for idempotency:
+
+```sql
+-- Infrastructure/Persistence/SqlObjects/Functions/fn_GetUserGroupHierarchy.sql
+CREATE OR ALTER FUNCTION [extensions].[fn_GetEntityHierarchy](@EntityId UNIQUEIDENTIFIER)
+RETURNS TABLE
+AS
+RETURN
+(
+    WITH Hierarchy AS (
+        SELECT Id, ParentId, 0 AS Level
+        FROM [extensions].[fb_Entities]
+        WHERE Id = @EntityId
+        UNION ALL
+        SELECT child.Id, child.ParentId, parent.Level + 1
+        FROM [extensions].[fb_Entities] child
+        INNER JOIN Hierarchy parent ON child.ParentId = parent.Id
+        WHERE parent.Level < 10
+    )
+    SELECT DISTINCT Id FROM Hierarchy
+);
+```
+
+### Migration Integration
+
+In a migration's `Up()` method, call SqlObjectHelper to apply/re-apply SQL objects:
+
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    // ... table creation, indexes, etc.
+
+    // Apply all SQL objects (idempotent — CREATE OR ALTER)
+    SqlObjectHelper.ApplyAll(migrationBuilder);
+}
+```
+
+Or apply a single function:
+```csharp
+SqlObjectHelper.ApplyOne(migrationBuilder, "Functions.fn_GetEntityHierarchy.sql");
+```
+
+### When to Use SQL Objects
+
+| Need | Solution |
+|------|----------|
+| Recursive hierarchy traversal | TVF with CTE (fn_GetXxxHierarchy) |
+| Complex aggregation for reports | SQL View (vw_XxxSummary) |
+| Bulk operations with business logic | Stored Procedure (sp_XxxBatch) |
+| Simple CRUD, filtering, sorting | EF Core LINQ (no SQL needed) |

package/templates/skills/business-analyse/steps/step-05-handoff.md

@@ -313,43 +313,43 @@ From `specification.uiWireframes[]`, `specification.dashboards[]` and `analysis.
 ```json
 "seedData": [
   {
-    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/NavigationModuleConfiguration.cs",
-    "type": "HasData",
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationModuleSeedData.cs",
+    "type": "SeedData",
     "category": "core",
     "source": "specification.seedDataCore.navigationModules",
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/PermissionsConfiguration.cs",
-    "type": "HasData",
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/PermissionsSeedData.cs",
+    "type": "SeedData",
     "category": "core",
     "source": "specification.seedDataCore.permissions",
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/RolesConfiguration.cs",
-    "type": "HasData",
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs",
+    "type": "SeedData",
     "category": "core",
     "source": "specification.seedDataCore.roles",
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/TenantConfiguration.cs",
-    "type": "HasData",
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/TenantSeedData.cs",
+    "type": "SeedData",
     "category": "core",
     "source": "specification.seedDataCore.tenants",
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/UserConfiguration.cs",
-    "type": "HasData",
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/UserSeedData.cs",
+    "type": "SeedData",
     "category": "core",
     "source": "specification.seedDataCore.users",
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/{Entity}SeedData.cs",
-    "type": "HasData",
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/{Entity}SeedData.cs",
+    "type": "SeedData",
     "category": "business",
     "source": "specification.seedDataBusiness.{module}",
     "module": "{moduleCode}"
@@ -357,12 +357,51 @@ From `specification.uiWireframes[]`, `specification.dashboards[]` and `analysis.
 ]
 ```
 
+**For client projects (ExtensionsDbContext), add these MANDATORY infrastructure files:**
+
+```json
+"seedData": [
+  // ... 5 core + business entries above ...
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs",
+    "type": "IClientSeedDataProvider",
+    "category": "infrastructure",
+    "description": "Runtime provider that injects core seed data (navigation, permissions, roles) into Core schema",
+    "source": "specification.seedDataCore",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/DevDataSeeder.cs",
+    "type": "DevDataSeeder",
+    "category": "infrastructure",
+    "description": "Seeds development/demo data for domain entities at startup",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/SeedConstants.cs",
+    "type": "SeedConstants",
+    "category": "infrastructure",
+    "description": "Shared constants for deterministic seed data",
+    "module": "{moduleCode}"
+  }
+]
+```
+
+**Path convention:** All seed data files MUST be under `Persistence/Seeding/Data/` (matching SmartStack.app architecture).
+NEVER use `Data/SeedData/` or `Infrastructure/Data/SeedData/`.
+
+**IClientSeedDataProvider (MANDATORY for client projects):** This provider injects core seed data
+(navigation, permissions, roles) into the Core schema at runtime. Generated at
+`src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`.
+See `/application` skill step-03b-provider for the full pattern.
+Without this provider, the 5 core SeedData files are DEAD CODE and will have no effect.
+
 Core categories (ALWAYS 5):
-1. NavigationModuleConfiguration (navigation items for module)
-2. PermissionsConfiguration (RBAC permissions)
-3. RolesConfiguration (roles using permissions)
-4. TenantConfiguration (test tenants)
-5. UserConfiguration (test users)
+1. NavigationModuleSeedData (navigation items for module)
+2. PermissionsSeedData (RBAC permissions)
+3. RolesSeedData (roles using permissions)
+4. TenantSeedData (test tenants)
+5. UserSeedData (test users)
 
 Business categories (from specification.seedDataBusiness):
 - Domain-specific reference data
@@ -635,6 +674,8 @@ Generate `.ralph/progress.txt` as main task tracker:
     □ Create {Entity2}Repository
     □ Configure DbContext for module
     □ Setup specifications for complex queries
+    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
+    □ Create DevDataSeeder + SeedConstants (if first module)
     Total: A tasks
 
   [API] REST Endpoints & Controllers
@@ -652,6 +693,7 @@ Generate `.ralph/progress.txt` as main task tracker:
     □ Create custom hook use{ModuleName}
     □ Implement pagination, filtering, sorting
     □ Validate all pages match their wireframe layout
+    □ ⚠️ Routes MUST be INSIDE Layout wrapper (AdminLayout/BusinessLayout/UserLayout)
     Total: C tasks
 
   [I18N] Internationalization Keys

package/templates/skills/controller/steps/step-01-analyze.md

@@ -35,7 +35,7 @@ Glob: "src/SmartStack.Domain/**/{entity}s.cs"
 **If Entity NOT found:**
 ```
 STOP - Entity {entity} not found in Domain layer.
-Create entity first: /apex add {entity} entity to Domain
+Create entity first using /application skill to add the entity to Domain
 ```
 
 ### 2. Check DbContext

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -131,7 +131,27 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
     }
   }
 
-  // 2. Add a final validation task
+  // 2. Add IClientSeedDataProvider task for client projects (ExtensionsDbContext)
+  // This is MANDATORY - without it, core seed data (navigation, permissions, roles) is dead code
+  const hasClientSeedData = filesToCreate["seedData"]?.some(f =>
+    f.type === "IClientSeedDataProvider" || f.path?.includes("SeedDataProvider"));
+  if (!hasClientSeedData && filesToCreate["seedData"]?.length > 0) {
+    tasks.push({
+      id: taskId,
+      description: `[infrastructure] Create IClientSeedDataProvider to inject core seed data at runtime`,
+      status: "pending",
+      category: "infrastructure",
+      dependencies: [lastIdByCategory["infrastructure"] || lastIdByCategory["domain"]].filter(Boolean),
+      acceptance_criteria: "IClientSeedDataProvider implements SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync; registered in DI",
+      started_at: null, completed_at: null, iteration: null, commit_hash: null,
+      files_changed: { created: ["src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs"], modified: ["src/Infrastructure/DependencyInjection.cs"] },
+      validation: null, error: null, module: moduleCode
+    });
+    lastIdByCategory["infrastructure"] = taskId;
+    taskId++;
+  }
+
+  // 3. Add a final validation task
   tasks.push({
     id: taskId,
     description: `[validation] Build, test, and MCP validate module ${moduleCode}`,

package/templates/skills/ralph-loop/steps/step-02-execute.md

@@ -74,13 +74,85 @@ writeJSON('.ralph/prd.json', prd);
 |----------|-----------|----------|
 | `domain` | `validate_conventions` | Entity base class, IHasData, audit fields |
 | `application` | `validate_conventions`, `scaffold_extension` | CQRS, MediatR, FluentValidation |
-| `infrastructure` | `check_migrations`, `suggest_migration` | EF Core config, HasData seeding |
-| `api` | `scaffold_routes`, `validate_security` | Controller conventions, authorization |
-| `frontend` | `validate_frontend_routes`, `scaffold_frontend_extension` | React patterns, hooks |
+| `infrastructure` | `check_migrations`, `suggest_migration` | EF Core config, HasData seeding, IClientSeedDataProvider, SqlObjects |
+| `api` | `scaffold_routes`, `validate_security` | Controller conventions, authorization, context-based folder hierarchy |
+| `frontend` | `validate_frontend_routes`, `scaffold_frontend_extension` | React patterns, hooks, Layout wrapper |
 | `i18n` | - | 4-language JSON structure |
 | `test` | `scaffold_tests`, `analyze_test_coverage` | xUnit, test naming conventions |
 | `validation` | `validate_conventions` | Build, test, lint checks |
 
+**Infrastructure task guidance (MANDATORY directory conventions):**
+
+When executing `infrastructure` category tasks, follow these rules strictly:
+
+1. **Seed data files** MUST go under `Infrastructure/Persistence/Seeding/Data/{Module}/`
+   - NEVER use `Infrastructure/Data/SeedData/` or `Data/SeedData/`
+   - Each module gets 5 core files: NavigationModuleSeedData.cs, PermissionsSeedData.cs, RolesSeedData.cs, TenantSeedData.cs, UserSeedData.cs
+
+2. **IClientSeedDataProvider** (client projects with `extensions` DbContext):
+   - Generate at `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
+   - Register in DI: `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()`
+   - Must implement: SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync
+   - See `/application` skill step-03b-provider for the full pattern
+
+3. **DevDataSeeder** for domain entity seed data:
+   - Located at `Infrastructure/Persistence/Seeding/DevDataSeeder.cs`
+   - Implements `IDevDataSeeder`, registered in DI
+
+4. **Migrations** MUST all be in `Infrastructure/Persistence/Migrations/`
+   - NEVER create subdirectories under Migrations/
+   - Always use `-o Persistence/Migrations` flag with `dotnet ef migrations add`
+
+5. **SQL Objects** go under `Infrastructure/Persistence/SqlObjects/`
+   - `Functions/` for TVFs and scalar functions (.sql files)
+   - Use `SqlObjectHelper.cs` for embedded resource loading
+   - Use `CREATE OR ALTER` in SQL files for idempotency
+
+**Frontend task guidance (MANDATORY Layout wrapper):**
+
+When executing `frontend` category tasks, follow these rules strictly:
+
+1. **Routes MUST be inside Layout wrapper** (CRITICAL - violating this breaks the entire UI shell)
+   - All routes MUST be nested inside the appropriate context Layout component
+   - `platform.*` → `<Route path="/platform" element={<AdminLayout />}>` children
+   - `business.*` → `<Route path="/business" element={<BusinessLayout />}>` children
+   - `personal.*` → `<Route path="/personal/myspace" element={<UserLayout />}>` children
+   - **If routes are placed OUTSIDE the layout wrapper: header, sidebar, and AvatarMenu will NOT render**
+   - NEVER create flat routes at the top level of `<Routes>`
+
+2. **Nested routes, NOT flat routes**
+   - Use `<Route path="application"><Route path="module" element={...} /></Route>` pattern
+   - NEVER use `<Route path="/context/application/module" element={...} />` (flat)
+   - Use `<Route index element={<Navigate to="default" replace />} />` for default redirects
+
+3. **Tenant-prefixed routes** - If `/t/:slug/` block exists, add routes there too
+
+4. **See `/application` skill templates-frontend.md** for full template patterns
+
+**API/Controller task guidance (MANDATORY folder hierarchy):**
+
+When executing `api` category tasks, follow these rules strictly:
+
+1. **Controllers MUST be organized by context and application folders:**
+   - Path: `Api/Controllers/{ContextShort}/{Application}/{EntityName}Controller.cs`
+   - If no application sub-level: `Api/Controllers/{ContextShort}/{EntityName}Controller.cs`
+
+2. **Context-to-folder mapping (from navRoute):**
+
+   | NavRoute Prefix | Controller Folder |
+   |-----------------|-------------------|
+   | `platform.administration` | `Admin` |
+   | `platform.support` | `Support` |
+   | `business.*` | `Business` |
+   | `personal.*` | `User` |
+
+3. **Sub-folders for applications/modules with multiple controllers:**
+   - `Admin/Tenants/` for tenant-related controllers
+   - `Admin/AI/` for AI-related controllers
+   - `Admin/Communications/` for communication controllers
+
+4. **Reference:** SmartStack.app `Api/Controllers/` for the canonical structure
+
 ### 4. Explore Context (if needed)
 
 **Use subagents sparingly:**