@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -1,221 +0,0 @@
-# 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

@@ -1,138 +0,0 @@
-# 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

@@ -1,225 +0,0 @@
-# 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