@atlashub/smartstack-cli 4.34.0 → 4.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.34.0",
+  "version": "4.35.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

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

@@ -2,8 +2,8 @@
 
 > 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.
+> **v3.7+:** Pattern A (mergeRoutes) and Pattern B (JSX Routes) were removed.
+> The only supported routing pattern is PageRegistry.register() + DynamicRouter.
 > See references/frontend-route-wiring-app-tsx.md for the current pattern.
 
 ---
@@ -507,117 +507,86 @@ export const $moduleApi = {
 
 ---
 
-## TEMPLATE: ROUTES (App.tsx)
+## TEMPLATE: ROUTES (PageRegistry + DynamicRouter)
 
-### Detect App.tsx Routing Pattern FIRST
+### Default Pattern (v3.7+): PageRegistry + DynamicRouter
 
-Before adding routes, **read App.tsx** and detect which pattern is used:
+> **This is the ONLY supported pattern** since v3.7.
+> Pages are registered in `componentRegistry.generated.ts` via `PageRegistry.register()`.
+> DynamicRouter resolves routes automatically from the navigation API + PageRegistry.
+> **No App.tsx wiring needed.** No manual route duplication for tenant prefixes.
 
-| Pattern | How to detect | Action |
-|---------|---------------|--------|
-| **Pattern A** (mergeRoutes) | `applicationRoutes: ApplicationRouteExtensions` present | Add to `applicationRoutes.{application}[]` array |
-| **Pattern B** (JSX Routes) | `<Route path="/{application}" element={<{Layout} />}>` present | Insert `<Route>` children inside Layout wrapper |
+**Steps:**
 
-### Pattern A: mergeRoutes (applicationRoutes array)
-
-> **This is the DEFAULT pattern** generated by `smartstack init`.
-> Routes added to `applicationRoutes` are automatically injected into BOTH standard and tenant-prefixed route trees by `mergeRoutes()`. No manual duplication needed.
+1. Create your page component(s)
+2. Register in `componentRegistry.generated.ts` (or run `scaffold_routes outputFormat="componentRegistry"`)
+3. Ensure navigation seed data has matching `ComponentKey` values
+4. DynamicRouter does the rest
 
 ```tsx
-// Add to App.tsx — imports at top
-import { $MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALPage';
-import { $MODULE_PASCALDetailPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage';
-import { Create$MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/Create$MODULE_PASCALPage';
-
-// Add routes to applicationRoutes.{application}[] with RELATIVE paths (no leading /)
-const applicationRoutes: ApplicationRouteExtensions = {
-  '$APPLICATION_KEBAB': [
-    // ... existing routes ...
-    { path: '$MODULE_KEBAB', element: <$MODULE_PASCALPage /> },
-    { path: '$MODULE_KEBAB/create', element: <Create$MODULE_PASCALPage /> },
-    { path: '$MODULE_KEBAB/:id', element: <$MODULE_PASCALDetailPage /> },
-    { path: '$MODULE_KEBAB/:id/edit', element: <Create$MODULE_PASCALPage /> },
-  ],
-};
+// 1. Create page component
+// pages/$APPLICATION/$MODULE/$MODULE_PASCALPage.tsx
+export function $MODULE_PASCALPage() { /* ... */ }
+
+// 2. Register in componentRegistry.generated.ts
+import { PageRegistry } from '@/extensions/PageRegistry';
+
+PageRegistry.register(
+  '$APPLICATION_KEBAB.$MODULE_KEBAB',
+  lazy(() => import('@/pages/$APPLICATION/$MODULE/$MODULE_PASCALPage')
+    .then(m => ({ default: m.$MODULE_PASCALPage })))
+);
+
+// For CRUD sub-pages (detail, create):
+PageRegistry.register(
+  '$APPLICATION_KEBAB.$MODULE_KEBAB.detail',
+  lazy(() => import('@/pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage')
+    .then(m => ({ default: m.$MODULE_PASCALDetailPage })))
+);
+
+PageRegistry.register(
+  '$APPLICATION_KEBAB.$MODULE_KEBAB.create',
+  lazy(() => import('@/pages/$APPLICATION/$MODULE/Create$MODULE_PASCALPage')
+    .then(m => ({ default: m.Create$MODULE_PASCALPage })))
+);
 ```
 
-**mergeRoutes auto-generates redirects** for intermediate paths (e.g., `$APPLICATION` → `$APPLICATION/$DEFAULT_MODULE_KEBAB`) so you don't need to add index redirects manually.
-
-**Application-to-Layout mapping (automatic via mergeRoutes):**
-
-| Application key | Injected into Layout | Standard path | Tenant path |
-|-----------------|---------------------|---------------|-------------|
-| `administration` | `AppLayout` | `/administration/...` | `/t/:slug/administration/...` |
-| `{application}` | `AppLayout` | `/{application}/...` | `/t/:slug/{application}/...` |
-| `myspace` | `AppLayout` | `/myspace/...` | `/t/:slug/myspace/...` |
-
-### Pattern B: JSX Routes (inside Layout wrapper)
-
-> **Legacy pattern** — only used if App.tsx was manually restructured with JSX `<Route>` elements.
-
-The unified `AppLayout` provides the application shell: **header with AvatarMenu**, sidebar, navigation. It renders child pages via React Router's `<Outlet />`.
+```sql
+-- 3. Navigation seed data (ComponentKey must match PageRegistry key)
+INSERT INTO core.nav_Sections (...)
+VALUES (..., ComponentKey = '$APPLICATION_KEBAB.$MODULE_KEBAB', ...);
+```
 
-**If routes are placed OUTSIDE the layout wrapper, the shell (header, sidebar, AvatarMenu) will NOT render. The page appears "naked" without any navigation.**
+### How DynamicRouter resolves routes
 
-**Step-by-step insertion:**
+1. Fetches menu from `GET /api/navigation/menu`
+2. For each Application → Module → Section → Resource, builds `<Route>` elements
+3. Looks up each item's `ComponentKey` in `PageRegistry` to get the React component
+4. Wraps routes in `<ProtectedRoute>` (API-driven permission check via `isOpen` flag)
+5. Generates both standard (`/$APPLICATION/$MODULE`) and tenant-prefixed (`/t/:slug/$APPLICATION/$MODULE`) routes automatically
 
-1. Open `App.tsx`
-2. Find the existing layout route for the target application:
-   - `administration` → `<Route path="/administration" element={<AppLayout />}>`
-   - `{application}` → `<Route path="/{application}" element={<AppLayout />}>`
-   - `myspace` → `<Route path="/myspace" element={<AppLayout />}>`
-3. Add the new routes **INSIDE** that `<Route>` block
-4. If a tenant-prefixed block exists (`/t/:slug/...`), add the routes there too
+### ⚠️ CRITICAL RULES
 
+**FORBIDDEN — Flat routes outside DynamicRouter:**
 ```tsx
-// Add to App.tsx
-
-import { $MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALPage';
-import { $MODULE_PASCALDetailPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage';
-import { Create$MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/Create$MODULE_PASCALPage';
-
-// Find the EXISTING layout route and add routes INSIDE it:
-<Route path="/$APPLICATION" element={<$APPLICATION_Layout />}>
-  {/* ... existing routes stay here ... */}
-
-  {/* NEW: $MODULE routes - added as children of the layout */}
-  <Route path="$MODULE_KEBAB">
-    <Route index element={<Navigate to="." replace />} />
-    <Route index element={<$MODULE_PASCALPage />} />
-    <Route path="create" element={<Create$MODULE_PASCALPage />} />
-    <Route path=":id" element={<$MODULE_PASCALDetailPage />} />
-    <Route path=":id/edit" element={<Create$MODULE_PASCALPage />} />
-  </Route>
-</Route>
+// ❌ WRONG — bypasses layout, permission checks, and tenant handling
+<Route path="/$APPLICATION_KEBAB/$MODULE_KEBAB" element={<$MODULE_PASCALPage />} />
 ```
 
-### ⚠️ CRITICAL RULES (both patterns)
-
-**FORBIDDEN — Adding to clientRoutes[] with absolute paths:**
+**FORBIDDEN — Registering pages without navigation seed data:**
 ```tsx
-// ❌ WRONG — bypasses layout entirely, shell will NOT render
-const clientRoutes: RouteConfig[] = [
-  { path: '/$APPLICATION_KEBAB/$MODULE_KEBAB', element: <$MODULE_PASCALPage /> },
-];
+// ❌ WRONG — PageRegistry.register() alone does nothing without a matching ComponentKey in the DB
+PageRegistry.register('my-app.my-module', MyPage);
+// Must also have INSERT INTO core.nav_Sections with ComponentKey = 'my-app.my-module'
 ```
 
-`clientRoutes` is ONLY for routes **outside** SmartStack locked applications (e.g., `/about`, `/pricing`).
-
-**FORBIDDEN — Flat routes outside layout:**
-```tsx
-// ❌ WRONG (Pattern B only) — flat route bypasses layout
-<Route path="/$APPLICATION_KEBAB/$MODULE_KEBAB" element={<$MODULE_PASCALPage />} />
-```
+---
 
-### Why nested/context routes?
+### Legacy Patterns (DEPRECATED — removed in v3.7)
 
-| Aspect | clientRoutes (wrong) | applicationRoutes / nested (correct) |
-|--------|---------------------|--------------------------------------|
-| Shell rendered | No (bypasses layout) | Yes (Outlet pattern) |
-| AvatarMenu visible | No | Yes |
-| Tenant prefix | Manual duplication | Automatic (mergeRoutes) |
-| Auto-redirects | None | Generated for intermediate paths |
-| Permission check | Bypassed (no RouteGuard) | Enforced by RouteGuard |
+> **Pattern A (mergeRoutes)** and **Pattern B (JSX Routes)** were removed in v3.7.
+> `smartstackRoutes.tsx`, `RouteGuard.tsx`, and `mergeRoutes()` no longer exist.
+> If you encounter a pre-v3.7 project, upgrade to PageRegistry + DynamicRouter.
 
 ---
 

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 (client uses mergeRoutes legacy or PageRegistry+DynamicRouter)
+  [SKIP]  App.tsx — Intentionally different (client uses PageRegistry+DynamicRouter v3.7+)
   [SKIP]  ExtensionsDbContext — Intentionally simplified
 
 --------------------------------------------------------------------------------
@@ -161,7 +161,7 @@ These differences are **by design** and should always be marked `[SKIP]`:
 
 | File/Pattern | Reason |
 |---|---|
-| `App.tsx` — routing pattern (`mergeRoutes` legacy or `PageRegistry`+`DynamicRouter` v3.7+) | Client projects use their own routing entry point, not platform routing |
+| `App.tsx` — routing pattern (`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` (legacy) or `PageRegistry`+`DynamicRouter` (v3.7+); app uses direct routing |
+| `App.tsx` | Client uses `PageRegistry`+`DynamicRouter` (v3.7+); app uses DynamicRouter exclusively (mergeRoutes removed in v3.7) |
 | `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 |

package/templates/skills/documentation/steps/step-03-validate.md

@@ -25,8 +25,7 @@ Validate that generated documentation is complete and accurate, then integrate i
 - [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
 - [ ] Every Mock UI section has `Annotation` components explaining each visual element
 - [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
-- [ ] Route added as **child** of `/docs/business` group (not standalone) in App.tsx
-- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] Route added as **child** of `/docs/business` group (not standalone) in DynamicRouter.tsx
 - [ ] DocsLayout sidebar updated (if applicable)
 - [ ] Module appears in UserIndexPage.tsx (if applicable)
 - [ ] DocPanelContext.tsx mapping updated for all module routes
@@ -38,8 +37,7 @@ Validate that generated documentation is complete and accurate, then integrate i
 - [ ] i18n JSON uses root key matching namespace
 - [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
 - [ ] doc-data.ts contains structured data (~50 lines)
-- [ ] Route added as **child** of `/system/docs` group (not standalone) in App.tsx
-- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] Route added as **child** of `/system/docs` group (not standalone) in DynamicRouter.tsx
 - [ ] DocsLayout sidebar updated (if applicable)
 
 #### For `update` Type
@@ -113,7 +111,7 @@ detects tenant-prefixed routes (`/t/:slug/...`), and builds lookup keys as `{app
 - `/support/tickets/123` → tries `support/tickets/123`, then `support/tickets`
 - `/t/my-company/administration/users` → strips tenant prefix, then tries `administration/users`
 
-#### App.tsx Routing
+#### DynamicRouter.tsx Routing
 
 Documentation pages use a **separate routing system** from business pages. They render inside `DocsLayout` (sidebar navigation), NOT `AppLayout`. There are two route groups:
 
@@ -122,10 +120,10 @@ Documentation pages use a **separate routing system** from business pages. They
 
 > **Note:** The `<Suspense fallback={<PageLoader />}>` is already in place at the global level (wrapping the entire Routes tree). Do NOT add per-route `<Suspense>` wrappers.
 
-**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group:
+**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group in `DynamicRouter.tsx`:
 
 ```tsx
-// 1. Add lazy import at top of App.tsx
+// 1. Add lazy import at top of DynamicRouter.tsx
 const {Module}DocPage = lazy(() =>
   import('@/pages/docs/business/{application}/{module}')
 );
@@ -138,10 +136,10 @@ const {Module}DocPage = lazy(() =>
 </Route>
 ```
 
-**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group:
+**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group in `DynamicRouter.tsx`:
 
 ```tsx
-// 1. Add lazy import at top of App.tsx
+// 1. Add lazy import at top of DynamicRouter.tsx
 const {Tool}DocPage = lazy(() =>
   import('@/pages/docs/{category}/{tool}')
 );
@@ -154,9 +152,9 @@ const {Tool}DocPage = lazy(() =>
 </Route>
 ```
 
-#### smartstackRoutes.tsx Registration
+#### DynamicRouter Documentation Routes
 
-**MANDATORY** for all doc types: Add the route in `smartstackRoutes.tsx` under the corresponding group (`/docs/business` or `/system/docs`). Documentation routes are part of `LOCKED_PREFIXES` and cannot be overridden by client extensions.
+Documentation routes are statically defined in `DynamicRouter.tsx` (not dynamically generated from the navigation API). When adding new documentation pages, add the lazy import and `<Route>` entry in the documentation section of `DynamicRouter.tsx`.
 
 #### DocsLayout Sidebar Update
 
@@ -164,7 +162,7 @@ If the new documentation page should appear in the sidebar navigation, update th
 
 #### Important Notes
 
-- Documentation routes do **NOT** use `AppLayout`, `RouteGuard`, or `LicenseGuard`
+- Documentation routes do **NOT** use `AppLayout`, `ProtectedRoute`, or `LicenseGuard`
 - Documentation routes have **no tenant prefix** (`/t/:slug/...`) — they are globally accessible
 - Documentation routes require **no specific permission** to access
 
@@ -259,8 +257,8 @@ Add or update entry with metadata:
 - [x] Mock UI faithfully reproduces the real page interface (user type)
 - [x] Every Mock UI section has `Annotation` components (user type)
 - [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
-- [x] Route added as child of correct DocsLayout group in App.tsx
-- [x] Route registered in smartstackRoutes.tsx (locked routes)
+- [x] Route added as child of correct DocsLayout group in DynamicRouter.tsx
+- [x] Route added in DynamicRouter.tsx documentation section
 - [x] DocsLayout sidebar updated (if applicable)
 - [x] docs-manifest.json updated
 - [x] i18n/config.ts updated with new namespace

package/templates/mcp-scaffolding/frontend/routes.tsx.hbs

@@ -1,126 +0,0 @@
-{{!-- SmartStack React Router Configuration Template --}}
-{{!-- Generates router configuration from NavRoute registry --}}
-
-/**
- * React Router Configuration
- *
- * Auto-generated by SmartStack MCP - DO NOT EDIT MANUALLY
- * Generated: {{generatedAt}}
- */
-
-import React, { Suspense, lazy } from 'react';
-import { createBrowserRouter, RouteObject, Navigate } from 'react-router-dom';
-import { ROUTES } from './navRoutes.generated';
-{{#if includeGuards}}
-import { ProtectedRoute, PermissionGuard } from './guards';
-{{/if}}
-
-// ============================================================================
-// Layouts
-// ============================================================================
-
-{{#each applications}}
-import { {{capitalize this}}Layout } from '../layouts/{{capitalize this}}Layout';
-{{/each}}
-
-// ============================================================================
-// Pages (lazy loaded for code splitting)
-// ============================================================================
-
-{{#each routes}}
-const {{pageName this.navRoute}}Page = lazy(() => import('../pages/{{pagePath this.navRoute}}'));
-{{/each}}
-
-// ============================================================================
-// Loading Component
-// ============================================================================
-
-const PageLoader: React.FC = () => (
-  <div className="flex items-center justify-center h-64">
-    <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-500" />
-  </div>
-);
-
-// ============================================================================
-// Route Configuration
-// ============================================================================
-
-const routes: RouteObject[] = [
-  // Root redirect
-  {
-    path: '/',
-    element: <Navigate to="{{defaultPath}}" replace />,
-  },
-
-{{#each applicationTree}}
-  // {{uppercase @key}} Application
-  {
-    path: '{{@key}}',
-    element: <{{capitalize @key}}Layout />,
-    children: [
-{{#each this}}
-      {
-        path: '{{modulePath this.navRoute}}',
-{{#if this.permissions.length}}
-        element: (
-          <PermissionGuard permissions={ROUTES['{{this.navRoute}}'].permissions}>
-            <Suspense fallback={<PageLoader />}>
-              <{{pageName this.navRoute}}Page />
-            </Suspense>
-          </PermissionGuard>
-        ),
-{{else}}
-        element: (
-          <Suspense fallback={<PageLoader />}>
-            <{{pageName this.navRoute}}Page />
-          </Suspense>
-        ),
-{{/if}}
-      },
-{{/each}}
-    ],
-  },
-{{/each}}
-
-  // 404 Not Found
-  {
-    path: '*',
-    element: (
-      <div className="flex flex-col items-center justify-center h-screen">
-        <h1 className="text-4xl font-bold text-gray-900">404</h1>
-        <p className="mt-2 text-gray-600">Page not found</p>
-        <a href="{{defaultPath}}" className="mt-4 text-blue-600 hover:underline">
-          Return to home
-        </a>
-      </div>
-    ),
-  },
-];
-
-// ============================================================================
-// Router Export
-// ============================================================================
-
-{{#if includeGuards}}
-export const router = createBrowserRouter([
-  {
-    element: <ProtectedRoute />,
-    children: routes,
-  },
-]);
-{{else}}
-export const router = createBrowserRouter(routes);
-{{/if}}
-
-export default router;
-
-// ============================================================================
-// Type Exports
-// ============================================================================
-
-export type { RouteObject };
-
-/**
- * Get route configuration by NavRoute path
- */
-export const getRouteConfig = (navRoute: string) => ROUTES[navRoute];