@atlashub/smartstack-cli 3.22.0 → 3.24.0

package/templates/skills/apex/references/smartstack-layers.md

@@ -17,8 +17,9 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
-- Inherit `AuditableEntity`, implement `IHasData` for multi-tenant
-- Audit fields: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy
+- Inherit `BaseEntity`, implement `ITenantEntity` + `IAuditableEntity`
+- See `references/smartstack-api.md` for exact BaseEntity API (Id, CreatedAt, UpdatedAt only)
+- No Code/IsDeleted/RowVersion in BaseEntity — add business properties yourself
 - Domain events for state changes
 - Value objects for composite values
 
@@ -49,7 +50,8 @@
 
 ## Layer 1 — Application (parallel with API)
 
-**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/`
+**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/` (interface)
+**Service impls:** `Infrastructure/Services/{ContextPascal}/{App}/{Module}/` (implementation)
 **DTOs:** `Application/DTOs/{ContextPascal}/{App}/{Module}/`
 **Validators:** `Application/Validators/{ContextPascal}/{App}/{Module}/`
 
@@ -60,10 +62,13 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
+- **ALL services MUST inject `ICurrentUser` and filter by `TenantId`** (see `smartstack-api.md` Service Pattern)
+- **ALL services MUST inject `ILogger<T>`** for production diagnostics
 - CQRS with MediatR
 - FluentValidation for all commands
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
+- **FORBIDDEN:** `tenantId: Guid.Empty`, queries without TenantId filter, services without ICurrentUser
 
 ---
 
@@ -96,40 +101,107 @@
 
 **Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`
 
+> **Detailed templates:** See ralph-loop `references/core-seed-data.md` for complete C# code templates.
+> Navigation hierarchy: Context → Application → Module → Section → Resource (ALL levels need seed data).
+
 | Action | Tool |
 |--------|------|
 | Generate permissions | MCP `generate_permissions` (PRIMARY) |
-| Navigation seed | Template below |
-| Roles seed | Template below |
-| Provider | Template below |
-
-### Seed Data Chain (5 files)
-
-1. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages
-2. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
-3. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
-4. **SeedConstants.cs** — Shared deterministic GUIDs
-5. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
-   - SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
+| Navigation seed | Templates below |
+| Roles seed | Templates below |
+| Provider | Templates below |
+
+### Seed Data Chain (7 files minimum)
+
+1. **NavigationApplicationSeedData.cs** — Application-level navigation entry (MUST be first)
+2. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages (fr, en, it, de)
+3. **NavigationSectionSeedData.cs** — Section-level navigation (if sections defined)
+4. **NavigationResourceSeedData.cs** — Resource-level navigation (if resources defined)
+5. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
+6. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
+7. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
+   - `SeedNavigationAsync()` — seeds Application → Module → Section → Resource + translations
+   - `SeedPermissionsAsync()` + `SeedRolePermissionsAsync()`
    - DI: `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()`
 
+### Deterministic GUID Pattern
+
+```csharp
+// Use SHA256 for deterministic GUIDs (reproducible across environments)
+public static readonly Guid ModuleId = GenerateDeterministicGuid("nav-module-{app}-{module}");
+
+private static Guid GenerateDeterministicGuid(string input)
+{
+    var hash = System.Security.Cryptography.SHA256.HashData(
+        System.Text.Encoding.UTF8.GetBytes(input));
+    var bytes = new byte[16];
+    Array.Copy(hash, bytes, 16);
+    return new Guid(bytes);
+}
+```
+
+### Route Convention (CRITICAL — Full Paths Required)
+
+> **Routes stored in DB drive the platform menu AND application-tracking.**
+> Short routes (e.g., `humanresources`) cause **400 Bad Request** on every page navigation.
+
+**Route format: `/{context}/{app-kebab}/{module-kebab}/{section-kebab}`**
+
+| Level | Code (C#) | Route (DB) |
+|-------|-----------|-----------|
+| Application | `humanresources` | `/business/human-resources` |
+| Module | `employees` | `/business/human-resources/employees` |
+| Section | `departments` | `/business/human-resources/employees/departments` |
+| Resource | `export` | `/business/human-resources/employees/departments/export` |
+
+**Platform examples (verified from SmartStack.app):**
+- `/platform/administration` (not `administration`)
+- `/platform/administration/users` (not `users`)
+- `/personal/myspace/profile` (not `profile`)
+
+- PascalCase for C# code identifiers (`HumanResources`)
+- **kebab-case** for ALL URL routes in seed data (`human-resources`)
+- **Routes MUST start with `/`** and include full parent hierarchy
+- Helper: `ToKebabCase()` transforms PascalCase → kebab-case
+
+```csharp
+private static string ToKebabCase(string value)
+    => System.Text.RegularExpressions.Regex.Replace(value, "(?<!^)([A-Z])", "-$1").ToLowerInvariant();
+
+// Route construction:
+var appRoute = $"/{ToKebabCase(contextCode)}/{ToKebabCase(appCode)}";
+// → "/business/human-resources"
+
+var moduleRoute = $"{appRoute}/{ToKebabCase(moduleCode)}";
+// → "/business/human-resources/employees"
+
+var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
+// → "/business/human-resources/employees/departments"
+```
+
 **FORBIDDEN:**
 - `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
 - Missing translations (must have fr, en, it, de)
 - Empty seed classes with no seeding logic
+- PascalCase in route URLs → always kebab-case
+- Missing NavigationApplicationSeedData → menu invisible
+- **Short routes without `/` prefix** → `"humanresources"` must be `"/business/human-resources"`
+- **Routes without parent hierarchy** → `"employees"` must be `"/business/human-resources/employees"`
 
 ---
 
 ## Layer 2 — Frontend (parallel with I18n)
 
+> **Detailed patterns:** See `references/smartstack-frontend.md` for complete code templates.
+
 **Pages:** `src/pages/{ContextPascal}/{AppPascal}/{Module}/`
 **Components:** `src/components/{Module}/`
 
 | Action | Tool |
 |--------|------|
 | API client | MCP `scaffold_api_client` |
-| Routes | MCP `scaffold_routes` |
-| Complex pages | /ui-components skill |
+| Routes | MCP `scaffold_routes` (outputFormat: `clientRoutes`) |
+| Complex pages | /ui-components skill + `smartstack-frontend.md` patterns |
 | Validate routes | MCP `validate_frontend_routes` |
 
 **Layout mapping:**
@@ -140,21 +212,95 @@
 | `business.*` | `BusinessLayout` | `/business` |
 | `personal.*` | `UserLayout` | `/personal/myspace` |
 
+### Lazy Loading (MANDATORY)
+
+ALL page components MUST be lazy-loaded using `React.lazy()`:
+
+```tsx
+const EmployeesPage = lazy(() =>
+  import('@/pages/Business/HumanResources/Employees/EmployeesPage')
+    .then(m => ({ default: m.EmployeesPage }))
+);
+
+// Route element — ALWAYS wrap with Suspense
+element: <Suspense fallback={<PageLoader />}><EmployeesPage /></Suspense>
+```
+
+### Page Structure Pattern
+
+All pages MUST follow: hooks → useEffect(load) → loading state → error state → content.
+
+```tsx
+// 1. Hooks at top
+const { t } = useTranslation(['{module}']);
+// 2. State
+const [loading, setLoading] = useState(true);
+// 3. useCallback + useEffect for data loading
+// 4. if (loading) return <Loader2 spinner />
+// 5. if (error) return <error UI with retry>
+// 6. return <content with CSS variables>
+```
+
+### Components & CSS
+
 **Components:** SmartTable, SmartFilter, EntityCard, SmartForm, StatCard (NEVER raw HTML)
-**CSS:** Variables only → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
+**CSS:** Variables only → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`, `border-[var(--border-color)]`
+**Loader:** `Loader2` from `lucide-react` for spinners, `PageLoader` for Suspense fallback
+
+### FK Fields in Forms (CRITICAL)
+
+Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST use the `EntityLookup` component — NEVER a plain text input. Users cannot type GUIDs manually.
+
+```tsx
+// CORRECT — EntityLookup for FK field
+<EntityLookup
+  apiEndpoint="/api/business/human-resources/employees"
+  value={formData.employeeId}
+  onChange={(id) => handleChange('employeeId', id)}
+  label={t('module:form.employee', 'Employee')}
+  mapOption={(item) => ({ id: item.id, label: item.name, sublabel: item.code })}
+  required
+/>
+
+// WRONG — plain text input for FK GUID
+<input type="text" value={formData.employeeId} placeholder="Enter employee ID" />
+```
+
+**Backend requirement:** Each target entity's GetAll endpoint MUST accept `?search=` parameter. See `smartstack-api.md` Service Pattern.
+
+See `references/smartstack-frontend.md` section 6 for the full `EntityLookup` component definition and usage patterns.
 
 **FORBIDDEN:**
 - `src/pages/{Module}/` (flat, missing Context/App)
 - `import axios` → use `@/services/api/apiClient`
 - `<table>` → use SmartTable
-- Hardcoded colors → use CSS variables
+- `<input type="text">` for FK Guid fields → use `EntityLookup`
+- Placeholder "Enter ID" or "Enter GUID" → use `EntityLookup`
+- Hardcoded Tailwind colors (`bg-white`, `text-gray-900`) → use CSS variables
+- Static page imports in route files → use `React.lazy()`
+- `<Suspense>` without `fallback` prop
 - Only fr/en → MUST have 4 languages
+- `t('key')` without namespace prefix → use `t('ns:key', 'fallback')`
+- Hardcoded user-facing strings in JSX → use `t()`
 
 ---
 
 ## Layer 2 — I18n
 
-4 JSON files: fr, en, it, de — identical key structures.
+> **Template:** See `references/smartstack-frontend.md` Section 2 for complete JSON template.
+
+4 JSON files per module namespace: fr, en, it, de — identical key structures.
+
+**Location:** `src/i18n/locales/{lang}/{module}.json`
+
+**Required keys:** `title`, `description`, `actions`, `labels`, `columns`, `form`, `errors`, `validation`, `messages`, `empty`
+
+**Usage pattern:**
+```tsx
+const { t } = useTranslation(['{module}']);
+t('{module}:title', 'Module Title')           // ALWAYS with fallback
+t('{module}:actions.create', 'Create entity') // ALWAYS with namespace prefix
+```
 
 ---
 

package/templates/skills/apex/steps/step-00-init.md

@@ -7,6 +7,14 @@ next_step: steps/step-01-analyze.md
 
 # Step 0: Initialize
 
+**Before anything else**, display the version banner:
+
+```
+═══════════════════════════════════════════════════════════════
+  SmartStack APEX — v{{SMARTSTACK_VERSION}}
+═══════════════════════════════════════════════════════════════
+```
+
 ## LOAD SHARED
 
 Read `_shared.md` for SmartStack detection patterns and MCP tools reference.
@@ -133,20 +141,25 @@ IF save_mode:
 ## 7. Display Context Summary
 
 ```
-**APEX SmartStack - Initialization Complete**
-
-**Task:** {task_description}
-**Context:** {context_code} / {app_name} / {module_code}
-**Sections:** {sections}
-
-**Sources:**
-- PRD: {prd_path || "none"}
-- Feature: {feature_path || "none"}
-
-**Flags:** {active_flags}
-**MCP:** {available|degraded}
-**Needs migration:** {yes|no}
-**Needs seed data:** {yes|no}
+═══════════════════════════════════════════════════════════════
+  APEX INITIALIZATION COMPLETE
+  SmartStack CLI v{{SMARTSTACK_VERSION}}
+═══════════════════════════════════════════════════════════════
+
+| Field              | Value                                        |
+|--------------------|----------------------------------------------|
+| Task               | {task_description}                            |
+| Context            | {context_code} / {app_name} / {module_code}  |
+| Sections           | {sections}                                   |
+| PRD                | {prd_path || "none"}                          |
+| Feature            | {feature_path || "none"}                     |
+| Flags              | {active_flags}                               |
+| MCP                | {available|degraded}                         |
+| Needs migration    | {yes|no}                                     |
+| Needs seed data    | {yes|no}                                     |
+
+NEXT STEP: step-01-analyze
+═══════════════════════════════════════════════════════════════
 ```
 
 ---

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

@@ -12,10 +12,28 @@ next_step: steps/step-02-plan.md
 
 ## LOAD CONDITIONALLY
 
+- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
 - If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
 
 ---
 
+## 0. Fresh Project Detection (Early Exit)
+
+```
+IF .smartstack/init-state.json exists:
+  Read it → check if project was recently initialized
+  Glob("src/**/Entities/**/*.cs") → count entity files
+
+  IF entity count == 0 AND no PRD AND no feature.json:
+    → SKIP full code exploration (sections 2-3)
+    → Declare: "Fresh project — all elements need to be CREATED"
+    → Jump directly to section 4 (Gap Analysis) with all items marked "create"
+```
+
+This saves ~2 minutes of Glob searches on an empty project.
+
+---
+
 ## 1. Context Sources
 
 Read available context (in order of priority):
@@ -118,7 +136,31 @@ Identify:
 
 ---
 
-## 4. Gap Analysis
+## 4. FK Field Detection
+
+For each entity found (or to be created), identify FK relationships:
+
+```
+For each entity in analysis results:
+  - List properties ending in "Id" with a matching navigation property (e.g., EmployeeId + Employee)
+  - Record: { fkProperty, targetEntity, isRequired }
+
+Output:
+  fkFields: [
+    { entity: "TimeEntry", fkProperty: "EmployeeId", targetEntity: "Employee", isRequired: true },
+    { entity: "TimeEntry", fkProperty: "ProjectId", targetEntity: "Project", isRequired: true }
+  ]
+```
+
+**Why:** FK fields drive two critical downstream requirements:
+1. **Frontend:** Each FK field MUST use `EntityLookup` component (NEVER plain text input for GUIDs)
+2. **Backend:** Each target entity's GetAll endpoint MUST support `?search=` query parameter
+
+These are propagated to step-02 (plan) and step-03 (execute).
+
+---
+
+## 5. Gap Analysis
 
 Compare what EXISTS vs what the TASK REQUIRES:
 
@@ -131,7 +173,7 @@ For each element in the task description:
 
 ---
 
-## 5. Analysis Summary
+## 6. Analysis Summary
 
 ```
 **APEX SmartStack - Analysis Complete**
@@ -158,7 +200,7 @@ For each element in the task description:
 
 ---
 
-## 6. Save Output (if save_mode)
+## 7. Save Output (if save_mode)
 
 Write to `{output_dir}/01-analyze.md` with analysis results.
 

package/templates/skills/apex/steps/step-02-plan.md

@@ -63,9 +63,13 @@ For EACH file in the plan, specify HOW it will be created/modified:
 | # | File | Action | Tool |
 |---|------|--------|------|
 | 10 | src/pages/{Ctx}/{App}/{Mod}/ListPage.tsx | create | /ui-components skill |
+| 10b | src/pages/{Ctx}/{App}/{Mod}/CreatePage.tsx | create | /ui-components skill (EntityLookup for FK fields) |
+| 10c | src/pages/{Ctx}/{App}/{Mod}/EditPage.tsx | create | /ui-components skill (EntityLookup for FK fields) |
 | 11 | src/services/api/{module}Api.ts | create | MCP scaffold_api_client |
 | 12 | src/routes/{module}.tsx | create | MCP scaffold_routes |
-| 13 | src/locales/fr/{module}.json | create | manual (4 languages) |
+| 13 | src/i18n/locales/{lang}/{module}.json | create | ref smartstack-frontend.md (4 languages: fr, en, it, de) |
+
+**FK Field Guidance:** If step-01 identified `fkFields[]`, every Create/Edit page MUST use `EntityLookup` for those fields (see `smartstack-frontend.md` section 6). The corresponding backend GetAll endpoints (Layer 1) MUST support `?search=` parameter.
 
 ### Layer 3 — Tests (sequential, if -t)
 

package/templates/skills/apex/steps/step-03-execute.md

@@ -13,6 +13,8 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 
 ## LOAD CONDITIONALLY
 
+- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
+- **ALWAYS** read `references/smartstack-frontend.md` — lazy loading, i18n, page structure, CSS variables
 - Read `references/smartstack-layers.md` for execution rules per layer
 - If NOT `{economy_mode}` AND Layer 1 has parallel work: read `references/agent-teams-protocol.md`
 
@@ -25,7 +27,8 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 ```
 For each entity to create/modify:
   → MCP scaffold_extension (type: "entity", target: entity_name)
-  → Verify: inherits AuditableEntity, has IHasData if multi-tenant
+  → Verify: inherits BaseEntity, implements ITenantEntity + IAuditableEntity
+  → Verify entity matches patterns in references/smartstack-api.md
 ```
 
 ### EF Core Configurations
@@ -43,7 +46,7 @@ For each entity:
 1. MCP suggest_migration → get standardized name
 2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
 3. dotnet ef database update (if local DB)
-4. dotnet build --no-restore → MUST PASS
+4. dotnet build → MUST PASS
 ```
 
 **BLOCKING:** If build fails after migration, fix EF configs before proceeding.
@@ -51,10 +54,10 @@ For each entity:
 ### Post-Layer 0 Build Gate
 
 ```bash
-dotnet build --no-restore
+dotnet build
 ```
 
-**MUST PASS before Layer 1. If failure, fix and retry.**
+**MUST PASS before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.**
 
 ---
 
@@ -64,6 +67,18 @@ dotnet build --no-restore
 
 Execute each item from the plan sequentially using skills and MCP.
 
+**For frontend tasks (economy_mode):** Follow the same rules as exec-frontend above:
+- `MCP scaffold_api_client` → API client + types + React Query hook
+- `MCP scaffold_routes` with `outputFormat: 'clientRoutes'` for lazy imports
+- Pages: use `/ui-components` skill — MANDATORY for entity lists, grids, tables, dashboards
+- **Form pages: Create `EntityCreatePage.tsx` (route: `/create`) and `EntityEditPage.tsx` (route: `/:id/edit`)**
+- **FK FIELDS (CRITICAL):** Any Guid FK property (e.g., EmployeeId, DepartmentId) MUST use `EntityLookup` component — NEVER a plain text input. See `smartstack-frontend.md` section 6.
+- **ZERO modals/popups/drawers for forms — ALL forms are full pages with their own URL**
+- **Form tests: Generate `EntityCreatePage.test.tsx` and `EntityEditPage.test.tsx` (co-located)**
+- Read `references/smartstack-frontend.md` for mandatory patterns (sections 3b + 8)
+- Generate i18n JSON files for all 4 languages (fr, en, it, de) — `src/i18n/locales/{lang}/{module}.json`
+- All pages must follow loading → error → content pattern with CSS variables
+
 ### If NOT economy_mode: Agent Teams (parallel)
 
 > **Protocol:** See `references/agent-teams-protocol.md`
@@ -80,6 +95,7 @@ Spawn 2 teammates (Opus, full tools):
     For each task:
     - Application services/DTOs: MCP scaffold_extension
     - Controllers: use /controller skill for complex, MCP scaffold_extension for simple
+    - IMPORTANT: ALL GetAll endpoints MUST support ?search= query parameter (enables EntityLookup on frontend)
     - Seed data: MCP generate_permissions, then follow smartstack-layers.md templates
 
     After ALL tasks done:
@@ -89,11 +105,37 @@ Spawn 2 teammates (Opus, full tools):
    "Execute these Layer 1 frontend tasks for module {module_code}:
     {list of frontend + i18n tasks from plan}
 
+    **MANDATORY: Read references/smartstack-frontend.md FIRST** — contains all required patterns.
+
     For each task:
     - API client: MCP scaffold_api_client
-    - Routes: MCP scaffold_routes
-    - Pages: use /ui-components skill
-    - I18n: 4 languages (fr, en, it, de)
+    - Routes: MCP scaffold_routes (outputFormat: 'clientRoutes') → generates lazy imports + Suspense
+    - Pages: use /ui-components skill — MUST follow smartstack-frontend.md patterns:
+      → React.lazy() for all page imports (named export wrapping)
+      → <Suspense fallback={<PageLoader />}> around all lazy components
+      → Page structure: hooks → useEffect(load) → loading → error → content
+      → CSS variables only: bg-[var(--bg-card)], text-[var(--text-primary)]
+      → SmartTable/SmartFilter/EntityCard (NEVER raw HTML)
+    - **FORM PAGES (CRITICAL):** Create/Edit forms are FULL PAGES with own routes:
+      → EntityCreatePage.tsx with route /{module}/create
+      → EntityEditPage.tsx with route /{module}/:id/edit
+      → ZERO modals/popups/drawers/dialogs for forms
+      → Back button with navigate(-1) on every form page
+      → See smartstack-frontend.md section 3b for templates
+    - **FK FIELDS (CRITICAL):** Foreign key Guid fields (e.g., EmployeeId) MUST use EntityLookup:
+      → NEVER render FK fields as plain text inputs — users cannot type GUIDs
+      → Use EntityLookup from @/components/ui/EntityLookup for searchable selection
+      → Each FK field needs: apiEndpoint, mapOption (display name), search support on backend
+      → See smartstack-frontend.md section 6 for the full EntityLookup pattern
+    - **FORM TESTS (MANDATORY):**
+      → EntityCreatePage.test.tsx (co-located next to page)
+      → EntityEditPage.test.tsx (co-located next to page)
+      → Cover: rendering, validation, submit, pre-fill, navigation, errors
+      → See smartstack-frontend.md section 8 for test templates
+    - I18n: Generate 4 JSON files per module namespace (fr, en, it, de)
+      → Follow JSON template from smartstack-frontend.md
+      → Keys: actions, labels, errors, validation, columns, form, messages, empty
+      → ALL t() calls MUST use namespace prefix + fallback: t('ns:key', 'Default text')
     - MUST use src/pages/{Context}/{App}/{Module}/ hierarchy (NOT flat)
 
     After ALL tasks done:
@@ -102,7 +144,7 @@ Spawn 2 teammates (Opus, full tools):
 Wait for both teammates to report completion.
 
 Build verification:
-  dotnet build --no-restore  (backend)
+  dotnet build  (backend)
   npm run typecheck           (frontend, if applicable)
 
 shutdown_request → shutdown_response → TeamDelete("apex-exec")
@@ -136,7 +178,7 @@ After Layer 1 completes:
    - DI registration added
 
 2. Build gate:
-   dotnet build --no-restore → MUST PASS
+   dotnet build → MUST PASS
    npm run typecheck → MUST PASS (if frontend)
 ```