@atlashub/smartstack-cli 4.14.0 → 4.17.0

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

@@ -25,7 +25,9 @@ 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 registered in App.tsx
+- [ ] Route added as **child** of `/docs/business` group (not standalone) in App.tsx
+- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] DocsLayout sidebar updated (if applicable)
 - [ ] Module appears in UserIndexPage.tsx (if applicable)
 - [ ] DocPanelContext.tsx mapping updated for all module routes
 - [ ] i18n/config.ts updated with new namespace
@@ -36,7 +38,9 @@ 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 registered in App.tsx and parent indexes
+- [ ] Route added as **child** of `/system/docs` group (not standalone) in App.tsx
+- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] DocsLayout sidebar updated (if applicable)
 
 #### For `update` Type
 
@@ -111,34 +115,59 @@ detects tenant-prefixed routes (`/t/:slug/...`), and builds lookup keys as `{app
 
 #### App.tsx Routing
 
-**For `user` type:** Add dynamic import and route:
+Documentation pages use a **separate routing system** from business pages. They render inside `DocsLayout` (sidebar navigation), NOT `AppLayout`. There are two route groups:
+
+- **`/docs/business`** → Business module docs (user type) — uses `<DocsLayout />`
+- **`/system/docs`** → Developer/database/testing docs — uses `<DocsLayout />`
+
+> **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:
 
 ```tsx
+// 1. Add lazy import at top of App.tsx
 const {Module}DocPage = lazy(() =>
   import('@/pages/docs/business/{application}/{module}')
 );
 
-// In routes array:
-{
-  path: '/docs/business/{application}/{module}',
-  element: <Suspense><{Module}DocPage /></Suspense>
-}
+// 2. Find the existing <Route path="/docs/business" element={<DocsLayout />}> group
+//    Add as CHILD route (not standalone):
+<Route path="/docs/business" element={<DocsLayout />}>
+  {/* ... existing doc routes ... */}
+  <Route path="{application}/{module}" element={<{Module}DocPage />} />
+</Route>
 ```
 
-**For `developer|database|testing` types:** Add to appropriate category:
+**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group:
 
 ```tsx
+// 1. Add lazy import at top of App.tsx
 const {Tool}DocPage = lazy(() =>
-  import('@/pages/docs/developer/{category}/{tool}')
+  import('@/pages/docs/{category}/{tool}')
 );
 
-// In routes array:
-{
-  path: '/docs/developer/{category}/{tool}',
-  element: <Suspense><{Tool}DocPage /></Suspense>
-}
+// 2. Find the existing <Route path="/system/docs" element={<DocsLayout />}> group
+//    Add as CHILD route:
+<Route path="/system/docs" element={<DocsLayout />}>
+  {/* ... existing doc routes ... */}
+  <Route path="{category}/{tool}" element={<{Tool}DocPage />} />
+</Route>
 ```
 
+#### smartstackRoutes.tsx Registration
+
+**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.
+
+#### DocsLayout Sidebar Update
+
+If the new documentation page should appear in the sidebar navigation, update the `navigation` array in `DocsLayout.tsx` with the new entry (label, path, icon).
+
+#### Important Notes
+
+- Documentation routes do **NOT** use `AppLayout`, `RouteGuard`, or `LicenseGuard`
+- Documentation routes have **no tenant prefix** (`/t/:slug/...`) — they are globally accessible
+- Documentation routes require **no specific permission** to access
+
 #### i18n Config Update
 
 **File:** `web/smartstack-web/src/i18n/config.ts`
@@ -230,7 +259,9 @@ 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 registered in App.tsx
+- [x] Route added as child of correct DocsLayout group in App.tsx
+- [x] Route registered in smartstackRoutes.tsx (locked routes)
+- [x] DocsLayout sidebar updated (if applicable)
 - [x] docs-manifest.json updated
 - [x] i18n/config.ts updated with new namespace
 - [x] Module appears in UserIndexPage (if type = user)

package/templates/mcp-scaffolding/frontend/nav-routes.ts.hbs

@@ -1,133 +0,0 @@
-{{!-- SmartStack NavRoute Registry Template --}}
-{{!-- Generates centralized route registry for frontend --}}
-
-/**
- * NavRoute Registry
- *
- * Auto-generated by SmartStack MCP - DO NOT EDIT MANUALLY
- * Generated: {{generatedAt}}
- * Source: {{source}}
- * Routes: {{routeCount}}
- */
-
-export interface NavRoute {
-  /** NavRoute path (e.g., "administration.users") */
-  navRoute: string;
-  /** API endpoint path (e.g., "/api/administration/users") */
-  api: string;
-  /** Frontend route path (e.g., "/administration/users") */
-  web: string;
-  /** Required permissions to access this route */
-  permissions: string[];
-  /** Backend controller name */
-  controller?: string;
-  /** Supported HTTP methods */
-  methods: string[];
-}
-
-/**
- * All registered NavRoutes
- */
-export const ROUTES: Record<string, NavRoute> = {
-{{#each routes}}
-  '{{this.navRoute}}': {
-    navRoute: '{{this.navRoute}}',
-    api: '{{this.apiPath}}',
-    web: '{{this.webPath}}',
-    permissions: [{{#each this.permissions}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}],
-{{#if this.controller}}
-    controller: '{{this.controller}}',
-{{/if}}
-    methods: [{{#each this.methods}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}],
-  },
-{{/each}}
-};
-
-/**
- * Get route configuration by NavRoute path
- * @throws Error if route not found
- */
-export function getRoute(navRoute: string): NavRoute {
-  const route = ROUTES[navRoute];
-  if (!route) {
-    throw new Error(`Route not found: ${navRoute}. Run scaffold_routes to regenerate.`);
-  }
-  return route;
-}
-
-/**
- * Safely get route configuration, returns undefined if not found
- */
-export function tryGetRoute(navRoute: string): NavRoute | undefined {
-  return ROUTES[navRoute];
-}
-
-/**
- * Check if user has permission for route
- */
-export function hasRoutePermission(navRoute: string, userPermissions: string[]): boolean {
-  const route = ROUTES[navRoute];
-  if (!route || route.permissions.length === 0) return true;
-  return route.permissions.some(p => userPermissions.includes(p));
-}
-
-/**
- * Get all routes for an application (e.g., "administration")
- */
-export function getRoutesByApplication(application: string): NavRoute[] {
-  return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${application}.`));
-}
-
-/**
- * Get all routes for an application and module (e.g., "administration.users")
- */
-export function getRoutesByModule(application: string, module: string): NavRoute[] {
-  const prefix = `${application}.${module}`;
-  return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${prefix}.`) || r.navRoute === prefix);
-}
-
-/**
- * Get all unique applications
- */
-export function getApplications(): string[] {
-  const applications = new Set<string>();
-  for (const route of Object.values(ROUTES)) {
-    applications.add(route.navRoute.split('.')[0]);
-  }
-  return Array.from(applications);
-}
-
-/**
- * Get all unique modules within an application
- */
-export function getModules(application: string): string[] {
-  const modules = new Set<string>();
-  for (const route of Object.values(ROUTES)) {
-    const parts = route.navRoute.split('.');
-    if (parts[0] === application && parts.length >= 2) {
-      modules.add(parts[1]);
-    }
-  }
-  return Array.from(modules);
-}
-
-/**
- * Build API URL from NavRoute with optional path segments
- */
-export function buildApiUrl(navRoute: string, ...segments: string[]): string {
-  const route = getRoute(navRoute);
-  if (segments.length === 0) return route.api;
-  return `${route.api}/${segments.join('/')}`;
-}
-
-/**
- * Build frontend URL from NavRoute with optional path segments
- */
-export function buildWebUrl(navRoute: string, ...segments: string[]): string {
-  const route = getRoute(navRoute);
-  if (segments.length === 0) return route.web;
-  return `${route.web}/${segments.join('/')}`;
-}
-
-// Route count for debugging
-export const ROUTE_COUNT = {{routeCount}};

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];