@atlashub/smartstack-cli 4.31.0 → 4.33.0

package/templates/skills/application/references/frontend-i18n-and-output.md

@@ -48,8 +48,8 @@ Display generated frontend code organized by category:
 
 ### Routes
 - Updated `navRoutes.generated.ts`
-- Generated `applicationRoutes.generated.tsx`
-- Wired routes in `App.tsx` (standard + tenant blocks)
+- Generated `componentRegistry.generated.ts` (PageRegistry registrations)
+- Navigation seed data has matching componentKeys
 
 ### i18n
 - `locales/fr/{entityCode}.json`

package/templates/skills/application/references/frontend-route-naming.md

@@ -50,8 +50,12 @@ Navigation seed data:
 Route = "/human-resources/time-management"  // From ToKebabCase()
 ```
 
-App.tsx routes must use:
+PageRegistry keys and seed data ComponentKeys must use kebab-case:
 ```tsx
+// v3.7+ (DynamicRouter): componentKey uses dot-separated kebab-case
+PageRegistry.register('human-resources.time-management', lazy(() => ...));
+
+// Legacy (applicationRoutes): paths use kebab-case
 const applicationRoutes: ApplicationRouteExtensions = {
   'human-resources': [  // ← kebab-case
     { path: 'time-management', element: <TimeManagementPage /> },  // ← kebab-case

package/templates/skills/application/references/frontend-route-wiring-app-tsx.md

@@ -1,168 +1,70 @@
-# Frontend: Route Wiring in App.tsx
+# Frontend: Route Registration with PageRegistry + DynamicRouter
 
-> Referenced from `steps/step-05-frontend.md` — Detailed route wiring patterns and verification.
+> **v3.7+** — Replaces the legacy Pattern A (mergeRoutes) and Pattern B (JSX routes) patterns.
 
 ---
 
-## Step 4: Wire Routes to App.tsx (BLOCKING)
+## How It Works
 
-**CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.
+1. **Backend seed data** defines navigation entries with `ComponentKey` values
+   (e.g., `administration.users`, `support.tickets.list`)
+2. **`componentRegistry.generated.ts`** registers all page components into `PageRegistry`
+   via `PageRegistry.register('key', lazy(() => import(...)))`
+3. **DynamicRouter** fetches the menu API, matches each entry's `componentKey` to a
+   `PageRegistry` entry, and generates `<Route>` elements at runtime
+4. **Implicit routes** (detail, create, edit) are resolved by convention:
+   - `*.detail` → `.../:id`
+   - `*.create` → `.../create`
+   - `*.edit` → `.../:id/edit`
 
-After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
+No manual App.tsx wiring is needed.
 
 ---
 
-## Step 4a: Import Page Components
+## For SmartStack Core Pages
 
-At the top of App.tsx:
+`componentRegistry.generated.ts` is auto-generated by MCP `scaffold_routes`:
 
 ```tsx
-import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
-// Or lazy-loaded:
-const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{EntityName}Page'));
+// Auto-generated — DO NOT EDIT
+import { lazy } from 'react';
+import { PageRegistry } from '@/extensions/PageRegistry';
+
+PageRegistry.register('administration.users', lazy(() =>
+  import('@/pages/platform/administration/users/UsersPage').then(m => ({ default: m.UsersPage }))
+));
+PageRegistry.register('administration.users.detail', lazy(() =>
+  import('@/pages/platform/administration/users/UserDetailPage').then(m => ({ default: m.UserDetailPage }))
+));
+// ... ~100 registrations
 ```
 
----
-
-## Step 4a.5: Import Generated Route Extensions (if scaffold_routes was used)
-
-If `scaffold_routes` generated `applicationRoutes.generated.tsx`, import and spread:
-
-```tsx
-import { applicationRouteExtensions } from '@/routes/applicationRoutes.generated';
-
-const applicationRoutes: ApplicationRouteExtensions = {
-  ...applicationRouteExtensions,
-  // additional manual routes if needed...
-};
-```
-
-If no generated file exists, add routes directly to the existing `applicationRoutes` object.
-
----
-
-## Step 4b: Detect App.tsx Routing Pattern
-
-Read App.tsx and detect which pattern is used:
-
-### Pattern A: applicationRoutes Object
-
-**If App.tsx contains:** `applicationRoutes: ApplicationRouteExtensions`
-
-→ Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`)
-
-```tsx
-const applicationRoutes: ApplicationRouteExtensions = {
-  'human-resources': [
-    // existing routes...
-    { path: '{module_kebab}/{section_kebab}', element: <{EntityName}ListPage /> },
-    { path: '{module_kebab}/{section_kebab}/create', element: <Create{EntityName}Page /> },
-    { path: '{module_kebab}/{section_kebab}/:id', element: <{EntityName}DetailPage /> },
-    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Create{EntityName}Page /> },
-
-    // Parent redirect routes (MANDATORY — prevents /login redirect on parent navigation)
-    { path: '{module_kebab}', element: <Navigate to="{module_kebab}/{first_section_kebab}" replace /> },
-    { path: '', element: <Navigate to="{first_module_kebab}/{first_section_kebab}" replace /> },
-  ],
-};
-```
-
-Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
-
-#### RULE — Route Ordering in applicationRoutes
-
-> **CRITICAL:** Routes within each application key MUST follow static-before-dynamic order.
-> React Router matches top-to-bottom — a `:id` route placed before a `dashboard` route
-> will match `dashboard` as an `id` parameter → 404.
-
-```tsx
-const applicationRoutes: ApplicationRouteExtensions = {
-  'human-resources': [
-    // ✅ CORRECT ORDER — static before dynamic
-    { path: 'employees', element: <EmployeesPage /> },
-    { path: 'employees/create', element: <CreateEmployeePage /> },
-    { path: 'employees/dashboard', element: <EmployeeDashboardPage /> },
-    { path: 'employees/:id', element: <EmployeeDetailPage /> },
-    { path: 'employees/:id/edit', element: <EditEmployeePage /> },
-
-    // Redirect routes ALWAYS LAST
-    { path: '', element: <Navigate to="employees" replace /> },
-  ],
-};
-```
-
-```tsx
-// ❌ FORBIDDEN — :id before static routes
-'human-resources': [
-  { path: 'employees/:id', element: <EmployeeDetailPage /> },      // ← WRONG: catches 'dashboard'
-  { path: 'employees/dashboard', element: <DashboardPage /> },      // ← NEVER REACHED
-]
-```
-
-See `smartstack-layers.md` "RULE — Frontend Route Ordering" for the full ordering specification.
-POST-CHECK C49 detects and BLOCKS this anti-pattern.
-
-#### Custom Applications (Pattern A)
-
-Custom application keys (any key **not** in the built-in list: `administration`, `support`, `user`, `api`) are fully supported in `applicationRoutes`. `mergeRoutes()` automatically:
-
-1. Creates a new route entry wrapped in `<AppLayout />`
-2. Injects it into **both** standard (`/{app-key}/...`) and tenant-prefixed (`/t/:slug/{app-key}/...`) trees, inside `TenantRouteWrapper > RouteGuard > LicenseGuard`
-3. Generates automatic parent redirect routes (e.g., `employees` → `employees/management`)
-
-No need to use Pattern B for custom applications — Pattern A handles everything automatically.
-
-### Pattern B: JSX Routes
-
-**If App.tsx contains:** `<Route path="/{application}" element={<{Layout} />}>`
-
-→ Insert `<Route>` children inside the Layout wrapper:
-
+Imported once in `main.tsx`:
 ```tsx
-<Route path="/human-resources" element={<AppLayout />}>
-  {/* ... existing routes ... */}
-  <Route path="{module_kebab}" element={<{EntityName}Page />} />
-</Route>
+import './extensions/componentRegistry.generated';
 ```
 
-**ALSO add the same routes inside the tenant-prefixed block:**
-
-Find `<Route path="/t/:slug">` and add the **same route entries** there.
-
 ---
 
-## Step 4b.5: Verify mergeRoutes() Call (BLOCKING)
+## For Client SDK Pages
 
-**BEFORE modifying routes, READ App.tsx and verify the `mergeRoutes()` call has 2 parameters.**
+Clients register their own pages directly:
 
-✅ Correct:
 ```tsx
-const routes = mergeRoutes(clientRoutes, applicationRoutes);
-```
+import { PageRegistry } from '@atlashub/smartstack';
+import { lazy } from 'react';
 
-❌ If you see only 1 parameter:
-```tsx
-const routes = mergeRoutes(clientRoutes);
+PageRegistry.register('rh.time.dashboard', lazy(() => import('./pages/TimeDashboard')));
+PageRegistry.register('rh.time.list', lazy(() => import('./pages/TimeList')));
+PageRegistry.register('rh.time.detail', lazy(() => import('./pages/TimeDetail')));
 ```
 
-→ Add the `applicationRoutes` object and pass it as 2nd parameter.
-Without it, ALL application routes are silently ignored → blank page or /login redirect.
-
-**NEVER remove the `applicationRoutes` parameter or the `ApplicationRouteExtensions` import.**
-
----
-
-## Step 4c: Application-to-Layout Mapping
-
-| Application prefix | Layout Component | Route path |
-|---------|------------------|------------|
-| `administration.*` | `AppLayout` | `/administration` |
-| `*` (business apps) | `AppLayout` | `/{application}` |
-| `myspace.*` | `AppLayout` | `/myspace` |
+Navigation entries are created in DB (via admin UI or seed data).
+DynamicRouter does the junction automatically.
 
 ---
 
-## Step 4d: Verify Wiring
+## Verification
 
 ```
 Tool: mcp__smartstack__validate_frontend_routes
@@ -170,68 +72,17 @@ Args:
   scope: "routes"
 ```
 
-If `appWiring.issues` is not empty, fix the wiring before proceeding.
-
----
-
-## Step 4e: Parent Redirect Routes (MANDATORY)
-
-**CRITICAL:** Without parent redirects, navigating to an application or module URL (e.g., `/human-resources` or `/human-resources/employees`) will cause a redirect to `/login` because no route matches.
-
-For each application, you MUST add:
-
-1. **Application root redirect** — redirects `/{application}` to the first module/section:
-   ```tsx
-   { path: '', element: <Navigate to="{first_module}/{first_section}" replace /> }
-   ```
-
-2. **Module redirect** (if modules have sections) — redirects `/{application}/{module}` to first section:
-   ```tsx
-   { path: '{module}', element: <Navigate to="{module}/{first_section}" replace /> }
-   ```
-
-**Example:** For NavRoutes `human-resources.employees.management` and `human-resources.employees.departments`:
-```tsx
-{ path: 'employees', element: <Navigate to="employees/management" replace /> },
-{ path: '', element: <Navigate to="employees/management" replace /> },
-```
-
-The `to` prop is resolved relative to the **parent route** (`/{application}`), so always use the full path from the application root.
-
-> Note: `scaffold_routes` with `outputFormat: "applicationRoutes"` generates these redirects automatically.
-
----
-
-## Forbidden Patterns (BOTH patterns)
-
-- Adding application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
-- Adding routes OUTSIDE the Layout wrapper (shell will not render)
-- Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
-- Adding custom application routes to `clientRoutes[]` with absolute paths:
-  ```tsx
-  // ❌ WRONG — bypasses RouteGuard + TenantLayout + AppLayout → /login redirect
-  const clientRoutes: RouteConfig[] = [
-    { path: '/human-resources/employees/management', element: <EmployeePage /> },
-  ];
-  ```
-  Custom application routes MUST go in `applicationRoutes` with RELATIVE paths:
-  ```tsx
-  // ✅ CORRECT
-  const applicationRoutes: ApplicationRouteExtensions = {
-    'human-resources': [
-      { path: 'employees/management', element: <EmployeePage /> },
-    ],
-  };
-  ```
-- Removing the `applicationRoutes` 2nd parameter from `mergeRoutes()` — this silently breaks ALL custom routes
+Checks:
+- `componentRegistry.generated.ts` exists
+- Each backend NavRoute has a `PageRegistry.register()` call
+- `main.tsx` imports the generated file
+- Implicit route keys (*.detail, *.create, *.edit) exist for CRUD pages
 
 ---
 
-## Verification Checklist
+## Legacy Patterns (DEPRECATED)
 
-- [ ] Routes are inside the AppLayout wrapper
-- [ ] Routes use NESTED structure (not flat)
-- [ ] Application kebab-case matches navigation seed data
-- [ ] Both standard and tenant-prefixed blocks have routes (if using Pattern B)
-- [ ] Page components are imported at top of App.tsx
-- [ ] `mcp__smartstack__validate_frontend_routes` returns no issues
+> The Pattern A (`mergeRoutes(clientRoutes, applicationRoutes)`) and Pattern B
+> (JSX `<Route>` in App.tsx) patterns are deprecated since v3.7.
+> They still work but are not recommended for new development.
+> See git history for the legacy documentation.

package/templates/skills/application/references/frontend-verification.md

@@ -73,21 +73,21 @@ Verify exactly **4 language files** exist with identical key structures:
 
 ### 5. Route Check (BLOCKING)
 
-Verify routes are:
-- **INSIDE** the AppLayout wrapper
-- **NESTED** (not flat)
+Verify routes are registered:
+- **v3.7+ (DynamicRouter):** PageRegistry.register() exists in componentRegistry.generated.ts
+- **Legacy:** inside Layout wrapper, nested, correct path convention
 - Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)
 
 ### 5b. Route Wiring Check (BLOCKING)
 
-Verify routes are actually wired into App.tsx (not just generated in standalone files):
+**v3.7+ (DynamicRouter):** Verify PageRegistry registration:
 
-1. Open `App.tsx` (or `main.tsx`)
-2. Verify the new route path appears **inside** the correct Layout wrapper
-3. Verify the route also appears inside the **tenant-prefixed** block (`/t/:slug/...`)
-4. Verify the page component is imported (lazy-loaded) at the top of the file
+1. Open `componentRegistry.generated.ts`
+2. Verify new pages have `PageRegistry.register()` calls with matching componentKeys
+3. Verify `main.tsx` imports `./extensions/componentRegistry.generated`
+4. DynamicRouter resolves routes automatically — no App.tsx wiring needed
 
-**If routes are only in `applicationRoutes.generated.tsx` or `routes/index.tsx` but NOT in App.tsx, the routes will NOT work at runtime — page will be BLANK.**
+**Legacy:** Verify routes are wired into App.tsx (inside Layout wrapper + tenant block).
 
 Run validation:
 ```
@@ -96,7 +96,7 @@ Args:
   scope: "routes"
 ```
 
-If `appWiring.issues` is not empty, fix the wiring before proceeding.
+If validation returns issues, fix before proceeding.
 
 ### 5c. Route Kebab-Case Check (BLOCKING)
 
@@ -110,7 +110,7 @@ Scan App.tsx route paths for non-kebab-case segments:
 
 **Verification steps:**
 
-1. Extract all route path strings from App.tsx (both `applicationRoutes` and `<Route path="...">`)
+1. Extract all route keys from `componentRegistry.generated.ts` (v3.7+) or App.tsx (`applicationRoutes` / `<Route path="...">`)
 2. For each multi-word path segment, verify it uses hyphens (kebab-case)
 3. Cross-reference route paths with navigation seed data routes to ensure exact match
 4. Single-word segments are fine as-is (e.g., `employees`, `products`)

package/templates/skills/application/steps/step-05-frontend.md

@@ -103,23 +103,33 @@ Args:
   options:
     includeGuards: true
     generateRegistry: true
-    outputFormat: "applicationRoutes"
+    outputFormat: "componentRegistry"
 ```
 
 This generates:
-- `navRoutes.generated.ts` - Route registry (NavRoute to API/web path mapping)
-- `applicationRoutes.generated.tsx` - Route fragments grouped by context with page imports
+- `navRoutes.generated.ts` — Route registry (NavRoute to API/web path mapping)
+- `componentRegistry.generated.ts` — PageRegistry.register() calls for DynamicRouter
 
-### 4. Wire Routes to App.tsx (BLOCKING)
+### 4. Verify PageRegistry Registration
 
-See [references/frontend-route-wiring-app-tsx.md](../references/frontend-route-wiring-app-tsx.md) for:
-- Step 4a: Import page components (lazy)
-- Step 4a.5: Import generated route extensions (if scaffold_routes was used)
-- Step 4b: Detect App.tsx routing pattern (Pattern A vs Pattern B)
-- Step 4b.5: Verify mergeRoutes() has 2 parameters (BLOCKING)
-- Step 4c: Application-to-Layout mapping table
-- Step 4d: Route wiring verification
-- Forbidden patterns (absolute paths in clientRoutes, outside Layout, missing 2nd param)
+After `scaffold_routes` generates the files:
+
+1. **Verify `componentRegistry.generated.ts`** contains `PageRegistry.register()` calls
+   for each new page component
+2. **Verify `main.tsx`** imports `./extensions/componentRegistry.generated`
+   (this should already be present — check once)
+3. **Verify navigation seed data** has `ComponentKey` values matching the registered keys
+   (e.g., seed Route="/administration/users" → ComponentKey="administration.users")
+
+No manual App.tsx wiring is needed — DynamicRouter resolves routes automatically
+from the API menu response + PageRegistry at runtime.
+
+Verification:
+```
+Tool: mcp__smartstack__validate_frontend_routes
+Args:
+  scope: "routes"
+```
 
 ### 5-6. Verify i18n & Present Output
 
@@ -157,10 +167,11 @@ See [references/frontend-verification.md](../references/frontend-verification.md
 
 - React component generated
 - API client generated with types
-- Routes updated (nested structure)
-- Routes wired in App.tsx (standard + tenant blocks)
+- PageRegistry entries generated (componentRegistry.generated.ts)
+- navRoutes.generated.ts updated
+- Navigation seed data has matching componentKeys
 - i18n files created (4 languages)
-- Post-generation verification passed (all 7 checks + route wiring check)
+- Post-generation verification passed
 - Proceeded to step-06-migration.md
 
 ## FAILURE MODES

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

@@ -2,6 +2,10 @@
 
 > These templates generate React/TypeScript code for new applications/modules.
 
+> **DEPRECATED (v3.7+):** Pattern A (mergeRoutes) and Pattern B (JSX Routes) below
+> are replaced by PageRegistry.register() + DynamicRouter.
+> See references/frontend-route-wiring-app-tsx.md for the current pattern.
+
 ---
 
 ## FRONTEND ARCHITECTURE

package/templates/skills/cli-app-sync/SKILL.md

@@ -113,7 +113,7 @@ COMPARISON POINTS: {total}
   [OK]    index.css — @custom-variant dark present
   [OK]    DependencyInjection.Application — MediatR warning present
   [OK]    DependencyInjection.Infrastructure — SQL Server pattern matches
-  [SKIP]  App.tsx — Intentionally different (mergeRoutes pattern)
+  [SKIP]  App.tsx — Intentionally different (client uses mergeRoutes legacy or PageRegistry+DynamicRouter)
   [SKIP]  ExtensionsDbContext — Intentionally simplified
 
 --------------------------------------------------------------------------------
@@ -161,7 +161,7 @@ These differences are **by design** and should always be marked `[SKIP]`:
 
 | File/Pattern | Reason |
 |---|---|
-| `App.tsx` — `mergeRoutes` + `SmartStackProvider` | Client projects use extension routing pattern, not platform routing |
+| `App.tsx` — routing pattern (`mergeRoutes` legacy or `PageRegistry`+`DynamicRouter` v3.7+) | Client projects use their own routing entry point, not platform routing |
 | `ExtensionsDbContext` | Intentionally simplified vs `CoreDbContext` — different architectural role |
 | `api.ts` | Re-exports SmartStack client — wrapper pattern is correct |
 | `DependencyInjection.Infrastructure.cs` | SQL Server connection pattern identical by design |

package/templates/skills/cli-app-sync/references/comparison-map.md

@@ -208,7 +208,7 @@ These comparisons should **always** return `[SKIP]` — differences are by desig
 
 | Item | Reason |
 |---|---|
-| `App.tsx` | Client uses `mergeRoutes` + `SmartStackProvider`; app uses direct routing |
+| `App.tsx` | Client uses `mergeRoutes` (legacy) or `PageRegistry`+`DynamicRouter` (v3.7+); app uses direct routing |
 | `api.ts` | Client re-exports SmartStack client — wrapper pattern is correct |
 | `ExtensionsDbContext` | Intentionally simplified vs `CoreDbContext` |
 | `GlobalUsings.cs` | App has platform-wide usings; client has minimal set |