@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/skills/application/references/backend-table-prefix-mapping.md

@@ -0,0 +1,79 @@
+# Backend: Table Prefix & Controller Folder Mapping
+
+> Referenced from `steps/step-04-backend.md` — Deriving table prefixes and controller organization.
+
+---
+
+## Table Prefix Priority
+
+1. **If a `feature.json` exists** with `metadata.tablePrefix` → use that prefix (e.g., `rh_`, `fi_`)
+2. **Otherwise**, derive from navigation context using the fallback table below
+
+---
+
+## Fallback Table (when no feature.json tablePrefix)
+
+| Application | Table Prefix | Controller Folder | Example |
+|---------|--------|-------------------|---------|
+| `administration.*` | `auth_` or `cfg_` | `Administration` | Table: `auth_Tenants`, Controller: `Controllers/Administration/TenantsController.cs` |
+| `support.*` | `support_` | `Support` | Table: `support_Tickets`, Controller: `Controllers/Support/TicketsController.cs` |
+| `*` (business apps) | `ref_` or domain-specific | `{ApplicationPascal}` | Table: `ref_Products`, Controller: `Controllers/Sales/ProductsController.cs` |
+| `myspace.*` | `usr_` | `MySpace` | Table: `usr_Preferences`, Controller: `Controllers/MySpace/PreferencesController.cs` |
+
+---
+
+## Feature.json Table Prefix Detection
+
+```
+Search for feature.json in:
+  - docs/business/{application}/business-analyse/*/feature.json
+  - Read metadata.tablePrefix if exists
+```
+
+**Example from feature.json:**
+
+```json
+{
+  "metadata": {
+    "tablePrefix": "rh_",
+    "schema": "core"
+  },
+  "analysis": { ... }
+}
+```
+
+---
+
+## Implementation
+
+```csharp
+// Check for feature.json tablePrefix
+Search for feature.json in:
+  - docs/business/{application}/business-analyse/*/feature.json
+  - Read metadata.tablePrefix if exists
+
+IF metadata.tablePrefix exists:
+  {prefix} = metadata.tablePrefix   # e.g., "rh_"
+ELSE:
+  {prefix} = derived from context table above
+```
+
+Store: `{controller_folder}` = the Controller Folder from the table above.
+
+---
+
+## Usage in MCP Call
+
+When calling `mcp__smartstack__scaffold_extension`:
+
+```
+Tool: mcp__smartstack__scaffold_extension
+Args:
+  type: "feature"
+  name: "{entityName}"
+  options:
+    navRoute: "{full_path}"
+    tablePrefix: "{prefix}"        ← Derived prefix
+    schema: "core"
+    ...
+```

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

@@ -30,7 +30,7 @@ services.AddScoped<I{EntityName}Service, {EntityName}Service>();
 
 ## Check 4: RequirePermission Attributes (BLOCKING)
 
-Each HTTP action MUST have `[RequirePermission(Permissions.{Context}.{Application}.{Module}.{Action})]`.
+Each HTTP action MUST have `[RequirePermission(Permissions.{Application}.{Module}.{Action})]`.
 
 ## Check 5: Entity Configuration (BLOCKING)
 

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

@@ -0,0 +1,67 @@
+# Frontend: i18n Structure & Output Formatting
+
+> Referenced from `steps/step-05-frontend.md` — i18n files and output presentation.
+
+---
+
+## i18n Structure
+
+All i18n files must follow this structure:
+
+```
+locales/
+├── fr/
+│   └── {entityCode}.json
+├── en/
+│   └── {entityCode}.json
+├── it/
+│   └── {entityCode}.json
+└── de/
+    └── {entityCode}.json
+```
+
+**Note:** i18n files are auto-generated by `type: "page"` scaffold. Verify the 4 language files were created and customize the `title`/`subtitle` with proper labels.
+
+If customization needed:
+- `i18n/locales/fr/{entityCode}.json` → set `"title": "{labels.fr}"`
+- `i18n/locales/en/{entityCode}.json` → set `"title": "{labels.en}"`
+- `i18n/locales/it/{entityCode}.json` → set `"title": "{labels.it}"`
+- `i18n/locales/de/{entityCode}.json` → set `"title": "{labels.de}"`
+
+---
+
+## Presenting Output to User
+
+Display generated frontend code organized by category:
+
+### Pages
+- `pages/{application}/{module}/{EntityName}Page.tsx`
+- `pages/{application}/{module}/{EntityName}ListView.tsx`
+
+### Components
+- `components/{application}/{module}/{EntityName}.tsx`
+- `hooks/use{EntityName}.ts`
+
+### API Client
+- `services/api/{entityCode}Api.ts`
+- `types/{entityName}.types.ts`
+
+### Routes
+- Updated `navRoutes.generated.ts`
+- Generated `clientRoutes.generated.tsx`
+- Wired routes in `App.tsx` (standard + tenant blocks)
+
+### i18n
+- `locales/fr/{entityCode}.json`
+- `locales/en/{entityCode}.json`
+- `locales/it/{entityCode}.json`
+- `locales/de/{entityCode}.json`
+
+### Route Configuration Example
+```tsx
+// In routes.tsx - NESTED routes (not flat!)
+<Route path="{application_kebab}">
+  <Route index element={<Navigate to="{module_kebab}" replace />} />
+  <Route path="{module_kebab}" element={<{EntityName}Page />} />
+</Route>
+```

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

@@ -0,0 +1,117 @@
+# Frontend: Route Naming & Kebab-Case Requirements
+
+> Referenced from `steps/step-05-frontend.md` — Route path conventions and naming rules.
+
+---
+
+## Route Naming Rule (BLOCKING)
+
+All route paths MUST use **kebab-case** to match navigation seed data exactly.
+
+**Transformation:** `PascalCase` → `kebab-case`
+
+Examples:
+- `HumanResources` → `human-resources`
+- `Employees` → `employees`
+- `TimeManagement` → `time-management`
+- `OrderItems` → `order-items`
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Issue |
+|---------|-------|
+| `humanresources` | Concatenated words without hyphens |
+| `timemanagement` | Missing hyphens in multi-word names |
+| `mymodule` | Ambiguous (is this "my-module" or literal "mymodule"?) |
+
+---
+
+## Required Patterns
+
+| Pattern | Correct Usage |
+|---------|---------------|
+| `human-resources` | Multi-word segment with proper hyphens |
+| `time-management` | Proper kebab-case |
+| `employees` | Single-word segments stay lowercase |
+| `products` | Single-word segments stay lowercase |
+
+---
+
+## Verification
+
+Route paths MUST match the navigation seed data routes (which use `ToKebabCase()`).
+
+**Example verification:**
+
+Navigation seed data:
+```csharp
+Route = "/human-resources/time-management"  // From ToKebabCase()
+```
+
+App.tsx routes must use:
+```tsx
+const applicationRoutes: ApplicationRouteExtensions = {
+  'human-resources': [  // ← kebab-case
+    { path: 'time-management', element: <TimeManagementPage /> },  // ← kebab-case
+  ],
+};
+```
+
+---
+
+## Kebab-Case Conversion Rules
+
+| Input | Output | Rule |
+|-------|--------|------|
+| `ProductCode` | `product-code` | Insert `-` before uppercase letters |
+| `Product` | `product` | Lowercase single words |
+| `IDs` | `ids` | Lowercase acronyms |
+| `HTTPSConnection` | `https-connection` | Insert `-` before each uppercase cluster transition |
+| `CamelCaseExample` | `camel-case-example` | Insert `-` at each camelCase boundary |
+
+---
+
+## Implementation Pattern
+
+When generating routes, apply kebab-case to all multi-word segments:
+
+```tsx
+// CORRECT
+<Route path="/human-resources" element={<HRLayout />}>
+  <Route path="employees" element={<EmployeesPage />} />
+  <Route path="time-management" element={<TimeManagementPage />} />
+</Route>
+
+// FORBIDDEN
+<Route path="/humanresources" element={<HRLayout />} />
+<Route path="/HR" element={<HRLayout />} />
+<Route path="/human_resources" element={<HRLayout />} />
+```
+
+---
+
+## Cross-Reference with Navigation Seeds
+
+Before finalizing route paths, verify they match navigation seeds:
+
+**Step 1:** Extract application code from `{full_path}` (e.g., `human-resources.time-management` → app: `human-resources`)
+
+**Step 2:** Check existing navigation seeds:
+```bash
+Glob: **/Seeding/Data/Navigation/NavigationApplicationSeedData.cs
+Search for: Route = "/{application_kebab}"
+```
+
+**Step 3:** Ensure App.tsx routes use the exact same kebab-case format.
+
+---
+
+## Validation Checklist
+
+- [ ] All multi-word segments use hyphens (kebab-case)
+- [ ] Single-word segments are lowercase
+- [ ] Route paths match navigation seed data routes
+- [ ] No uppercase letters in route paths
+- [ ] No underscores (`_`) or camelCase in paths

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

@@ -0,0 +1,107 @@
+# Frontend: Route Wiring in App.tsx
+
+> Referenced from `steps/step-05-frontend.md` — Detailed route wiring patterns and verification.
+
+---
+
+## Step 4: Wire Routes to App.tsx (BLOCKING)
+
+**CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.
+
+After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
+
+---
+
+## Step 4a: Import Page Components
+
+At the top of App.tsx:
+
+```tsx
+import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
+// Or lazy-loaded:
+const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{EntityName}Page'));
+```
+
+---
+
+## 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}', element: <{EntityName}ListPage /> },
+    { path: '{module_kebab}/new', element: <Create{EntityName}Page /> },
+    { path: '{module_kebab}/:id', element: <{EntityName}DetailPage /> },
+    { path: '{module_kebab}/:id/edit', element: <Create{EntityName}Page /> },
+  ],
+};
+```
+
+Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
+
+### Pattern B: JSX Routes
+
+**If App.tsx contains:** `<Route path="/{application}" element={<{Layout} />}>`
+
+→ Insert `<Route>` children inside the Layout wrapper:
+
+```tsx
+<Route path="/human-resources" element={<AppLayout />}>
+  {/* ... existing routes ... */}
+  <Route path="{module_kebab}" element={<{EntityName}Page />} />
+</Route>
+```
+
+**ALSO add the same routes inside the tenant-prefixed block:**
+
+Find `<Route path="/t/:slug">` and add the **same route entries** there.
+
+---
+
+## Step 4c: Application-to-Layout Mapping
+
+| Application prefix | Layout Component | Route path |
+|---------|------------------|------------|
+| `administration.*` | `AppLayout` | `/administration` |
+| `*` (business apps) | `AppLayout` | `/{application}` |
+| `myspace.*` | `AppLayout` | `/myspace` |
+
+---
+
+## Step 4d: Verify Wiring
+
+```
+Tool: mcp__smartstack__validate_frontend_routes
+Args:
+  scope: "routes"
+```
+
+If `appWiring.issues` is not empty, fix the wiring before proceeding.
+
+---
+
+## 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()`)
+
+---
+
+## Verification Checklist
+
+- [ ] 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

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

@@ -9,13 +9,13 @@
 **CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
 
 ```tsx
-// CORRECT - Inside BusinessLayout (shell renders: header + AvatarMenu + sidebar)
-<Route path="/business" element={<BusinessLayout />}>
-  <Route path="sales/products" element={<ProductsPage />} />
+// CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/sales" element={<SalesLayout />}>
+  <Route path="products" element={<ProductsPage />} />
 </Route>
 
 // FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
-<Route path="/business/sales/products" element={<ProductsPage />} />
+<Route path="/sales/products" element={<ProductsPage />} />
 ```
 
 ### Rule 2: Use nested routes (not flat)
@@ -24,8 +24,8 @@
 
 ```tsx
 // CORRECT - Nested routes inside layout
-<Route path="/business" element={<BusinessLayout />}>
-  <Route path="sales">
+<Route path="/sales" element={<SalesLayout />}>
+  <Route path="products">
     <Route index element={<Navigate to="products" replace />} />
     <Route path="products" element={<ProductsPage />} />
     <Route path="orders" element={<OrdersPage />} />
@@ -33,8 +33,8 @@
 </Route>
 
 // FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
-<Route path="/business/sales" element={<Navigate to="products" />} />
-<Route path="/business/sales/products" element={<ProductsPage />} />
+<Route path="/sales/products" element={<Navigate to="products" />} />
+<Route path="/sales/products" element={<ProductsPage />} />
 ```
 
 ## Post-Generation Verification (MANDATORY)
@@ -74,9 +74,9 @@ Verify exactly **4 language files** exist with identical key structures:
 ### 5. Route Check (BLOCKING)
 
 Verify routes are:
-- **INSIDE** the Layout wrapper (`BusinessLayout`, `AdminLayout`, or `UserLayout`)
+- **INSIDE** the AppLayout wrapper
 - **NESTED** (not flat)
-- Following path convention: `/{context}/{application_kebab}/{module_kebab}` (kebab-case)
+- Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)
 
 ### 5b. Route Wiring 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 `contextRoutes` and `<Route path="...">`)
+1. Extract all route path strings from App.tsx (both `applicationRoutes` and `<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`)
@@ -150,7 +150,7 @@ Common issues: missing imports, wrong interface names, incorrect prop types, mis
 IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.
 
 **Focus only on errors in files generated by this step:**
-- `pages/{context}/{application}/{module}/*.tsx`
+- `pages/{application}/{module}/*.tsx`
 - `services/api/{entityCode}Api.ts`
 - `types/{entityName}.types.ts`
 - `hooks/use{EntityName}*.ts`

package/templates/skills/application/references/init-parameter-detection.md

@@ -0,0 +1,121 @@
+# Initialization: Parameter Detection & Extraction
+
+> Referenced from `steps/step-00-init.md` — Parameter parsing and MCP validation.
+
+---
+
+## Navigation Level Detection
+
+From user request, identify the level:
+
+| Hint in Request | → Level | Parent Required |
+|-----------------|---------|-----------------|
+| "application", "app", "nouvelle application" | application | No |
+| "module", "feature", "nouveau module" | module | Yes (application) |
+| "section", "tab", "nouvelle section" | section | Yes (application.module) |
+| "resource", "sous-section" | resource | Yes (application.module.section) |
+
+---
+
+## Parameter Extraction
+
+Required parameters to extract:
+
+```yaml
+# Required
+level: application | module | section | resource
+code: kebab-case (e.g., "products", "order-management")
+labels:
+  fr: "Label français"
+  en: "English label"
+  it: "Etichetta italiana"
+  de: "Deutsche Bezeichnung"
+icon: Lucide icon name (e.g., "Package", "ShoppingCart")
+displayOrder: number
+
+# Conditional (required for module and section levels)
+parentPath: "application.module" or "application.module.section" (dot-separated)
+```
+
+---
+
+## Project Type & Seeding Strategy
+
+Read `.smartstack/config.json` at the project root:
+
+| projectType | dbContext | Seeding Strategy |
+|-------------|----------|-----------------|
+| `core` | `core` | HasData() in Configuration files (existing pattern) |
+| `client` | `extensions` | IClientSeedDataProvider (runtime seeding) |
+
+**If file not found or projectType missing:** Default to `core` / `hasdata`.
+
+Store:
+```
+{project_type} = "core" or "client"
+{db_context} = "core" or "extensions"
+{seeding_strategy} = "hasdata" or "provider"
+```
+
+---
+
+## Feature.json Context (Optional Enrichment)
+
+Search for a Business Analysis feature.json for the target module:
+
+```
+Glob: docs/business/*/{code}/business-analyse/v*/feature.json
+      .business-analyse/business/*/modules/{code}/features/*/feature.json
+```
+
+**If found (status = "handed-off" or "consolidated"):**
+
+Extract context for subsequent steps:
+
+| feature.json Section | Used In Step | Extracted Data |
+|----------------------|-------------|----------------|
+| `analysis.entities[]` | step-04 (backend) | Entity names, attributes, relationships, validations |
+| `specification.useCases[]` | step-04 (backend) | API endpoint definitions beyond basic CRUD |
+| `specification.permissionMatrix` | step-02 (permissions) | Custom permission paths and role assignments |
+| `specification.apiEndpoints[]` | step-04 (backend) | Exact HTTP methods, routes, DTOs |
+| `specification.navigation` | step-01 (navigation) | Navigation hierarchy with labels and icons |
+| `specification.i18nKeys` | step-05 (frontend) | Pre-defined translation keys |
+| `specification.validations[]` | step-04 (backend) | Field-level validation rules |
+| `specification.uiWireframes[]` | step-05 (frontend) | UI layout guidance |
+| `specification.seedDataCore` | step-01, step-02, step-03 | Pre-computed seeds |
+| `analysis.businessRules[]` | step-04, step-07 | Business rules for service logic and tests |
+| `specification.lifeCycles[]` | step-04 (backend) | Entity state machines |
+| `specification.dashboards` | step-05 (frontend) | Dashboard KPIs and chart specs |
+| `documentation` | step-08 | userDocRequired / techDocRequired flags |
+
+Store:
+```
+{feature_json_path} = "path/to/feature.json" or null
+{has_feature_context} = true or false
+{feature_data} = parsed feature.json object (if found)
+```
+
+**If NOT found or status not in ["handed-off", "consolidated"]:**
+```
+{has_feature_context} = false
+```
+
+Continue normally. All subsequent steps use their standard generation logic (generic CRUD).
+
+> **When `{has_feature_context} = true`**, subsequent steps SHOULD use the feature.json data
+> to generate more accurate code: entities with correct attributes and relationships, custom
+> permissions beyond basic CRUD, specific API routes, validation rules, and business logic
+> in services. This reduces post-generation manual corrections significantly.
+
+---
+
+## MCP Prerequisite Check (BLOCKING)
+
+**CRITICAL:** This check is **BLOCKING** - the skill cannot proceed without MCP.
+
+Call: `mcp__smartstack__validate_conventions`
+Args: `{ checks: ["tables"] }`
+
+**On success:** Set `mcp_available = true`, continue.
+
+**On failure (STOP):** Display MCP installation instructions and halt.

package/templates/skills/application/references/migration-checklist-troubleshooting.md

@@ -0,0 +1,100 @@
+# Migration: Checklist & Troubleshooting
+
+> Referenced from `steps/step-06-migration.md` — Migration verification and common issues.
+
+---
+
+## Pre-Migration Build Verification (BLOCKING)
+
+**CRITICAL:** The backend MUST build successfully before creating a migration.
+EF Core tools compile the project internally; a build failure produces confusing errors
+that do not point to the actual source file.
+
+```bash
+dotnet build {SolutionName}.sln --no-restore
+```
+
+**Common causes at this stage:**
+- Missing DbSet registration (should have been caught in step-04 Check 2)
+- Missing DI registration (should have been caught in step-04 Check 3)
+- Circular references between generated services
+- Missing package references (e.g., FluentValidation)
+- Frontend changes that modified shared files
+
+**After build succeeds:** Continue to migration name suggestion.
+
+---
+
+## Migration Content Verification
+
+The migration should include:
+- Navigation entity (Application/Module/Section/Resource)
+- Navigation translations (4 languages)
+- Permissions (CRUD + wildcard)
+- RolePermissions (role assignments)
+- Domain entity table
+- Indexes and constraints
+- SQL Objects injection (if any .sql files exist)
+
+---
+
+## SQL Objects Injection
+
+Check if any SQL object files exist:
+```
+Glob: **/Persistence/SqlObjects/Functions/*.sql
+```
+
+If SQL files are found, the migration's `Up()` method should include a call to re-apply all SQL objects:
+```csharp
+// At the end of the Up() method:
+SqlObjectHelper.ApplyAll(migrationBuilder);
+```
+
+This ensures SQL functions/views are re-applied with each migration (`CREATE OR ALTER` = idempotent).
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Migration conflicts | Run `/efcore:conflicts` to analyze |
+| Permission 403 errors | Verify Permissions.cs and PermissionConfiguration.cs are in sync |
+| Navigation not visible | Check user role has appropriate permissions |
+| Route not found | Verify nested route structure in routes.tsx |
+| i18n missing | Check locale files exist and are properly loaded |
+| EF Core compilation error | Check DbSet and DI registration |
+| FK constraint errors | Verify all entity references exist in seed data |
+
+### Quick Fixes
+
+```bash
+# Rebuild and restart
+dotnet build
+dotnet ef database update
+
+# Clear frontend cache
+cd web && rm -rf node_modules/.cache && npm run dev
+
+# Reset database (development only)
+dotnet ef database drop --context CoreDbContext --force
+dotnet ef database update --context CoreDbContext
+```
+
+---
+
+## Final Checklist
+
+- [ ] Pre-migration build passed
+- [ ] Migration name suggested via MCP
+- [ ] Migration created with correct context
+- [ ] Migration includes navigation, permissions, and entity table
+- [ ] SQL objects injected (if applicable)
+- [ ] Migration applied successfully
+- [ ] Database updated without errors
+- [ ] DbSet registered in DbContext
+- [ ] DI registration in place
+- [ ] Application starts without errors