@atlashub/smartstack-cli 3.34.0 → 3.36.0

package/templates/skills/documentation/SKILL.md

@@ -81,7 +81,68 @@ Identify the specific name:
 
 ### STEP 3: EXECUTION
 
-**For NEW documentation (type = user|developer|database|testing):**
+**For NEW documentation (type = user) - AUTOMATIC MOCK UI GENERATION:**
+
+Use the automated generator script that creates complete documentation with Mock UI components:
+
+```bash
+npx tsx scripts/generate-doc-with-mock-ui.ts \
+  --module {module} \
+  --context {context} \
+  --application {application} \
+  --app-path "D:/01 - projets/SmartStack.app/02-Develop"
+```
+
+**What it does automatically:**
+
+1. **Find & Extract Entity** (e.g., users → User.cs)
+   - Locates Domain entity file
+   - Extracts all properties with types
+
+2. **Extract API Endpoints** (via `extract-api-endpoints.ts`)
+   - Scans controller for all endpoints
+   - Parses `[HttpGet]`, `[HttpPost]`, `[NavRoute]`, `[RequirePermission]`
+   - Resolves permission constants
+   - Output: JSON array of endpoints with method, path, handler, permission
+
+3. **Extract Business Rules** (via `extract-business-rules.ts`)
+   - Scans Domain entity for guard clauses and DomainExceptions
+   - Scans unit tests for edge case scenarios
+   - Auto-assigns BR-XXX IDs and categorizes rules
+   - Output: JSON array of business rules with id, name, category, statement
+
+4. **Generate Mock UI Components**
+   - **KPIs**: Automatic stats based on entity properties
+     - Total count
+     - Active/Inactive (if IsActive property)
+     - Status breakdown (if Status property)
+     - Time-based stats (if DateTime property)
+   - **Table**: Smart column selection (6 most relevant properties)
+     - Filters out: Hash, Token, *Id (FK), normalized, internal fields
+     - Prioritizes: name/title → email → status → date
+   - **Form**: Create form with intelligent field types
+     - Email → type="email" with placeholder
+     - Bool → checkbox
+     - DateTime → type="date"
+     - Description/Notes → textarea
+     - Default → type="text"
+
+5. **Generate Complete TSX File**
+   - Full React component with breadcrumb, sections, mock data
+   - Section 1: Introduction
+   - Section 2: Access (navigation path + URL)
+   - Section 3: Interface Overview (KPIs + Table Mock UI)
+   - Section 4: Create Form (generated form fields)
+   - Section 5: API Reference (endpoints table)
+
+6. **Manual Steps (Post-Generation)**
+   - Save generated TSX to `docs/business/{context}/{application}/{module}/index.tsx`
+   - Update docs-manifest.json
+   - Update App.tsx routing
+   - Update DocPanelContext.tsx mapping
+   - Generate i18n FR file (if needed)
+
+**For NEW documentation (type = developer|database|testing):**
 
 Follow the data-driven workflow from [templates.md](templates.md):
 
@@ -92,22 +153,127 @@ Follow the data-driven workflow from [templates.md](templates.md):
 4. Generate i18n FR file (source language only)
 5. Update docs-manifest.json
 6. Update App.tsx routing and parent indexes
-7. Update DocPanelContext.tsx mapping (contextual doc panel)
 ```
 
 **For UPDATE documentation (type = update):**
 
+Re-run the generator script to refresh automatically extracted data:
+
 ```
-1. Read docs-manifest.json → find target module
-2. Invoke docs-context-reader agent → get current doc state
-3. Identify code changes since last doc update (git diff)
-4. Map changes to documentation sections (see data-schema.md)
-5. Update doc-data.ts with new/modified data
-6. Update i18n FR file if labels changed
-7. Update docs-manifest.json timestamps
+1. Run generate-doc-with-mock-ui.ts → regenerates with latest API/rules
+2. Update i18n FR file if labels changed
+3. Update docs-manifest.json timestamps
 ```
 
 > **i18n simplifié:** Seul FR (source) est généré. EN/IT/DE sont déférés à un pipeline de traduction séparé.
+
+---
+
+## EXTRACTION SCRIPTS REFERENCE
+
+### extract-api-endpoints.ts
+
+**Purpose:** Extract all API endpoints from SmartStack controllers
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**What it extracts:**
+- Controller file path (e.g., `UsersController.cs`)
+- HTTP method (`[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`)
+- Route suffix (e.g., `{id:guid}`, `activate`)
+- Base path from `[NavRoute("platform.administration.users")]`
+- Permission from `[RequirePermission(Permissions.Admin.Users.View)]`
+- Handler method name
+
+**Output:** JSON array
+```json
+[
+  {
+    "method": "GET",
+    "path": "/api/platform/administration/users",
+    "handler": "GetUsers",
+    "permission": "platform.administration.users.read"
+  }
+]
+```
+
+**Permission resolution:**
+- Loads `Permissions.cs` constants
+- Maps `Permissions.Admin.Users.View` → `"platform.administration.users.read"`
+
+---
+
+### extract-business-rules.ts
+
+**Purpose:** Extract business rules from Domain entities and unit tests
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Phase 1: Domain Entity Extraction**
+- Scans Domain entity (e.g., `User.cs`)
+- Looks for guard clauses: `if (...) throw new DomainException("...")`
+- Looks for validation in Create/Update methods
+- Extracts exception messages and context
+
+**Phase 2: Unit Tests Extraction**
+- Scans unit test file (e.g., `UserTests.cs`)
+- Looks for test methods with `[Fact]` attribute
+- Extracts test names and scenarios (edge cases)
+- Maps to business rule statements
+
+**Output:** JSON array
+```json
+[
+  {
+    "id": "BR-001",
+    "name": "Email requis",
+    "category": "Validation",
+    "statement": "Un utilisateur doit avoir une adresse email valide et non vide"
+  }
+]
+```
+
+**Auto-categorization:**
+- Validation: Required fields, format checks
+- Security: Password rules, access control
+- Business Logic: State transitions, calculations
+
+---
+
+### generate-doc-with-mock-ui.ts
+
+**Purpose:** Main generator - creates complete documentation TSX with Mock UI
+
+**Input:**
+- `--module {module}` - Module name (e.g., users)
+- `--context {context}` - Context (e.g., platform)
+- `--application {application}` - Application (e.g., administration)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Workflow:**
+1. Find Domain entity file (users → User.cs via singularize)
+2. Extract entity properties (name, type, nullable, required)
+3. Call `extract-api-endpoints.ts`
+4. Call `extract-business-rules.ts`
+5. Generate mock data (5 sample records with realistic values)
+6. Generate KPI stats (Total, Active/Inactive, Status breakdown)
+7. Generate table UI (smart column selection - 6 most relevant)
+8. Generate form UI (intelligent field types based on property)
+9. Output complete TSX file to stdout
+
+**Smart Features:**
+- **Singularize**: users → User.cs, tenants → Tenant.cs
+- **Property filtering**: Excludes hash, token, *Id, normalized, internal
+- **Priority selection**: name/title > email > status > date
+- **Field type detection**: email → email input, bool → checkbox
+- **Mock value generation**: Realistic emails, names, dates, GUIDs
+
+**Output:** Complete React TSX component (400-500 lines)
+
 </workflow>
 
 <execution_rules>

package/templates/skills/efcore/steps/squash/step-03-create.md

@@ -55,10 +55,11 @@ echo "DbContext Type: $DBCONTEXT_TYPE"
 
 const result = await mcp__smartstack__suggest_migration({
   description: DESCRIPTION,
-  context: DBCONTEXT_TYPE    // NEVER hardcode!
+  context: DBCONTEXT_TYPE,   // NEVER hardcode!
+  squash: true               // Squash format: {context}_v{version} (no sequence/description)
 });
 
-// Result example: core_v1.9.0_001_MultitenantConsolidated
+// Result example: core_v1.9.0 (squash — just version, no _001_Description)
 MIGRATION_NAME = result.migrationName;
 ```
 
@@ -66,11 +67,12 @@ MIGRATION_NAME = result.migrationName;
 - Calculating name manually
 - Hardcoding context as "core"
 - Using underscores instead of dots in version
+- Adding sequence/description to squash migrations
 
 ### 3. Create Migration with EF Core
 
 ```bash
-# MIGRATION_NAME = result from MCP (e.g., core_v1.9.0_001_MultitenantConsolidated)
+# MIGRATION_NAME = result from MCP (e.g., core_v1.9.0)
 # DBCONTEXT = CoreDbContext or ExtensionsDbContext (from detect_dbcontext)
 
 echo ""
@@ -211,7 +213,7 @@ After step-03-create:
 
 | Variable | Description |
 |----------|-------------|
-| `{migration_name}` | Name from MCP (e.g., core_v1.9.0_001_...) |
+| `{migration_name}` | Name from MCP (e.g., core_v1.9.0) |
 | `{migration_file}` | Full path to .cs file |
 | `{designer_file}` | Full path to .Designer.cs file |
 

package/templates/skills/gitflow/_shared.md

@@ -462,7 +462,9 @@ GitFlow configuration JSON template v2.1.0 (aligned with `templates/config.json`
     "enabled": true,
     "validateOnCommit": true,
     "blockDestructive": true,
-    "migrationNaming": "{context}_v{version}_{sequence}_{Description}"
+    "migrationNaming": "{context}_v{version}_{sequence}_{Description}",
+    "migrationNamingSquash": "{context}_v{version}",
+    "squashBeforePR": true
   },
   "workflow": {
     "push": {

package/templates/skills/gitflow/steps/step-pr.md

@@ -122,6 +122,40 @@ else
 fi
 ```
 
+### 4b. Enforce Migration Squash (Feature Branches)
+
+**BLOCKING**: Feature branches must have at most 1 migration before creating a PR.
+
+```bash
+if [ "$BRANCH_TYPE" = "feature" ]; then
+  MIGRATION_DIR=$(find . -path "*/Persistence/Migrations" -type d 2>/dev/null | head -1)
+  if [ -n "$MIGRATION_DIR" ]; then
+    # Count migration .cs files added by this feature (not in target branch)
+    NEW_MIGRATIONS=$(git diff --name-only "origin/$TARGET_BRANCH...HEAD" -- "$MIGRATION_DIR" \
+      | grep -E '\.cs$' \
+      | grep -v 'Designer\|ModelSnapshot' \
+      | wc -l)
+
+    if [ "$NEW_MIGRATIONS" -gt 1 ]; then
+      echo ""
+      echo "❌ MULTIPLE MIGRATIONS DETECTED ($NEW_MIGRATIONS migrations)"
+      echo "→ Feature branches must have exactly 1 migration (squashed) before PR"
+      echo "→ Run: /efcore squash"
+      echo ""
+      echo "Migrations found:"
+      git diff --name-only "origin/$TARGET_BRANCH...HEAD" -- "$MIGRATION_DIR" \
+        | grep -E '\.cs$' \
+        | grep -v 'Designer\|ModelSnapshot'
+      STOP
+    elif [ "$NEW_MIGRATIONS" -eq 1 ]; then
+      echo "✓ Single migration detected (squashed)"
+    else
+      echo "✓ No migrations in this feature"
+    fi
+  fi
+fi
+```
+
 ### 5. Generate PR Content
 
 **Title:**

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

@@ -36,6 +36,7 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
 | `-c TEXT` | `--completion-promise TEXT` | Completion signal text |
 | `-v` | `--verbose` | Detailed logging |
 | `-r` | `--resume` | Resume from previous state |
+| `-p` | `--parallel` | Teams mode: Phase 0 (entities) sequential, then spawn parallel teammates per application/module |
 </parameters>
 
 <workflow>
@@ -50,9 +51,30 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
    - Find eligible → batch by category (max 5) → execute → test → commit → loop
 7. Report (step-05)
 
-**Multi-module (2+ modules, from BA handoff):**
+**Multi-module (2+ modules) with `-p` (parallel mode):**
+1. Init: detect prd-*.json, parse `-p` flag (step-00)
+2. **Phase 0 (Ralph sequential):**
+   - Ralph generates ALL entities from ALL modules via `/apex --foundation`
+   - Creates ONE migration with all entities
+   - Commits: `chore(foundation): entities for all modules`
+3. **Phase 1-N (Teams parallel):**
+   ```
+   Team Lead → TeamCreate("smartstack-{project}")
+     Spawn teammates (1 per application OR 1 per module if app > 3 modules):
+       - Task(subagent_type: "apex", name: "apex-hr")
+       - Task(subagent_type: "apex", name: "apex-crm")
+       - Task(subagent_type: "apex", name: "apex-pm")
+     Each teammate generates:
+       - Services + Controllers + Seed data + Frontend + Tests
+       - NO entities (already done in Phase 0)
+       - NO migrations (ModelSnapshot already complete)
+     → Teammates work in parallel → Ralph collects results → TeamDelete
+   ```
+4. Report with per-module aggregation (step-05)
+
+**Multi-module (2+ modules) WITHOUT `-p` (sequential mode — legacy):**
 1. Init: detect prd-*.json, read dependency layers (step-00)
-2. **IF dependency graph available:** Agent Teams (parallel)
+2. **IF dependency graph available:** Agent Teams (parallel, legacy)
    ```
    Team Lead → TeamCreate("ralph-{app}")
      Layer 0: Spawn "mod-employees" (foundation) → wait LAYER_READY
@@ -79,6 +101,10 @@ LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODUL
 | `{current_iteration}` | number | Current iteration |
 | `{current_module}` | string\|null | Current module (multi-module) |
 | `{modules_queue}` | object\|null | Module queue (multi-module) |
+| `{section_split_mode}` | boolean | Section splitting active for current module (>4 entities + >1 section) |
+| `{section_phases}` | SectionPhase[] | Phase execution plan (Phase 0: foundation, Phase 1..N: per-section) |
+| `{parallel_mode}` | boolean | Teams mode enabled via `-p` flag. Ralph generates Phase 0 (entities) sequentially, then spawns parallel teammates. |
+| `{team_name}` | string\|null | Team name for parallel mode (e.g., "smartstack-hr") |
 </state_variables>
 
 <mcp_requirements>
@@ -141,6 +167,7 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 |------|-------------|
 | `references/category-rules.md` | Step-01 and compact loop (category ordering and dependency rules) |
 | `references/compact-loop.md` | Step-04 section 5 (module loop with /apex delegation) |
+| `references/section-splitting.md` | Step-01 section 4c when module has >4 entities + >1 section |
 | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
 </step_files>
 
@@ -151,6 +178,8 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 ├── progress.txt          # Persistent memory
 ├── modules-queue.json    # Multi-module tracking (if applicable)
 ├── prd-{module}.json     # Per-module PRDs (from ss derive-prd, unified v3 format)
+├── prd-{module}-phase0.json         # Section split: Foundation (domain+infra+migration)
+├── prd-{module}-section-{code}.json # Section split: Per-section (app+api+seed+frontend+tests)
 ├── logs/
 └── reports/
     └── {feature}.md

package/templates/skills/ralph-loop/references/category-rules.md

@@ -65,3 +65,32 @@ A valid PRD MUST contain tasks in these categories:
 - `test` — at least 1 test task
 
 If any category is missing, ralph step-01 injects a guardrail task.
+
+---
+
+## Section-Level Splitting (>4 Entities)
+
+When a module has many entities, a single `/apex -d` call saturates the context window.
+Section-level splitting breaks the module into smaller, manageable phases.
+
+**Activation threshold:** `> 4 domain tasks` AND `> 1 architecture section`
+
+| Phase | Content | Depends On |
+|-------|---------|------------|
+| Phase 0 | ALL domain + infrastructure + migration + module seed data | — |
+| Phase 1 | Section A: services, controllers, section seed, pages, i18n, tests | Phase 0 |
+| Phase 2 | Section B: idem | Phase 0 (+ Phase 1 if FK cross-section) |
+| Phase N | Section N: idem | Phase 0 (+ earlier phases if FK) |
+| Final | Cross-validation (dotnet build, typecheck, MCP validate) | All phases |
+
+**Key rules:**
+- Phase 0 creates ALL entity classes + ALL EF configs + ONE migration (avoids ModelSnapshot conflicts)
+- Section phases NEVER create entities or migrations — only services, controllers, pages on top
+- FK cross-section dependencies determine section execution order (topological sort)
+- Orphan entities (not in any section) are included in Phase 0 with their services/controllers
+- Each phase produces a temporary PRD file: `.ralph/prd-{module}-phase0.json`, `.ralph/prd-{module}-section-{code}.json`
+- Temporary PRD files are cleaned up in step-05 (report)
+
+**Backward compatible:** Modules with `<= 4 domain tasks` or `1 section` → standard execution, zero impact.
+
+See `references/section-splitting.md` for full detection, mapping, and execution logic.

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -23,10 +23,93 @@ Display compact progress:
 
 ---
 
-## A. Find Eligible Tasks
+## A0. Section-Split Mode (checked BEFORE standard batching)
 
 ```javascript
 const prd = readJSON('.ralph/prd.json');
+
+if (prd._sectionSplit?.enabled) {
+  // SECTION-SPLIT: Delegate per-phase instead of per-category batch
+
+  // Find next pending phase with dependencies met
+  const nextPhase = prd._sectionSplit.phases.find(p => p.status === 'pending');
+
+  if (!nextPhase) {
+    // All phases done — check if master PRD tasks are all complete
+    goto CHECK_COMPLETION;
+  }
+
+  const depsOk = nextPhase.dependsOn.every(depIdx =>
+    prd._sectionSplit.phases[depIdx].status === 'completed'
+  );
+
+  if (!depsOk) {
+    // Phase blocked — should not happen with topological sort
+    console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
+    goto CHECK_COMPLETION;
+  }
+
+  const phaseLabel = nextPhase.type === 'foundation'
+    ? `Phase 0: Foundation (${nextPhase.entities.length} entities + migration)`
+    : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (${nextPhase.entities.length} entities)`;
+  console.log(`[{iteration}/{max}] SECTION SPLIT: ${phaseLabel}`);
+
+  // INVOKE /apex -d {nextPhase.prdFile}
+  // Apex sees a normal (smaller) PRD and executes normally
+
+  // After apex returns: merge results back into master PRD
+  // Read references/section-splitting.md sections 7-9
+  const phasePrd = readJSON(nextPhase.prdFile);
+  for (const phaseTask of phasePrd.tasks) {
+    const masterTask = prd.tasks.find(t => t.id === phaseTask.id);
+    if (masterTask) {
+      masterTask.status = phaseTask.status;
+      masterTask.completed_at = phaseTask.completed_at;
+      masterTask.commit_hash = phaseTask.commit_hash;
+      masterTask.files_changed = phaseTask.files_changed;
+      masterTask.error = phaseTask.error;
+      masterTask.validation = phaseTask.validation;
+    }
+  }
+
+  // Handle phase failure
+  if (phasePrd.tasks.some(t => t.status === 'failed')) {
+    const retryCount = nextPhase._retryCount || 0;
+    if (retryCount < 2) {
+      nextPhase.status = 'pending';
+      nextPhase._retryCount = retryCount + 1;
+      console.log(`Phase ${nextPhase.phase} had failures — retry ${retryCount + 1}/2`);
+      // Reset failed tasks in phase PRD for retry
+      for (const task of phasePrd.tasks) {
+        if (task.status === 'failed') { task.status = 'pending'; task.error = null; }
+      }
+      writeJSON(nextPhase.prdFile, phasePrd);
+    } else {
+      nextPhase.status = 'failed';
+      console.error(`Phase ${nextPhase.phase} failed after 2 retries`);
+    }
+  } else {
+    nextPhase.status = 'completed';
+  }
+
+  prd._sectionSplit.currentPhase = nextPhase.phase;
+  writeJSON('.ralph/prd.json', prd);
+
+  // → Skip to section C (commit PRD state), then D (loop back)
+  goto COMMIT_PRD;
+}
+```
+
+> **IMPORTANT:** When `_sectionSplit.enabled`, the standard category-based batching (section A below)
+> is SKIPPED. The loop delegates per-phase to apex instead of per-category-batch.
+
+---
+
+## A. Find Eligible Tasks
+
+> **Note:** This section is SKIPPED when `prd._sectionSplit?.enabled` (handled by A0 above).
+
+```javascript
 const MAX_RETRIES = 3;
 
 // RETRY: Reset failed tasks to pending if retries remain (max 3 attempts per task)
@@ -115,7 +198,7 @@ writeJSON('.ralph/prd.json', prd);
 Apex handles everything for the current module:
 - Reads PRD, extracts context (context_code, app_name, module_code, entities, sections)
 - Executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
-- Runs full POST-CHECKs (43 checks from `references/post-checks.md`)
+- Runs full POST-CHECKs (50 checks from `references/post-checks.md`)
 - Commits per layer (atomic commits)
 - Validates with MCP (`validate_conventions`)
 - Updates task statuses in the PRD file directly