@atlashub/smartstack-cli 4.75.0 → 4.79.0

package/templates/skills/apex-verify/steps/step-01-nav-audit.md

@@ -0,0 +1,96 @@
+---
+name: step-01-nav-audit
+description: Audit navigation seed data for reserved section codes appearing as menu items
+next_step: steps/step-02-crud-audit.md
+---
+
+# Step 1: Navigation Audit
+
+## YOUR TASK:
+Scan all navigation seed data files for sections with reserved codes that should NOT appear as sidebar menu items.
+
+## RESERVED SECTION CODES:
+```
+RESERVED = ["detail", "create", "edit"]
+```
+These are internal route targets (/:id, /create, /:id/edit), NOT sidebar menu items.
+Any section with one of these codes — or containing "detail" (e.g., "department-detail") — must NOT be a visible menu entry.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Scan Navigation Seed Data
+
+For each file in {seed_files}:
+
+**1a. Extract all section entries**
+
+Use Grep to find section definitions. Two patterns to check:
+
+Pattern A — SectionData record array:
+```csharp
+new("detail", "/path/:id", "icon", 4, (...))
+```
+→ Grep for `new\s*\("([^"]+)"` in SectionData arrays
+
+Pattern B — NavigationSectionSeedEntry objects:
+```csharp
+Code = "detail",
+```
+→ Grep for `Code\s*=\s*"([^"]+)"`
+
+**1b. Check each section code against RESERVED list**
+
+For each extracted section code:
+- If code == "detail" OR code == "create" OR code == "edit" → **BLOCKING finding**
+- If code contains "-detail" (e.g., "department-detail") → **BLOCKING finding**
+- Check if `IsActive = false` is set nearby (within 10 lines) — if so, downgrade to WARNING (it's hidden but still seeded, which is acceptable)
+
+### 2. Check Route Patterns
+
+For each section route in seed data:
+- Route ending with `/:id` that is NOT the "list" section's detail route → WARNING (may be a separate detail section that should be merged)
+- Route containing `/detail/` or `/create/` or `/edit/` as segments → **BLOCKING** (forbidden patterns per SmartStack convention)
+
+### 3. Record Findings
+
+For each issue found, create a finding:
+
+```
+{
+  id: "NAV-001",       // Sequential per category
+  severity: "BLOCKING",
+  category: "Navigation",
+  file: "EmployeesNavigationSeedData.cs",
+  line: 25,
+  message: "Reserved section code 'detail' is seeded as a visible menu item",
+  fix: "Remove this section entry from the Sections[] array. Detail routes are resolved by DynamicRouter convention (/:id under list section)."
+}
+```
+
+### Finding IDs:
+
+| ID | Severity | Rule |
+|----|----------|------|
+| NAV-001 | BLOCKING | Reserved section code (detail/create/edit) seeded as menu item |
+| NAV-002 | BLOCKING | Section code contains "-detail" (e.g., department-detail) seeded as menu item |
+| NAV-003 | BLOCKING | Route contains forbidden segment (/detail/, /create/, /edit/) |
+| NAV-004 | WARNING | Reserved section code with IsActive = false (acceptable but unnecessary) |
+| NAV-005 | WARNING | Section code not in kebab-case |
+| NAV-006 | WARNING (v3.46) | `ApplicationZone` enum referenced in seed data — must use `IsPersonal`/`IsOpen` flags (cf. seed-checks.sh check **C66**, will become BLOCKING in v3.47) |
+| NAV-007 | WARNING (v3.46) | Legacy layouts `AdminLayout`/`BusinessLayout`/`UserLayout`/`HRLayout`/`SalesLayout` referenced — must use `AppLayout` (cf. seed-checks.sh check **C67**, will become BLOCKING in v3.47) |
+
+**Note** : NAV-006 and NAV-007 mirror the bash post-checks **C66**/**C67** in `apex/references/checks/seed-checks.sh`. The bash checks emit `WARNING` (no FAIL) during the v3.46 grace period — apex-verify should align with the same severity.
+
+---
+
+## SUCCESS METRICS:
+- All NavigationSeedData files scanned
+- Every section code checked against reserved list
+- Every route checked for forbidden patterns
+- Findings recorded with file:line evidence
+
+## NEXT STEP:
+If {scope} is `all` or `crud` → proceed to `./step-02-crud-audit.md`
+If {scope} is `nav` → skip to `./step-05-report.md`

package/templates/skills/apex-verify/steps/step-02-crud-audit.md

@@ -0,0 +1,127 @@
+---
+name: step-02-crud-audit
+description: Audit CRUD completeness - 4 page types per section, create buttons, componentRegistry
+next_step: steps/step-03-perm-audit.md
+---
+
+# Step 2: CRUD Audit
+
+## YOUR TASK:
+Verify that every section in the application has complete CRUD support: 4 page types, create button on list pages, and proper componentRegistry registration.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Identify Sections to Audit
+
+From {seed_files}, extract all section codes that represent CRUD entities.
+
+**Exclude from audit:**
+- Sections with code: "dashboard", "calendar", "import-export", "approve", "balances" (these are specialized views, not CRUD entities)
+- Sections with reserved codes: "detail", "create", "edit" (these shouldn't exist as sections)
+
+**Include in audit:**
+- "list" sections → audit as the main entity section
+- "departments", "absence-types", or any other entity section → audit for CRUD completeness
+
+For each auditable section, determine the entity name:
+- Section code → PascalCase entity name (e.g., "departments" → "Department", "absence-types" → "AbsenceType")
+
+### 2. Check 4 Page Types per Section
+
+For each entity, search in {page_files} for:
+
+```
+Required page types (at least 3 naming conventions per type):
+  ListPage:   {Entity}ListPage.tsx OR {Entity}sPage.tsx OR {Entities}Page.tsx
+  DetailPage: {Entity}DetailPage.tsx OR {Entity}Page.tsx
+  CreatePage: Create{Entity}Page.tsx OR {Entity}CreatePage.tsx OR {Entity}FormPage.tsx
+  EditPage:   Edit{Entity}Page.tsx OR {Entity}EditPage.tsx OR {Entity}FormPage.tsx (shared)
+```
+
+Note: Create and Edit may share a single `{Entity}FormPage.tsx` — this is acceptable.
+
+**Findings:**
+
+| ID | Severity | Rule |
+|----|----------|------|
+| CRUD-001 | BLOCKING | ListPage missing for entity |
+| CRUD-002 | BLOCKING | DetailPage missing for entity |
+| CRUD-003 | BLOCKING | Create/Edit page missing for entity (no CreatePage, EditPage, or FormPage) |
+
+### 3. Check Create Button on List Pages
+
+For each ListPage found:
+
+Grep for navigate patterns:
+```
+navigate('create')
+navigate(`create`)
+navigate('new')
+navigate(`${basePath}/create`)
+navigate(`create`)
+```
+
+Also check for link patterns:
+```
+<Link to="create"
+to={`create`}
+to="new"
+```
+
+If NONE found → **BLOCKING finding** (users cannot access create form)
+
+| ID | Severity | Rule |
+|----|----------|------|
+| CRUD-004 | BLOCKING | ListPage has no Create/New button (no navigate to create route) |
+
+### 4. Check componentRegistry Registration
+
+Read {registry_file} and extract all `PageRegistry.register()` calls.
+
+For each entity section:
+- Check for list page registration: key matching `*.{section}` or `*.{module}.{section}`
+- Check for detail page registration: key matching `*.{section}.detail` or the `:id` route
+- Check for create page registration: key matching `*.{section}.create`
+- Check for edit page registration: key matching `*.{section}.edit`
+
+| ID | Severity | Rule |
+|----|----------|------|
+| CRUD-005 | BLOCKING | Page exists on disk but NOT registered in componentRegistry |
+| CRUD-006 | WARNING | componentRegistry entry has no matching page file on disk |
+
+### 5. Check Form Submit Handlers
+
+For each Create/Edit/Form page:
+
+Grep for submit patterns:
+```
+onSubmit
+handleSubmit
+api.create(
+api.post(
+api.update(
+api.put(
+apiClient.post(
+apiClient.put(
+```
+
+If NONE found → WARNING (form exists but may not submit data)
+
+| ID | Severity | Rule |
+|----|----------|------|
+| CRUD-007 | WARNING | Form page has no visible submit handler |
+
+---
+
+## SUCCESS METRICS:
+- All entity sections identified from seed data
+- 4 page types checked per entity
+- Create button presence verified on all list pages
+- componentRegistry cross-referenced with page files
+- Form submit handlers checked
+
+## NEXT STEP:
+If {scope} is `all` or `perm` → proceed to `./step-03-perm-audit.md`
+If {scope} is `crud` → skip to `./step-05-report.md`

package/templates/skills/apex-verify/steps/step-03-perm-audit.md

@@ -0,0 +1,119 @@
+---
+name: step-03-perm-audit
+description: Cross-reference permissions between controllers, Permissions.cs, seed data, and roles
+next_step: steps/step-04-route-audit.md
+---
+
+# Step 3: Permission Audit
+
+## YOUR TASK:
+Cross-reference permissions across 4 sources to ensure complete coverage:
+1. Controller `[RequirePermission]` attributes → what the API enforces
+2. `Permissions.cs` static constants → what the code defines
+3. `PermissionsSeedData` → what gets seeded to the database
+4. `RolesSeedData` → what roles have which permissions
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Extract Controller Permissions
+
+For each file in {controller_files}:
+
+Grep for `[RequirePermission(` and extract the permission string:
+```csharp
+[RequirePermission(Permissions.Employees.Read)]
+[RequirePermission(Permissions.AbsenceManagement.Create)]
+```
+
+Build a set: `{controller_permissions}` = all unique permission references.
+
+Also note which controller and HTTP method uses each permission (for context in findings).
+
+### 2. Extract Permissions.cs Constants
+
+Read {permissions_file} and extract all `public const string` values:
+```csharp
+public const string Read = "human-resources.employees.read";
+public const string Wildcard = "human-resources.employees.*";
+```
+
+Build a set: `{defined_permissions}` = all permission path strings.
+Also track the constant name → path mapping.
+
+### 3. Extract Seed Data Permissions
+
+For each file in {perm_seed_files}:
+
+Grep for permission path patterns:
+```csharp
+Path = "human-resources.employees.read"
+new PermissionSeedEntry { ... Path = "..." }
+"human-resources.employees.read"  // in HasData() or SeedPermissionsAsync
+```
+
+Build a set: `{seeded_permissions}` = all permission paths in seed data.
+
+### 4. Extract Role Mappings
+
+For each file in {role_seed_files}:
+
+Grep for role-permission associations. Look for patterns:
+```csharp
+// Role assignment patterns
+new { RoleId = ..., PermissionId = ... }
+SeedRolePermissionsAsync
+rolePermissions.Add(...)
+```
+
+Build a map: `{role_mappings}` = { permission_path: [role_names] }
+
+### 5. Cross-Reference Matrix
+
+**Check A: Controllers → Permissions.cs**
+For each permission in {controller_permissions}:
+- Verify it resolves to a constant in {defined_permissions}
+- If missing → BLOCKING (controller references undefined permission)
+
+**Check B: Permissions.cs → Seed Data**
+For each permission in {defined_permissions} (excluding wildcards):
+- Verify it exists in {seeded_permissions}
+- If missing → BLOCKING (permission defined but never seeded = always 403)
+
+**Check C: Seed Data → Roles**
+For each permission in {seeded_permissions}:
+- Verify it has at least one role mapping in {role_mappings}
+- If missing → CRITICAL (permission seeded but no role has it = always 403)
+
+**Check D: Admin Role Wildcard**
+- Verify admin role has wildcard (`*`) permissions for each module
+- If missing → CRITICAL (admin cannot access module)
+
+**Check E: Role Matrix Sanity**
+- Viewer role must NOT have write permissions (create, update, delete)
+- Admin must have wildcard or all individual permissions
+
+### 6. Record Findings
+
+| ID | Severity | Rule |
+|----|----------|------|
+| PERM-001 | BLOCKING | Controller uses permission not defined in Permissions.cs |
+| PERM-002 | BLOCKING | Permissions.cs constant not seeded in PermissionsSeedData |
+| PERM-003 | CRITICAL | Seeded permission has no role mapping (always 403 for all users) |
+| PERM-004 | CRITICAL | Admin role missing wildcard for module |
+| PERM-005 | WARNING | Permission path segments not in kebab-case |
+| PERM-006 | WARNING | Viewer role has write permission (create/update/delete) |
+| PERM-007 | WARNING | Permission defined in Permissions.cs but unused by any controller (dead code) |
+
+---
+
+## SUCCESS METRICS:
+- All 4 sources extracted completely
+- Cross-reference matrix fully evaluated
+- Role matrix sanity checked
+- Findings recorded with file:line evidence
+
+## NEXT STEP:
+If {scope} is `all` or `route` → proceed to `./step-04-route-audit.md`
+If {scope} is `perm` → skip to `./step-05-report.md`

package/templates/skills/apex-verify/steps/step-04-route-audit.md

@@ -0,0 +1,98 @@
+---
+name: step-04-route-audit
+description: Verify route alignment between navigation seed data, componentRegistry, and controllers
+next_step: steps/step-05-report.md
+---
+
+# Step 4: Route Audit
+
+## YOUR TASK:
+Verify that routes are consistent across 3 sources: navigation seed data, componentRegistry (PageRegistry), and backend controllers (NavRoute attributes).
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Extract Seed Data Routes
+
+From {seed_files}, extract all section routes:
+```
+{seed_routes} = [
+  { code: "departments", route: "/human-resources/employees/departments", file: "...", line: N },
+  { code: "list", route: "/human-resources/employees", file: "...", line: N },
+  ...
+]
+```
+
+### 2. Extract PageRegistry Keys
+
+From {registry_file}, extract all `PageRegistry.register()` calls:
+```typescript
+PageRegistry.register('human-resources.employees.departments', ...)
+PageRegistry.register('human-resources.employees', ...)
+```
+
+Build: `{registry_keys}` = all registered page keys.
+
+### 3. Extract Controller NavRoutes
+
+From {controller_files}, extract `[NavRoute("...")]` attributes:
+```csharp
+[NavRoute("human-resources.employees")]
+[NavRoute("human-resources.employees.departments")]
+```
+
+Build: `{controller_navroutes}` = all NavRoute values.
+
+### 4. Cross-Reference
+
+**Check A: Seed Routes → PageRegistry**
+For each seed route (excluding reserved sections and /:id routes):
+- Convert route to PageRegistry key: `/human-resources/employees/departments` → `human-resources.employees.departments`
+- Verify key exists in {registry_keys}
+- If missing → BLOCKING (seed route has no frontend page)
+
+**Check B: Controller NavRoutes → Seed Data**
+For each NavRoute:
+- Convert to route path: `human-resources.employees` → `/human-resources/employees`
+- Verify exists in seed data routes
+- If missing → WARNING (controller exists but no navigation entry)
+
+**Check C: PageRegistry → Page Files**
+For each registry entry:
+- Verify the imported component file exists on disk
+- If missing → BLOCKING (registry references non-existent page)
+
+**Check D: Orphan Pages**
+For each page file in {page_files}:
+- Check if it's registered in componentRegistry
+- If NOT registered → WARNING (page exists but has no route — unreachable)
+
+**Check E: DynamicRouter Convention Routes**
+For each section with a list page:
+- Verify these implicit routes are handled (either by registry or DynamicRouter convention):
+  - `{section}/:id` → detail page
+  - `{section}/create` → create page
+  - `{section}/:id/edit` → edit page
+- Note: DynamicRouter may resolve these by convention without explicit registry entries. Only flag if BOTH registry AND convention are missing.
+
+### 5. Record Findings
+
+| ID | Severity | Rule |
+|----|----------|------|
+| ROUTE-001 | BLOCKING | Seed data route has no matching PageRegistry entry |
+| ROUTE-002 | WARNING | Controller NavRoute has no matching seed data entry |
+| ROUTE-003 | BLOCKING | PageRegistry references non-existent page file |
+| ROUTE-004 | WARNING | Orphan page — exists on disk but not registered (unreachable) |
+| ROUTE-005 | WARNING | Implicit route (detail/create/edit) not resolvable |
+
+---
+
+## SUCCESS METRICS:
+- All 3 sources extracted completely
+- Cross-reference completed for all combinations
+- Orphan detection completed
+- DynamicRouter conventions accounted for
+
+## NEXT STEP:
+Proceed to `./step-05-report.md`

package/templates/skills/apex-verify/steps/step-05-report.md

@@ -0,0 +1,110 @@
+---
+name: step-05-report
+description: Generate consolidated audit report with all findings
+---
+
+# Step 5: Consolidated Report
+
+## YOUR TASK:
+Compile all findings from previous steps into a structured, actionable report.
+
+---
+
+## REPORT FORMAT:
+
+Display the following report to the user:
+
+```
+============================================================
+       APEX VERIFICATION REPORT
+============================================================
+
+Project: {project_name}
+Scope:   {scope}
+Date:    {current_date}
+
+------------------------------------------------------------
+  SUMMARY
+------------------------------------------------------------
+
+| Category     | BLOCKING | CRITICAL | WARNING | PASS |
+|-------------|----------|----------|---------|------|
+| Navigation  | {count}  | {count}  | {count} | {Y/N}|
+| CRUD        | {count}  | {count}  | {count} | {Y/N}|
+| Permissions | {count}  | {count}  | {count} | {Y/N}|
+| Routes      | {count}  | {count}  | {count} | {Y/N}|
+| **TOTAL**   | {total}  | {total}  | {total} |      |
+
+Result: {PASS / FAIL (N blocking issues)}
+
+------------------------------------------------------------
+  BLOCKING FINDINGS (must fix)
+------------------------------------------------------------
+
+[{ID}] {message}
+  File: {file_path}:{line}
+  Fix:  {fix_description}
+
+... (repeat for each blocking finding)
+
+------------------------------------------------------------
+  CRITICAL FINDINGS (should fix)
+------------------------------------------------------------
+
+[{ID}] {message}
+  File: {file_path}:{line}
+  Fix:  {fix_description}
+
+... (repeat for each critical finding)
+
+------------------------------------------------------------
+  WARNINGS (nice to fix)
+------------------------------------------------------------
+
+[{ID}] {message}
+  File: {file_path}:{line}
+  Fix:  {fix_description}
+
+... (repeat for each warning)
+
+============================================================
+```
+
+## ADDITIONAL SECTIONS (if --fix):
+
+When {fix_mode} is true, add a "FIX COMMANDS" section after the findings:
+
+```
+------------------------------------------------------------
+  FIX COMMANDS
+------------------------------------------------------------
+
+# NAV-001: Remove reserved section 'detail' from menu
+# File: src/.../EmployeesNavigationSeedData.cs
+# Action: Remove the section entry with code "detail" from Sections[] array
+
+# CRUD-004: Add Create button to EmployeeListPage
+# File: web/.../EmployeeListPage.tsx
+# Action: Add in the page header:
+#   <button onClick={() => navigate('create')} className="...">
+#     New Employee
+#   </button>
+
+... (repeat for each finding with specific fix instructions)
+```
+
+## RULES FOR REPORT GENERATION:
+
+1. **Sort by severity**: BLOCKING first, then CRITICAL, then WARNING
+2. **Within same severity**: Sort by category (NAV, CRUD, PERM, ROUTE)
+3. **No false positives**: Only include findings with concrete evidence (file:line)
+4. **No duplicates**: Merge findings that point to the same root cause
+5. **Actionable fixes**: Every finding must have a clear, specific fix instruction
+6. **If no findings in a category**: Display "PASS — No issues found" for that category
+
+## SUCCESS CRITERIA:
+- Report is complete and properly formatted
+- All findings from steps 1-4 are included
+- Pass/fail status is correct
+- Fix commands are included if --fix was specified
+- Report is immediately actionable by the developer

package/templates/skills/application/references/contexts-cheatsheet.md

@@ -0,0 +1,86 @@
+# SmartStack Contexts — Cheatsheet
+
+> **Reference for `application` skill** — quick lookup of the 10 system contexts exposed by `<SmartStackProvider>`.
+
+## When This Reference Applies
+
+- You generate a component that needs to read auth/tenant/theme state
+- You audit a page that re-implements existing context state
+- The user asks "how do I read the current tenant", "how do I check a permission", "where is the SignalR connection"
+
+---
+
+## The 10 contexts (state map)
+
+| # | Context | Hook | State exposed | Example use case |
+|---|---|---|---|---|
+| 1 | AuthContext | `useAuth()` | `user`, `roles`, `permissions`, `isAuthenticated`, `login()`, `logout()`, `refresh()`, `hasPermission(path)` | Read current user, check permission gate |
+| 2 | TenantContext | `useTenant()` | `currentTenant`, `userTenants`, `isGlobalView`, `switchTenant(id)` | Display tenant switcher, scope a query |
+| 3 | NavigationContext | `useNavigation()` | `menu` (MenuDto), `reload()`, `currentApp`, `currentModule`, `currentSection`, `isLoading`, `getApplicationsByZone()` (back-compat alias) | Render sidebar, breadcrumb, route resolution |
+| 4 | ThemeContext | `useTheme()` | `mode`, `selectedTheme`, `selectedPreset`, `setMode()`, `setTheme(id)`, `setPreset(id)` | Toggle dark mode, switch theme |
+| 5 | LicenseContext | `useLicense()` | `license`, `isFeatureEnabled(code)`, `hasModule(code)` | Gate a feature behind license |
+| 6 | SignalRContext | `useSignalR()` | `isConnected`, `on(event, handler)`, `off(event, handler)`, `emit(event, payload)` | Real-time notifications |
+| 7 | FavoritesContext | `useFavorites()` | `favorites`, `toggleFavorite(item)`, `isFavorite(id)` | Bookmark a page/entity |
+| 8 | SidebarContext | `useSidebar()` | `isCollapsed`, `toggle()`, `setCollapsed(value)` | Sidebar collapse button |
+| 9 | FeatureConfigContext | `useFeatureConfig()` | `features` (record from `/api/config/public`) | Feature flag, A/B test |
+| 10 | DocPanelContext | `useDocPanel()` | `isOpen`, `toggle()`, `openDoc(slug)` | Contextual help panel |
+
+---
+
+## Common patterns
+
+### Permission check — render guard
+
+```tsx
+const { hasPermission } = useAuth();
+if (!hasPermission('administration.users.create')) return <Forbidden />;
+```
+
+### Tenant-scoped query
+
+```tsx
+const { currentTenant } = useTenant();
+const { data } = useQuery(
+  ['orders', currentTenant?.id],
+  () => orderApi.list({ tenantId: currentTenant?.id })
+);
+```
+
+### Real-time updates
+
+```tsx
+const { on, off } = useSignalR();
+useEffect(() => {
+  const handler = (notif) => toast(notif.message);
+  on('NotificationReceived', handler);
+  return () => off('NotificationReceived', handler);
+}, []);
+```
+
+### Feature flag
+
+```tsx
+const { isFeatureEnabled } = useLicense();
+if (isFeatureEnabled('ai-assistant')) return <AiAssistant />;
+```
+
+---
+
+## DO / DON'T
+
+| ✅ DO | ❌ DON'T |
+|---|---|
+| Consume contexts via the provided hooks | `useContext(SmartStackContext)` directly |
+| Memoize derived values from context | Re-compute on every render |
+| Subscribe/unsubscribe SignalR handlers in `useEffect` cleanup | Forget to `off()` (memory leak) |
+| Treat `permissions` as opaque strings | Parse permissions client-side |
+| Read tenant from `currentTenant`, not URL | Trust the URL slug as a source of truth |
+
+---
+
+## Reference source files (read-only)
+
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\contexts\` (all 10 files)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\provider\SmartStackProvider.tsx` (wrapping order)
+
+See [smartstack-provider.md](smartstack-provider.md) for the wrapping order.