@atlashub/smartstack-cli 3.37.0 → 3.38.0

package/templates/skills/application/references/backend-seeding-and-dto-output.md

@@ -0,0 +1,83 @@
+# Backend Generation: Entity Seeding & Output Formatting
+
+> Referenced from `steps/step-04-backend.md` — Optional seeding and MCP response handling.
+
+---
+
+## Entity Seeding (Optional)
+
+Ask the user if they want to seed initial data for the entity:
+
+```yaml
+questions:
+  - header: "Seed Data"
+    question: "Would you like to generate initial seed data for {EntityName}?"
+    options:
+      - label: "Yes - Generate SeedData provider"
+        description: "Creates {EntityName}SeedData.cs + registers in DevDataSeeder (same pattern as core)"
+      - label: "No - Skip seeding"
+        description: "Entity starts empty (can add seed data later)"
+    multiSelect: false
+```
+
+**If user selects YES:**
+
+See [references/backend-entity-seeding.md](../references/backend-entity-seeding.md) for the full seeding pattern:
+1. **SeedData file** (`{EntityName}SeedData.cs`) — static class with deterministic GUIDs, 3-5 samples
+2. **DevDataSeeder update** — add `Seed{EntityName}sAsync()` method with idempotent check
+
+**If user selects NO:**
+
+Skip this section and proceed to storing entity info.
+
+```markdown
+> Skipping entity seed data. You can generate it later using the SeedData provider pattern
+> documented in templates-seed.md.
+```
+
+---
+
+## Presenting Output to User
+
+Display generated backend code organized by layer:
+
+### Domain Layer
+- `Domain/{Application}/{Module}/{EntityName}.cs`
+
+### Infrastructure Layer
+- `Persistence/Configurations/{Application}/{Module}/{EntityName}Configuration.cs`
+- `Services/{Application}/{Module}/{EntityName}Service.cs`
+
+### Application Layer
+- `Common/Interfaces/I{EntityName}Service.cs`
+- `{Application}/{Module}/DTOs/{EntityName}ResponseDto.cs`
+- `{Application}/{Module}/DTOs/Create{EntityName}Dto.cs`
+- `{Application}/{Module}/DTOs/Update{EntityName}Dto.cs`
+
+### API Layer
+- `Controllers/{controller_folder}/{Application}/{EntityName}Controller.cs`
+  - NavRoute: `{full_path}`
+  - Endpoints:
+    - GET /api/{code} - List all
+    - GET /api/{code}/{id} - Get by ID
+    - POST /api/{code} - Create
+    - PUT /api/{code}/{id} - Update
+    - DELETE /api/{code}/{id} - Delete
+
+### Next Steps
+1. Add DbSet to ICoreDbContext: `public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();`
+2. Register service in DI: `services.AddScoped<I{EntityName}Service, {EntityName}Service>();`
+3. Run: `dotnet ef migrations add core_vX.X.X_XXX_Add{EntityName}`
+
+---
+
+## Entity Info Storage
+
+Store for use in frontend generation:
+
+```
+{entity_name} = "{EntityName}"
+{entity_code} = "{code}"
+{api_route} = "/api/{code}"
+{has_seed_data} = true/false  // Whether SeedData provider was generated
+```

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={<BusinessLayout />}>
+  {/* ... 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.*` | `AdminLayout` | `/administration` |
+| `*` (business apps) | `BusinessLayout` | `/{application}` |
+| `myspace.*` | `UserLayout` | `/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 Layout wrapper (BusinessLayout, AdminLayout, UserLayout)
+- [ ] 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 Layout wrapper (e.g. `SalesLayout`, `AdminLayout`, or `UserLayout`)
 - **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,120 @@
+# 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) |
+
+---
+
+## Parameter Extraction
+
+Required parameters to extract:
+
+```yaml
+# Required
+level: application | module | section
+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" (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.