@atlashub/smartstack-cli 2.7.2 → 2.7.4

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/efcore/steps/squash/step-03-create.md

@@ -131,6 +131,45 @@ echo "  Up methods: $UP_METHODS"
 echo "  Down methods: $DOWN_METHODS"
 ```
 
+### 6. Inject SQL Objects (Functions, Views, SP)
+
+EF Core ne génère PAS de DDL pour les TVF, vues et procédures stockées.
+Les scripts SQL source sont dans `Persistence/SqlObjects/` (Embedded Resources).
+Après un squash, il faut les réinjecter dans la migration consolidée.
+
+```bash
+# Check if SqlObjects folder exists with .sql files
+SQL_OBJECTS_DIR="$INFRA_PROJECT_DIR/Persistence/SqlObjects"
+SQL_FILES=$(find "$SQL_OBJECTS_DIR" -name "*.sql" 2>/dev/null | wc -l)
+
+if [ "$SQL_FILES" -gt 0 ]; then
+  echo ""
+  echo "Found $SQL_FILES SQL object(s) in SqlObjects/"
+  echo "Injecting SqlObjectHelper.ApplyAll(migrationBuilder) into migration..."
+
+  # Add using directive if not present
+  if ! grep -q "using SmartStack.Infrastructure.Persistence.SqlObjects;" "$MIGRATION_FILE"; then
+    sed -i '1s/^/using SmartStack.Infrastructure.Persistence.SqlObjects;\n/' "$MIGRATION_FILE"
+  fi
+
+  # Add SqlObjectHelper.ApplyAll at the end of Up() method
+  # Find the closing brace of Up() and insert before it
+  sed -i '/protected override void Up/,/^        }/ {
+    /^        }/ i\
+\            // Apply SQL objects (TVF, Views, SP) from embedded resources\
+\            SqlObjectHelper.ApplyAll(migrationBuilder);
+  }' "$MIGRATION_FILE"
+
+  echo "  ✅ SqlObjectHelper.ApplyAll(migrationBuilder) injected"
+  find "$SQL_OBJECTS_DIR" -name "*.sql" -exec basename {} \; | while read f; do
+    echo "  📄 $f"
+  done
+else
+  echo ""
+  echo "No SQL objects found in SqlObjects/ - skipping injection"
+fi
+```
+
 ---
 
 ## EXPECTED RESULT:

package/templates/skills/ralph-loop/SKILL.md

@@ -108,7 +108,7 @@ The loop only stops when this exact tag is output or max iterations reached.
 </ralph_concept>
 
 <workflow>
-**Standard flow:**
+**Standard flow (single module):**
 1. Parse flags and task description
 2. Verify MCP servers are available (MANDATORY)
 3. Initialize .ralph/ structure and state files
@@ -117,6 +117,15 @@ The loop only stops when this exact tag is output or max iterations reached.
 6. Commit changes, update progress
 7. Check completion criteria
 8. If complete: generate final report
+
+**Multi-module flow (from BA handoff):**
+1-3. Same as standard flow
+4. Detect `prd-*.json` files → create `modules-queue.json`
+5. Copy current module's prd to `prd.json`
+6. Execute all tasks for current module (standard loop: steps 01→02→03→04)
+7. When module complete: advance to next module in queue
+8. Repeat steps 5-7 for each module
+9. When all modules done: generate cross-module report
 </workflow>
 
 <state_variables>
@@ -136,6 +145,8 @@ The loop only stops when this exact tag is output or max iterations reached.
 | `{task_category}` | string | Task category (domain/application/infrastructure/api/frontend/i18n/test/validation) |
 | `{files_created}` | string[] | Files created during current task |
 | `{files_modified}` | string[] | Files modified during current task |
+| `{current_module}` | string\|null | Current module code (multi-module only) |
+| `{modules_queue}` | object\|null | Module queue state (multi-module only) |
 
 </state_variables>
 
@@ -184,14 +195,33 @@ Before ANY work, verify MCP servers:
 
 ```
 .ralph/
-├── prd.json          # Task list with status
-├── progress.txt      # Persistent memory between iterations
+├── prd.json              # Task list with status (current module or single)
+├── progress.txt          # Persistent memory between iterations
+├── modules-queue.json    # Multi-module tracking (only if multiple prd-*.json exist)
+├── prd-{module1}.json    # Per-module PRD from BA handoff (source, not modified)
+├── prd-{module2}.json    # Per-module PRD from BA handoff (source, not modified)
 ├── logs/
 │   └── {timestamp}.log
 └── reports/
     └── {feature-name}.md
 ```
 
+**modules-queue.json structure (multi-module only):**
+```json
+{
+  "modules": [
+    {
+      "code": "module-code",
+      "prdFile": ".ralph/prd-module-code.json",
+      "status": "pending|in-progress|completed|failed|partial"
+    }
+  ],
+  "currentIndex": 0,
+  "totalModules": 3,
+  "completedModules": 0
+}
+```
+
 **prd.json structure:**
 ```json
 {
@@ -267,6 +297,8 @@ Before ANY work, verify MCP servers:
 - Completion promise output when genuinely complete
 - Final report generated in `.ralph/reports/`
 - `prd.json` top-level `status` set to `"completed"` or `"partial"`
+- **Multi-module:** All modules in `modules-queue.json` processed sequentially
+- **Multi-module:** Cross-module aggregation in final report
 </success_criteria>
 
 <available_commands>

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

@@ -163,6 +163,22 @@ fi
    - Read `prd.config.completion_promise` → `{completion_promise}`
    - Read `prd.config.max_iterations` → `{max_iterations}`
    - Read progress.txt for context
+
+6. **Restore multi-module state (if applicable):**
+   ```javascript
+   if (fileExists('.ralph/modules-queue.json')) {
+     const queue = readJSON('.ralph/modules-queue.json');
+     const currentModule = queue.modules[queue.currentIndex];
+
+     // Restore module state
+     {modules_queue} = queue;
+     {current_module} = currentModule.code;
+
+     console.log(`Resuming multi-module: ${currentModule.code} (${queue.currentIndex + 1}/${queue.totalModules})`);
+     console.log(`Modules completed: ${queue.completedModules}/${queue.totalModules}`);
+   }
+   ```
+
    - Continue to step-01
 
 ### 4. Initialize .ralph/ Structure (new loop)
@@ -183,6 +199,80 @@ mkdir -p .ralph/logs
 mkdir -p .ralph/reports
 ```
 
+### 4b. Detect Multi-Module PRDs (from BA Handoff)
+
+**After creating `.ralph/` directory, check for per-module PRD files:**
+
+```bash
+# Count prd-*.json files (generated by BA handoff via ss derive-prd)
+PRD_FILES=$(ls .ralph/prd-*.json 2>/dev/null)
+PRD_COUNT=$(echo "$PRD_FILES" | grep -c "prd-" 2>/dev/null || echo "0")
+```
+
+**If multiple prd-*.json files found (PRD_COUNT > 0):**
+
+1. **Read module order from master feature.json (if available):**
+```bash
+# Look for master feature.json that references modules
+MASTER_FEATURE=$(find docs/business -maxdepth 4 -name "feature.json" -path "*/business-analyse/*" | head -1)
+```
+
+2. **Build module queue:**
+```javascript
+const modules = [];
+
+if (MASTER_FEATURE && masterJson.metadata?.workflow?.moduleOrder) {
+  // Use order from BA master feature.json
+  for (const mod of masterJson.metadata.workflow.moduleOrder) {
+    const prdFile = `.ralph/prd-${mod.code}.json`;
+    if (fileExists(prdFile)) {
+      modules.push({ code: mod.code, prdFile, status: "pending" });
+    }
+  }
+} else {
+  // Fallback: alphabetical order from prd-*.json filenames
+  for (const file of prdFiles) {
+    const code = file.match(/prd-(.+)\.json$/)[1];
+    modules.push({ code, prdFile: `.ralph/${file}`, status: "pending" });
+  }
+}
+```
+
+3. **Create modules-queue.json:**
+```json
+{
+  "modules": [
+    { "code": "mod1", "prdFile": ".ralph/prd-mod1.json", "status": "pending" },
+    { "code": "mod2", "prdFile": ".ralph/prd-mod2.json", "status": "pending" }
+  ],
+  "currentIndex": 0,
+  "totalModules": 2,
+  "completedModules": 0
+}
+```
+
+4. **Set first module as active:**
+```javascript
+modules[0].status = "in-progress";
+```
+
+5. **Log detection:**
+```
+Multi-module detected: {PRD_COUNT} modules
+Queue: {module codes joined by " → "}
+Starting with: {modules[0].code}
+```
+
+**If only `.ralph/prd.json` exists (single module):**
+- Skip queue creation (backward compatible)
+- Proceed normally
+
+**Store:**
+```
+{modules_queue} = queue object or null
+{current_module} = first module code or null
+```
+
 ### 5. Validate Completion Promise
 
 **If {completion_promise} is null:**
@@ -251,10 +341,12 @@ Branch: {CURRENT_BRANCH}
 ║  MCP: ✅ Ready                                                  ║
 ║  Schema: v2.0.0                                                 ║
 ║  Branch: {CURRENT_BRANCH}                                       ║
+║  {modules_queue ? "Modules: " + totalModules + " (" + module_codes.join(" → ") + ")" : "Mode: single module"} ║
 ╠══════════════════════════════════════════════════════════════════╣
 ║  Files:                                                          ║
 ║  - .ralph/prd.json (tasks)                                       ║
 ║  - .ralph/progress.txt (memory)                                  ║
+║  {modules_queue ? "- .ralph/modules-queue.json (module tracking)" : ""} ║
 ╚══════════════════════════════════════════════════════════════════╝
 
 -> Loading tasks...
@@ -273,6 +365,7 @@ Branch: {CURRENT_BRANCH}
 - Metadata collected (branch, version, MCP status)
 - prd.json v2 schema validated (if resume)
 - Branch integrity validated (if resume)
+- Multi-module prd files detected and modules-queue.json created (if applicable)
 - Output is COMPACT
 - Proceeded to step-01 immediately after summary