@atlashub/smartstack-cli 3.23.0 → 3.25.0

package/dist/mcp-entry.mjs

@@ -34500,6 +34500,8 @@ public interface I{{name}}Service
   const implementationTemplate = `using System.Threading;
 using System.Threading.Tasks;
 using System.Collections.Generic;
+using System.Linq;
+using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging;
 using SmartStack.Application.Common.Interfaces.Identity;
 using SmartStack.Application.Common.Interfaces.Persistence;
@@ -34509,6 +34511,7 @@ namespace {{implNamespace}};
 /// <summary>
 /// Service implementation for {{name}} operations.
 /// IMPORTANT: All queries MUST filter by _currentUser.TenantId for multi-tenant isolation.
+/// IMPORTANT: GetAllAsync MUST support search parameter for frontend EntityLookup component.
 /// </summary>
 public class {{name}}Service : I{{name}}Service
 {
@@ -34532,6 +34535,10 @@ public class {{name}}Service : I{{name}}Service
     {
         _logger.LogInformation("Executing {{this}} for tenant {TenantId}", _currentUser.TenantId);
         // TODO: Implement {{this}} \u2014 ALL queries must filter by _currentUser.TenantId
+        // IMPORTANT: GetAllAsync MUST accept (string? search, int page, int pageSize) parameters
+        // to enable EntityLookup search on the frontend. Example:
+        //   if (!string.IsNullOrWhiteSpace(search))
+        //       query = query.Where(x => x.Name.Contains(search) || x.Code.Contains(search));
         await Task.CompletedTask;
         throw new NotImplementedException();
     }
@@ -35344,6 +35351,27 @@ export function use{{name}}(options: Use{{name}}Options = {}) {
   const componentImportPath = hierarchy.context && hierarchy.module ? `@/components/${hierarchy.context.toLowerCase()}/${hierarchy.module.toLowerCase()}/${name}` : `./components/${name}`;
   result.instructions.push(`import { ${name} } from '${componentImportPath}';`);
   result.instructions.push(`import { use${name} } from '@/hooks/use${name}';`);
+  result.instructions.push("");
+  result.instructions.push("### IMPORTANT: Foreign Key Fields in Forms");
+  result.instructions.push("If this entity has FK fields (e.g., EmployeeId, DepartmentId):");
+  result.instructions.push("- NEVER render FK Guid fields as plain text inputs");
+  result.instructions.push("- ALWAYS use EntityLookup component from @/components/ui/EntityLookup");
+  result.instructions.push("- EntityLookup provides searchable dropdown with API-backed search");
+  result.instructions.push("- See smartstack-frontend.md section 6 for the full EntityLookup pattern");
+  result.instructions.push("");
+  result.instructions.push("Example:");
+  result.instructions.push("```tsx");
+  result.instructions.push('import { EntityLookup } from "@/components/ui/EntityLookup";');
+  result.instructions.push("");
+  result.instructions.push("<EntityLookup");
+  result.instructions.push('  apiEndpoint="/api/{context}/{app}/{related-entity}"');
+  result.instructions.push("  value={formData.relatedEntityId}");
+  result.instructions.push('  onChange={(id) => handleChange("relatedEntityId", id)}');
+  result.instructions.push('  label="Related Entity"');
+  result.instructions.push("  mapOption={(item) => ({ id: item.id, label: item.name, sublabel: item.code })}");
+  result.instructions.push("  required");
+  result.instructions.push("/>");
+  result.instructions.push("```");
 }
 async function scaffoldTest(name, options, structure, config2, result, dryRun = false) {
   const isSystemEntity = options?.isSystemEntity || false;
@@ -56982,16 +57010,46 @@ async function scaffoldRoutes(input, config2) {
     result.instructions.push("");
     result.instructions.push("Add routes to `contextRoutes.{context}[]` with **RELATIVE** paths (no leading `/`):");
     result.instructions.push("");
+    result.instructions.push("**IMPORTANT:** Pages are lazy-loaded. Use `<Suspense fallback={<PageLoader />}>` wrapper.");
+    result.instructions.push("");
     result.instructions.push("```tsx");
+    result.instructions.push("import { lazy, Suspense } from 'react';");
+    result.instructions.push("import { PageLoader } from '@/components/ui/PageLoader';");
+    result.instructions.push("");
+    const importedComponents = /* @__PURE__ */ new Set();
+    for (const [context, applications] of Object.entries(routeTree)) {
+      for (const [, modules] of Object.entries(applications)) {
+        for (const route of modules) {
+          const pageEntry = pageFiles.get(route.navRoute);
+          if (pageEntry) {
+            for (const entry of pageEntry) {
+              if (!importedComponents.has(entry.componentName)) {
+                importedComponents.add(entry.componentName);
+                result.instructions.push(`const ${entry.componentName} = lazy(() =>`);
+                result.instructions.push(`  import('${entry.importPath}').then(m => ({ default: m.${entry.componentName} }))`);
+                result.instructions.push(");");
+              }
+            }
+          } else {
+            const component = route.navRoute.split(".").map(capitalize).join("") + "Page";
+            if (!importedComponents.has(component)) {
+              importedComponents.add(component);
+              result.instructions.push(`// TODO: const ${component} = lazy(() => import('@/pages/...'));`);
+            }
+          }
+        }
+      }
+    }
+    result.instructions.push("");
     result.instructions.push("const contextRoutes: ContextRouteExtensions = {");
     for (const [context, applications] of Object.entries(routeTree)) {
       result.instructions.push(`  ${context}: [`);
       for (const [, modules] of Object.entries(applications)) {
         for (const route of modules) {
-          const modulePath = route.navRoute.split(".").slice(1).join("/");
+          const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
           const pageEntry = pageFiles.get(route.navRoute);
           const component = pageEntry?.[0]?.componentName || `${route.navRoute.split(".").map(capitalize).join("")}Page`;
-          result.instructions.push(`    { path: '${modulePath}', element: <${component} /> },`);
+          result.instructions.push(`    { path: '${modulePath}', element: <Suspense fallback={<PageLoader />}><${component} /></Suspense> },`);
         }
       }
       result.instructions.push("  ],");
@@ -57004,7 +57062,8 @@ async function scaffoldRoutes(input, config2) {
     result.instructions.push("");
     result.instructions.push('### Pattern B: JSX Routes (if App.tsx uses `<Route path="/{context}" element={<{Layout} />}>`)');
     result.instructions.push("");
-    result.instructions.push("Insert `<Route>` children INSIDE the appropriate Layout wrapper:");
+    result.instructions.push("Insert `<Route>` children INSIDE the appropriate Layout wrapper.");
+    result.instructions.push("**IMPORTANT:** Use `<Suspense fallback={<PageLoader />}>` for lazy-loaded pages.");
     result.instructions.push("");
     for (const [context, applications] of Object.entries(routeTree)) {
       const layoutName = getLayoutName(context);
@@ -57013,10 +57072,10 @@ async function scaffoldRoutes(input, config2) {
       result.instructions.push("```tsx");
       for (const [, modules] of Object.entries(applications)) {
         for (const route of modules) {
-          const modulePath = route.navRoute.split(".").slice(1).join("/");
+          const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
           const pageEntry = pageFiles.get(route.navRoute);
           const component = pageEntry?.[0]?.componentName || `${route.navRoute.split(".").map(capitalize).join("")}Page`;
-          result.instructions.push(`<Route path="${modulePath}" element={<${component} />} />`);
+          result.instructions.push(`<Route path="${modulePath}" element={<Suspense fallback={<PageLoader />}><${component} /></Suspense>} />`);
         }
       }
       result.instructions.push("```");
@@ -57116,11 +57175,11 @@ async function discoverNavRoutes(structure, scope, warnings) {
           permissions.push(match2[1]);
         }
         const fullNavRoute = suffix ? `${navRoute}.${suffix}` : navRoute;
-        const expectedRoute = `api/${navRoute.replace(/\./g, "/")}${suffix ? `/${suffix}` : ""}`;
+        const expectedRoute = `api/${navRouteToUrlPath(navRoute)}${suffix ? `/${toKebabCase(suffix)}` : ""}`;
         routes.push({
           navRoute: fullNavRoute,
-          apiPath: `/api/${navRoute.replace(/\./g, "/")}${suffix ? `/${suffix}` : ""}`,
-          webPath: `/${navRoute.replace(/\./g, "/")}${suffix ? `/${suffix}` : ""}`,
+          apiPath: `/api/${navRouteToUrlPath(navRoute)}${suffix ? `/${toKebabCase(suffix)}` : ""}`,
+          webPath: `/${navRouteToUrlPath(navRoute)}${suffix ? `/${toKebabCase(suffix)}` : ""}`,
           permissions,
           controller: controllerName,
           methods
@@ -57255,34 +57314,37 @@ function generateRouterConfig(routes, includeGuards) {
     " */",
     "",
     "import { createBrowserRouter, RouteObject } from 'react-router-dom';",
-    "import { ROUTES } from './navRoutes.generated';"
+    "import { lazy, Suspense } from 'react';",
+    "import { ROUTES } from './navRoutes.generated';",
+    "import { PageLoader } from '@/components/ui/PageLoader';"
   ];
   if (includeGuards) {
     lines.push("import { ProtectedRoute, PermissionGuard } from './guards';");
   }
   const contexts = Object.keys(routeTree);
   for (const context of contexts) {
-    lines.push(`import { ${capitalize(context)}Layout } from '../layouts/${capitalize(context)}Layout';`);
+    const name = `${capitalize(context)}Layout`;
+    lines.push(`const ${name} = lazy(() => import('../layouts/${name}').then(m => ({ default: m.${name} })));`);
   }
   lines.push("");
-  lines.push("// Page imports - customize these paths");
+  lines.push("// Page imports - lazy loaded (customize paths)");
   for (const route of routes) {
     const pageName = route.navRoute.split(".").map(capitalize).join("");
-    lines.push(`// import { ${pageName}Page } from '../pages/${pageName}Page';`);
+    lines.push(`// const ${pageName}Page = lazy(() => import('../pages/${pageName}Page').then(m => ({ default: m.${pageName}Page })));`);
   }
   lines.push("");
   lines.push("const routes: RouteObject[] = [");
   for (const [context, applications] of Object.entries(routeTree)) {
     lines.push("  {");
     lines.push(`    path: '${context}',`);
-    lines.push(`    element: <${capitalize(context)}Layout />,`);
+    lines.push(`    element: <Suspense fallback={<PageLoader />}><${capitalize(context)}Layout /></Suspense>,`);
     lines.push("    children: [");
     for (const [app, modules] of Object.entries(applications)) {
       lines.push("      {");
       lines.push(`        path: '${app}',`);
       lines.push("        children: [");
       for (const route of modules) {
-        const modulePath = route.navRoute.split(".").slice(2).join("/");
+        const modulePath = route.navRoute.split(".").slice(2).map(toKebabCase).join("/");
         const pageName = route.navRoute.split(".").map(capitalize).join("");
         if (includeGuards && route.permissions.length > 0) {
           lines.push("          {");
@@ -57503,7 +57565,9 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
     "",
     "import type { RouteObject } from 'react-router-dom';",
     "import type { ContextRouteExtensions } from '@atlashub/smartstack';",
-    "import { Navigate } from 'react-router-dom';"
+    "import { lazy, Suspense } from 'react';",
+    "import { Navigate } from 'react-router-dom';",
+    "import { PageLoader } from '@/components/ui/PageLoader';"
   ];
   if (includeGuards) {
     lines.push("import { ROUTES } from './navRoutes.generated';");
@@ -57516,7 +57580,9 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
     if (pageEntries) {
       for (const entry of pageEntries) {
         if (!importedComponents.has(entry.componentName)) {
-          lines.push(`import { ${entry.componentName} } from '${entry.importPath}';`);
+          lines.push(`const ${entry.componentName} = lazy(() =>`);
+          lines.push(`  import('${entry.importPath}').then(m => ({ default: m.${entry.componentName} }))`);
+          lines.push(");");
           importedComponents.add(entry.componentName);
         }
       }
@@ -57525,7 +57591,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
   for (const route of routes) {
     if (!pageFiles.has(route.navRoute)) {
       const pageName = route.navRoute.split(".").map(capitalize).join("") + "Page";
-      lines.push(`// TODO: import { ${pageName} } from '@/pages/...';`);
+      lines.push(`// TODO: const ${pageName} = lazy(() => import('@/pages/...').then(m => ({ default: m.${pageName} })));`);
     }
   }
   lines.push("");
@@ -57542,10 +57608,10 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
         lines.push("  {");
         lines.push(`    path: '${app}',`);
         lines.push("    children: [");
-        const firstModulePath = modules[0].navRoute.split(".").slice(2).join("/");
+        const firstModulePath = modules[0].navRoute.split(".").slice(2).map(toKebabCase).join("/");
         lines.push(`      { index: true, element: <Navigate to="${firstModulePath}" replace /> },`);
         for (const route of modules) {
-          const modulePath = route.navRoute.split(".").slice(2).join("/");
+          const modulePath = route.navRoute.split(".").slice(2).map(toKebabCase).join("/");
           const pageName = route.navRoute.split(".").map(capitalize).join("") + "Page";
           const pageEntry = pageFiles.get(route.navRoute);
           const component = pageEntry?.[0]?.componentName || pageName;
@@ -57554,7 +57620,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
             lines.push(`      {`);
             lines.push(`        path: '${modulePath}',`);
             if (hasRealPage) {
-              lines.push(`        element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard>,`);
+              lines.push(`        element: <Suspense fallback={<PageLoader />}><PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard></Suspense>,`);
             } else {
               lines.push(`        element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><div>TODO: ${component}</div></PermissionGuard>,`);
             }
@@ -57562,7 +57628,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
           } else {
             lines.push(`      {`);
             lines.push(`        path: '${modulePath}',`);
-            lines.push(`        element: ${hasRealPage ? `<${component} />` : `<div>TODO: ${component}</div>`},`);
+            lines.push(`        element: ${hasRealPage ? `<Suspense fallback={<PageLoader />}><${component} /></Suspense>` : `<div>TODO: ${component}</div>`},`);
             lines.push(`      },`);
           }
         }
@@ -57570,7 +57636,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
         lines.push("  },");
       } else {
         for (const route of modules) {
-          const fullPath = route.navRoute.split(".").slice(1).join("/");
+          const fullPath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
           const pageName = route.navRoute.split(".").map(capitalize).join("") + "Page";
           const pageEntry = pageFiles.get(route.navRoute);
           const component = pageEntry?.[0]?.componentName || pageName;
@@ -57579,7 +57645,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
             lines.push(`  {`);
             lines.push(`    path: '${fullPath}',`);
             if (hasRealPage) {
-              lines.push(`    element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard>,`);
+              lines.push(`    element: <Suspense fallback={<PageLoader />}><PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard></Suspense>,`);
             } else {
               lines.push(`    element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><div>TODO: ${component}</div></PermissionGuard>,`);
             }
@@ -57587,7 +57653,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
           } else {
             lines.push(`  {`);
             lines.push(`    path: '${fullPath}',`);
-            lines.push(`    element: ${hasRealPage ? `<${component} />` : `<div>TODO: ${component}</div>`},`);
+            lines.push(`    element: ${hasRealPage ? `<Suspense fallback={<PageLoader />}><${component} /></Suspense>` : `<div>TODO: ${component}</div>`},`);
             lines.push(`  },`);
           }
         }
@@ -57632,6 +57698,12 @@ function getLayoutName(context) {
   };
   return layoutMap[context] || `${capitalize(context)}Layout`;
 }
+function toKebabCase(segment) {
+  return segment.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function navRouteToUrlPath(navRoute) {
+  return navRoute.split(".").map(toKebabCase).join("/");
+}
 function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }