@atlashub/smartstack-cli 4.74.0 → 4.75.0

package/templates/skills/business-analyse-design/SKILL.md

@@ -89,3 +89,13 @@ Client reviews HTML
 ## Entry Point
 
 **FIRST ACTION:** Load `steps/step-01-screens.md`
+
+<success_criteria>
+- screens.json genere par module avec specifications section/resource
+- Toutes les colonnes SmartTable referencent des attributs d'entite valides
+- Tous les champs SmartForm referencent des attributs d'entite valides
+- Tous les ecrans ont un champ permission valide depuis permissions.json
+- navigation.json genere avec arbre de navigation complet
+- Wireframes inclus dans screens.json avec mockupFormat et elements[]
+- Aucune entite ou permission inventee (toutes referencent Phase 1)
+</success_criteria>

package/templates/skills/business-analyse-design/references/screens-post-check.md

@@ -0,0 +1,221 @@
+# Screens POST-CHECK Validation
+
+This document contains the complete executable validation code for screens.json files. Run this validation after writing ALL screens.json files for a module.
+
+## Validation Levels
+
+- **BLOCKING errors:** Must be fixed before proceeding to the next step
+- **WARNING errors:** Should be reviewed but do not block progress
+
+## Validation Script
+
+```javascript
+for (const mod of modules) {
+  const screensPath = resolveModuleDir(mod.applicationCode, mod.code) + '/screens.json';
+  const entitiesPath = resolveModuleDir(mod.applicationCode, mod.code) + '/entities.json';
+  const permsPath = resolveModuleDir(mod.applicationCode, mod.code) + '/permissions.json';
+
+  const screens = READ(screensPath);
+  const entities = READ(entitiesPath);
+  const perms = READ(permsPath);
+
+  const entityNames = entities.entities.map(e => e.name);
+  const attrMap = {};
+  entities.entities.forEach(e => {
+    attrMap[e.name] = e.attributes.map(a => a.name);
+  });
+  const computedAttrs = {};
+  entities.entities.forEach(e => {
+    computedAttrs[e.name] = e.attributes.filter(a => a.computed).map(a => a.name);
+  });
+
+  for (const section of screens.sections) {
+    // CHECK 1: Every section has at least 1 resource
+    ASSERT(section.resources.length > 0,
+      `BLOCKING: ${mod.code}.${section.sectionCode} has 0 resources`);
+
+    for (const res of section.resources) {
+      // CHECK 2: Every resource has a valid entity
+      ASSERT(entityNames.includes(res.entity),
+        `BLOCKING: ${res.code} references unknown entity "${res.entity}"`);
+
+      // CHECK 3: Every resource has a permission
+      ASSERT(res.permission,
+        `BLOCKING: ${res.code} missing permission`);
+
+      // CHECK 4: SmartTable columns reference valid attributes
+      if (res.type === 'SmartTable' && res.columns) {
+        for (const col of res.columns) {
+          const field = col.field.split('.')[0];
+          ASSERT(attrMap[res.entity]?.includes(field),
+            `BLOCKING: ${res.code} column "${col.field}" not in ${res.entity}`);
+        }
+      }
+
+      // CHECK 5: SmartForm fields reference valid attributes
+      if (res.type === 'SmartForm' && res.tabs) {
+        for (const tab of res.tabs) {
+          if (tab.fields) {
+            for (const f of tab.fields) {
+              ASSERT(attrMap[res.entity]?.includes(f.field),
+                `BLOCKING: ${res.code} field "${f.field}" not in ${res.entity}`);
+            }
+          }
+        }
+      }
+
+      // CHECK 6: Lookup fields have entity
+      if (res.type === 'SmartForm' && res.tabs) {
+        for (const tab of res.tabs) {
+          if (tab.fields) {
+            for (const f of tab.fields) {
+              if (f.type === 'lookup') {
+                ASSERT(f.entity,
+                  `BLOCKING: ${res.code} lookup field "${f.field}" missing entity`);
+              }
+            }
+          }
+        }
+      }
+
+      // CHECK 7: Computed attributes are readonly or absent (WARNING)
+      if (res.type === 'SmartForm' && res.tabs) {
+        const compAttrs = computedAttrs[res.entity] || [];
+        for (const tab of res.tabs) {
+          if (tab.fields) {
+            for (const f of tab.fields) {
+              if (compAttrs.includes(f.field) && !f.readonly) {
+                WARN(`${res.code} field "${f.field}" is computed but not readonly`);
+              }
+            }
+          }
+        }
+      }
+
+      // CHECK 8: SmartFilter filters reference valid fields + lookup entity
+      if (res.type === 'SmartFilter' && res.filters) {
+        for (const filter of res.filters) {
+          if (filter.type === 'lookup') {
+            ASSERT(filter.entity,
+              `BLOCKING: ${res.code} filter "${filter.field}" type lookup missing entity`);
+          }
+        }
+      }
+    }
+  }
+
+  // CHECK 9: SmartFilter mandatory for list sections with SmartTable (BLOCKING)
+  for (const section of screens.sections) {
+    if (section.sectionCode === 'list') {
+      const hasTable = section.resources.some(r => r.type === 'SmartTable');
+      const hasFilter = section.resources.some(r => r.type === 'SmartFilter');
+      if (hasTable && !hasFilter && !mod.code.includes('Portal')) {
+        ASSERT(false, `BLOCKING: ${mod.code}.list has SmartTable but no SmartFilter`);
+      }
+    }
+  }
+
+  // CHECK 10: SmartKanban for workflow entities (WARNING)
+  for (const e of entities.entities) {
+    const statusAttr = e.attributes.find(a => a.name === 'status' && a.type === 'enum');
+    if (statusAttr && (statusAttr.options || []).length >= 3 && !mod.code.includes('Portal')) {
+      const hasKanban = screens.sections.some(s =>
+        s.resources.some(r => r.type === 'SmartKanban' && r.entity === e.name)
+      );
+      if (!hasKanban) {
+        WARN(`${mod.code}: entity "${e.name}" has ${statusAttr.options.length} workflow states but no SmartKanban`);
+      }
+    }
+  }
+}
+```
+
+## Validation Checklist
+
+Run these checks after writing all screens.json files:
+
+- [ ] Every resource has a valid `entity` referencing an entity from entities.json
+- [ ] Every resource has a valid `permission` referencing permissions.json
+- [ ] Every SmartTable column references a valid entity attribute
+- [ ] Every SmartForm field references a valid entity attribute
+- [ ] Every SmartTable `rowActions[]` has `action` and `permission` fields
+- [ ] Every section has at least one resource
+- [ ] Every module has at least one section
+- [ ] Every lookup field (SmartForm + SmartFilter) has an `entity` property
+- [ ] Computed attributes are `readonly: true` in detail forms or absent from create forms
+- [ ] Every `list` section with SmartTable also has a SmartFilter (except Portal)
+- [ ] Every entity with `status` enum >= 3 options has a SmartKanban resource (except Portal/config)
+
+## Check Details
+
+### CHECK 1: Section Resources
+Every section MUST have at least one resource. Empty sections are invalid.
+
+**Error Format:** `BLOCKING: {module}.{sectionCode} has 0 resources`
+
+### CHECK 2: Entity References
+Every resource MUST reference a valid entity name from entities.json.
+
+**Error Format:** `BLOCKING: {resource.code} references unknown entity "{entity}"`
+
+### CHECK 3: Permission References
+Every resource MUST have a permission field.
+
+**Error Format:** `BLOCKING: {resource.code} missing permission`
+
+### CHECK 4: SmartTable Column Attributes
+Every column in a SmartTable MUST reference a valid attribute from the entity. Nested attributes (e.g., `department.name`) are split on the first dot.
+
+**Error Format:** `BLOCKING: {resource.code} column "{field}" not in {entity}`
+
+### CHECK 5: SmartForm Field Attributes
+Every field in a SmartForm tab MUST reference a valid attribute from the entity.
+
+**Error Format:** `BLOCKING: {resource.code} field "{field}" not in {entity}`
+
+### CHECK 6: Lookup Field Entity References
+Every lookup field in a SmartForm MUST include an `entity` property identifying the target entity.
+
+**Error Format:** `BLOCKING: {resource.code} lookup field "{field}" missing entity`
+
+### CHECK 7: Computed Attribute Readonly (WARNING)
+Computed attributes (marked `computed: true` in entities.json) appearing in SmartForm SHOULD have `readonly: true`. This is a warning, not blocking.
+
+**Warning Format:** `{resource.code} field "{field}" is computed but not readonly`
+
+### CHECK 8: SmartFilter Lookup Entity References
+Every lookup filter in a SmartFilter MUST include an `entity` property.
+
+**Error Format:** `BLOCKING: {resource.code} filter "{field}" type lookup missing entity`
+
+### CHECK 9: SmartFilter Mandatory for Lists
+Every `list` section with a SmartTable MUST also include a SmartFilter resource (except for Portal modules).
+
+**Error Format:** `BLOCKING: {module}.list has SmartTable but no SmartFilter`
+
+### CHECK 10: SmartKanban Workflow Detection (WARNING)
+Every entity with a `status` enum attribute having 3 or more options (except Portal/config modules) SHOULD have a SmartKanban resource. This is a warning, not blocking.
+
+**Warning Format:** `{module}: entity "{entity}" has {count} workflow states but no SmartKanban`
+
+## Error Resolution
+
+### BLOCKING Errors
+Stop immediately and fix these errors before proceeding to step-02:
+
+1. Add missing resources to empty sections
+2. Verify entity names match entities.json exactly (case-sensitive)
+3. Add permission properties to all resources
+4. Fix column/field names to match entity attributes
+5. Add entity properties to all lookup fields
+6. Add SmartFilter to list sections with SmartTable
+
+### WARNING Errors
+Review and fix if applicable, but these do not block progress:
+
+1. Add `readonly: true` to computed fields in forms
+2. Consider adding SmartKanban for workflow entities with status enums
+
+## Exit Criteria
+
+All BLOCKING checks must pass before proceeding to step-02. WARNING checks should be reviewed and fixed where applicable.

package/templates/skills/business-analyse-design/references/screens-type-mapping.md

@@ -0,0 +1,138 @@
+# Screens Type Mapping & Business Rules
+
+This document defines how entity attributes map to UI component field types and specifies the business rules for handling computed attributes, readonly fields, lookups, and workflow detection.
+
+## Column/Field Type Mapping
+
+Map entity attribute types to SmartTable columns and SmartForm fields:
+
+| Entity type | SmartTable type | SmartForm type |
+|-------------|----------------|----------------|
+| `string` | `text` | `text` |
+| `int`, `decimal` | `number` | `number` |
+| `date` | `date` | `datepicker` |
+| `datetime` | `datetime` | `datetimepicker` |
+| `bool` | `boolean` | `checkbox` |
+| `enum` | `badge` | `select` |
+| `guid` (FK) | `lookup` | `lookup` |
+| `text` (long) | `text` (truncated) | `textarea` |
+
+## Computed Attribute Rule
+
+If `entities.json` marks an attribute with `computed: true`:
+
+- **SmartForm detail/edit:** the field MUST have `readonly: true`
+- **SmartForm create:** the field MUST be ABSENT (not yet calculable)
+- **SmartTable:** the field can appear normally (read-only by nature)
+
+Example:
+```json
+{
+  "field": "totalCompensation",
+  "label": "Salaire Total",
+  "type": "number",
+  "readonly": true
+}
+```
+
+## Readonly Field Rule
+
+- `readonly` MUST be a boolean (`true` or `false`)
+- Do NOT use string values like `"onCreate"` or `"onEdit"`
+- For conditional readonly logic (e.g., readonly on create but editable on edit), use a business rule (BR-WF category) to express the condition
+- The form always shows `readonly: true` or omits the field entirely
+
+Valid:
+```json
+{ "field": "status", "readonly": false }
+```
+
+Invalid:
+```json
+{ "field": "status", "readonly": "onCreate" }
+```
+
+## SmartForm Section Location Rule
+
+- **SmartForm in `list` section:** inline create / quick-create drawer (user creates without leaving the list)
+- **SmartForm in `detail` section:** full edit page (user navigates to a dedicated form page)
+
+Both patterns are valid. Use `list` section for high-frequency data entry (e.g., time entries). Use `detail` section for complex entities with multiple tabs.
+
+## Lookup Field Rule
+
+Lookup fields require explicit entity references for downstream consumers to resolve the foreign key target.
+
+**SmartForm requirement:**
+> Every SmartForm field with `type: "lookup"` MUST include `"entity": "{TargetEntityName}"`
+
+Example:
+```json
+{
+  "field": "department",
+  "label": "Departement",
+  "type": "lookup",
+  "entity": "Department",
+  "required": true
+}
+```
+
+**SmartFilter requirement:**
+> Every SmartFilter filter with `type: "lookup"` MUST include `"entity": "{TargetEntityName}"`
+
+Example:
+```json
+{
+  "field": "departmentId",
+  "type": "lookup",
+  "label": "Departement",
+  "entity": "Department"
+}
+```
+
+## SmartKanban Auto-Detection Rule (OBLIGATOIRE)
+
+For each entity with an `enum` attribute named `status` having >= 3 options:
+
+- **ADD** a SmartKanban resource in a dedicated `kanban` section (or alongside SmartTable in `list`)
+- **MAP** each enum option to a Kanban column with appropriate color:
+  - `gray` = draft/pending
+  - `blue` = submitted/in progress
+  - `green` = approved/completed
+  - `red` = rejected/cancelled
+  - `orange` = warning/under review
+- **SET** `cardFields` to the 3-4 most relevant display attributes (typically: code, name/label, assignee, date)
+- **SKIP** for:
+  - Portal modules (read-only, no workflow)
+  - Config/lookup entities (static, no workflow)
+
+Example detection:
+```javascript
+const statusAttr = entity.attributes.find(
+  a => a.name === 'status' && a.type === 'enum'
+);
+
+if (statusAttr && (statusAttr.options || []).length >= 3 && !isPortalModule) {
+  // ADD SmartKanban resource
+}
+```
+
+This ensures workflow entities get a visual board view — the standard UX for approval/lifecycle processes.
+
+## SmartFilter Mandatory Rule
+
+Every `list` section with a SmartTable MUST also have a SmartFilter resource placed BEFORE the SmartTable.
+
+**Pattern:**
+```
+Section: list
+  Resource 1: SmartFilter (filters come first)
+  Resource 2: SmartTable (grid follows)
+```
+
+Do NOT embed `filters[]` inside SmartTable — use a dedicated SmartFilter resource instead.
+
+**Exceptions (SKIP SmartFilter for):**
+- Portal modules with a single read-only grid
+
+This ensures consistent filtering UX across all data lists.

package/templates/skills/business-analyse-design/references/smartcomponents-templates.md

@@ -0,0 +1,225 @@
+# SmartComponent JSON Templates Reference
+
+This document contains the canonical JSON schema examples for all SmartComponent types used in screens definition. These templates show the exact structure and required fields for each component.
+
+## SmartTable Template
+
+A data grid component for displaying and managing entity collections with sorting, filtering, and row-level actions.
+
+```json
+{
+  "code": "{entity-plural}-grid",
+  "type": "SmartTable",
+  "entity": "{EntityName}",
+  "label": "Grille des {entity-plural}",
+  "columns": [
+    { "field": "code", "label": "Code", "type": "text", "sortable": true, "width": "100px" },
+    { "field": "fullName", "label": "Nom", "type": "text", "sortable": true },
+    { "field": "department.name", "label": "Departement", "type": "lookup", "filterable": true },
+    { "field": "status", "label": "Statut", "type": "badge", "filterable": true, "options": ["Active", "Inactive"] }
+  ],
+  "actions": ["create", "edit", "delete", "export"],
+  "permission": "{AppCode}.{ModuleCode}.Read",
+  "rowActions": [
+    { "action": "edit", "permission": "{AppCode}.{ModuleCode}.Update" },
+    { "action": "view-detail", "permission": "{AppCode}.{ModuleCode}.Read" }
+  ],
+  "defaultSort": { "field": "code", "direction": "asc" },
+  "pageSize": 25
+}
+```
+
+## SmartForm Template
+
+A form component for creating and editing entity records with support for multiple tabs, field validation, and nested subtables.
+
+```json
+{
+  "code": "{entity}-form",
+  "type": "SmartForm",
+  "entity": "{EntityName}",
+  "label": "Fiche {entity}",
+  "tabs": [
+    {
+      "label": "Informations",
+      "fields": [
+        { "field": "firstName", "label": "Prenom", "type": "text", "required": true, "col": 6 },
+        { "field": "lastName", "label": "Nom", "type": "text", "required": true, "col": 6 },
+        { "field": "email", "label": "Email", "type": "email", "required": true, "validation": "unique" },
+        { "field": "department", "label": "Departement", "type": "lookup", "entity": "Department", "required": true },
+        { "field": "status", "label": "Statut", "type": "select", "options": ["Active", "Inactive"], "readonly": false }
+      ]
+    },
+    {
+      "label": "Contrats",
+      "type": "subtable",
+      "entity": "Contract",
+      "columns": ["contractType", "startDate", "endDate", "status"]
+    }
+  ],
+  "permission": "{AppCode}.{ModuleCode}.Update"
+}
+```
+
+## SmartDashboard Template
+
+A dashboard component for displaying key performance indicators (KPIs) and data visualizations via charts.
+
+```json
+{
+  "code": "{module}-dashboard",
+  "type": "SmartDashboard",
+  "entity": "{PrimaryEntityName}",
+  "label": "Tableau de bord {module}",
+  "kpis": [
+    { "label": "Total actifs", "value": "count(status=Active)", "icon": "users", "color": "primary" },
+    { "label": "En conge", "value": "count(status=OnLeave)", "icon": "calendar", "color": "warning" }
+  ],
+  "charts": [
+    { "type": "pie", "label": "Repartition par departement", "dataSource": "employees", "groupBy": "department" },
+    { "type": "bar", "label": "Evolution des effectifs", "dataSource": "employees", "groupBy": "hireDate.year" }
+  ],
+  "permission": "{AppCode}.{ModuleCode}.Read"
+}
+```
+
+## SmartKanban Template
+
+A board component for workflow-based entities with status columns and draggable cards.
+
+```json
+{
+  "code": "{entity}-kanban",
+  "type": "SmartKanban",
+  "entity": "{EntityName}",
+  "label": "Kanban {entity}",
+  "statusField": "status",
+  "columns": [
+    { "value": "Draft", "label": "Brouillon", "color": "gray" },
+    { "value": "Submitted", "label": "Soumis", "color": "blue" },
+    { "value": "Approved", "label": "Approuve", "color": "green" }
+  ],
+  "cardFields": ["code", "assignee", "dueDate"],
+  "permission": "{AppCode}.{ModuleCode}.Read"
+}
+```
+
+## SmartFilter Template
+
+A dedicated filter component placed before SmartTable in list sections. Do NOT embed filters inside SmartTable — use a separate SmartFilter resource instead.
+
+```json
+{
+  "code": "{entity-plural}-filters",
+  "type": "SmartFilter",
+  "entity": "{EntityName}",
+  "label": "Filtres {entity-plural}",
+  "filters": [
+    { "field": "status", "type": "select", "label": "Statut", "options": ["Active", "Inactive"] },
+    { "field": "departmentId", "type": "lookup", "label": "Departement", "entity": "Department" },
+    { "field": "startDate", "type": "daterange", "label": "Periode" },
+    { "field": "search", "type": "text", "label": "Recherche" }
+  ],
+  "permission": "{AppCode}.{ModuleCode}.Read"
+}
+```
+
+## SmartCard Template
+
+A card component for displaying entity summaries with avatar, title, subtitle, and action buttons.
+
+```json
+{
+  "code": "{entity}-card",
+  "type": "SmartCard",
+  "entity": "{EntityName}",
+  "label": "Carte {entity}",
+  "title": "fullName",
+  "subtitle": "position",
+  "fields": [
+    { "field": "email", "label": "Email", "icon": "mail" },
+    { "field": "department.name", "label": "Departement", "icon": "building" }
+  ],
+  "avatar": "profileImage",
+  "actions": ["view-detail", "edit"],
+  "permission": "{AppCode}.{ModuleCode}.Read"
+}
+```
+
+## Canonical Output Format (screens.json)
+
+The final screens.json file MUST use the sections[] wrapper format:
+
+```json
+{
+  "sections": [
+    {
+      "sectionCode": "list",
+      "sectionLabel": "Liste des employes",
+      "resources": [
+        {
+          "code": "employees-filters",
+          "type": "SmartFilter",
+          "entity": "Employee",
+          "label": "Filtres employes",
+          "filters": [
+            { "field": "departmentId", "type": "lookup", "label": "Departement", "entity": "Department" },
+            { "field": "status", "type": "select", "label": "Statut", "options": ["Active", "Inactive"] }
+          ],
+          "permission": "HumanResources.Employees.Read"
+        },
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "entity": "Employee",
+          "label": "Grille des employes",
+          "columns": [],
+          "actions": ["create", "export"],
+          "rowActions": [
+            { "action": "edit", "permission": "HumanResources.Employees.Update" },
+            { "action": "view-detail", "permission": "HumanResources.Employees.Read" }
+          ],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
+    },
+    {
+      "sectionCode": "detail",
+      "sectionLabel": "Fiche employe",
+      "resources": [
+        {
+          "code": "employee-form",
+          "type": "SmartForm",
+          "entity": "Employee",
+          "label": "Fiche employe",
+          "tabs": [],
+          "actions": ["save", "cancel"],
+          "permission": "HumanResources.Employees.Update"
+        }
+      ]
+    },
+    {
+      "sectionCode": "dashboard",
+      "sectionLabel": "Tableau de bord",
+      "resources": [
+        {
+          "code": "employees-dashboard",
+          "type": "SmartDashboard",
+          "entity": "Employee",
+          "label": "Tableau de bord RH",
+          "kpis": [],
+          "charts": [],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Key Naming Requirements
+
+- Use `sectionCode` (not `id` or `code`)
+- Use `sectionLabel` (not `displayName` or `label`)
+- Resource `type` must be one of: `SmartTable`, `SmartForm`, `SmartDashboard`, `SmartKanban`, `SmartCard`, `SmartFilter`
+- The flat `screens[]` format (one object per screen with componentType at top level) is **DEPRECATED** — use `sections[]` instead