@atlashub/smartstack-cli 4.75.0 → 4.79.0

package/templates/skills/migrate/references/v3.34-to-v3.46.md

@@ -0,0 +1,289 @@
+# Migration rules: v3.34 → v3.46
+
+> Used by `/migrate --from=3.34 --to=3.46`.
+> Covers the breaking changes shipped during the v3.46 alignment work
+> (ApplicationZone removal, layout consolidation, NavigationApplication.Create
+> signature change, Tailwind tokenisation, mergeRoutes deprecation, AI patterns).
+
+## Rule list (machine-readable)
+
+```yaml
+rules:
+  # ──────────────────────────────────────────────────────────────────
+  # BACKEND — Domain / Seed / API
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-BE-001
+    category: backend
+    description: "ApplicationZone enum and Zone column removed (replaced by IsPersonal + IsOpen flags on NavigationApplication)."
+    detect_pattern: 'ApplicationZone\.\w+|Zone\s*=\s*ApplicationZone\.\w+|public\s+ApplicationZone\s+Zone'
+    glob: "src/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: false
+    references:
+      - templates/skills/apex/references/core-seed-data.md
+      - templates/skills/application/references/provider-template.md
+      - templates/skills/apex/references/checks/seed-checks.sh   # check C66 enforces this
+
+  - id: R-BE-002
+    category: backend
+    description: "NavigationApplication.Create() signature lost the first 'zone' parameter; gained isOpen + isPersonal at the end (both default false)."
+    detect_pattern: 'NavigationApplication\.Create\(\s*ApplicationZone\.\w+'
+    glob: "src/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: true   # contextual — review each call site
+    references:
+      - D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Navigation/NavigationApplication.cs
+
+  - id: R-BE-003
+    category: backend
+    description: "ApplicationMenuDto.Zone (string) field removed; consume IsPersonal + IsOpen instead."
+    detect_pattern: '\.Zone\b|"Zone"'
+    glob: "src/SmartStack.Application/Navigation/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: true
+
+  - id: R-BE-004
+    category: backend
+    description: "Migration to drop the 'Zone' column and add IsPersonal/IsOpen columns. Generate via dotnet ef if missing."
+    detect_pattern: 'Zone'
+    glob: "src/SmartStack.Infrastructure/Persistence/Migrations/*.cs"
+    severity: WARNING
+    requires_confirmation: true
+    note: "If the project's last migration is older than core_v3.46.0, prompt user to run /efcore:migration RemoveApplicationZone."
+
+  - id: R-BE-005
+    category: backend
+    description: "Domain Hooks moved to SmartStack.Application.Common.Interfaces.Hooks namespace (previously: scattered)."
+    detect_pattern: 'SmartStack\.(?:Domain|Application)\.(?!Common\.Interfaces\.Hooks)\w+\.(?:IBeforeCreate|IAfterCreate|IBeforeUpdate|IAfterUpdate|IBeforeDelete|IAfterDelete)'
+    glob: "src/**/*.cs"
+    severity: WARNING
+    requires_confirmation: false
+    references:
+      - templates/skills/apex/references/smartstack-api.md   # Entity Lifecycle Hooks section
+
+  - id: R-BE-006
+    category: backend
+    description: "BaseEntity gained an ExtensionData (string JSON) property + 7 typed methods. EF configuration must include builder.Property(x => x.ExtensionData).HasColumnType(\"nvarchar(max)\").HasDefaultValue(\"{}\")."
+    detect_pattern: 'class\s+\w+Configuration\s*:\s*IEntityTypeConfiguration<\w+>'
+    glob: "src/SmartStack.Infrastructure/Persistence/Configurations/**/*.cs"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Inspect each EF config file; only add the ExtensionData mapping where the entity inherits BaseEntity AND the table is meant to store extension data."
+
+  # ──────────────────────────────────────────────────────────────────
+  # FRONTEND — Layouts / Routing / Theme
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-FE-001
+    category: frontend
+    description: "Legacy domain-specific layouts (AdminLayout / BusinessLayout / UserLayout / HRLayout / SalesLayout) consolidated into AppLayout (sole authenticated shell)."
+    detect_pattern: '<\s*(AdminLayout|BusinessLayout|UserLayout|HRLayout|SalesLayout)\b|from\s+["\x27][^"\x27]*\/(AdminLayout|BusinessLayout|UserLayout|HRLayout|SalesLayout)["\x27]'
+    glob: "web/**/*.tsx"
+    severity: BLOCKING
+    requires_confirmation: false
+    references:
+      - templates/skills/application/references/frontend-route-naming.md
+      - templates/skills/apex/references/checks/seed-checks.sh   # check C67
+
+  - id: R-FE-002
+    category: frontend
+    description: "Hardcoded Tailwind colors must be replaced by CSS variables. Mapping table in themes-db-driven.md (24 rows: bg-blue-* → var(--info-bg), text-gray-900 → var(--text-primary), etc.)."
+    detect_pattern: '(bg|text|border)-(?!\[)(red|blue|green|gray|amber|yellow|orange|purple|indigo|violet|cyan|pink|emerald|rose|sky|teal|lime|fuchsia|stone|slate|zinc|neutral)-\d'
+    glob: "web/**/*.tsx"
+    severity: WARNING   # was BLOCKING in iteration 2 — but for a migration we relax to WARNING and let the user batch-fix
+    requires_confirmation: true
+    references:
+      - templates/skills/application/references/themes-db-driven.md   # Section 5: Migration map
+      - templates/skills/apex/references/checks/frontend-checks.sh    # check C9
+
+  - id: R-FE-003
+    category: frontend
+    description: "Tailwind dark: prefix removed. SmartStack toggles a .dark class on root; CSS vars adapt automatically."
+    detect_pattern: '\bdark:(bg|text|border)-'
+    glob: "web/**/*.tsx"
+    severity: WARNING
+    requires_confirmation: false
+
+  - id: R-FE-004
+    category: frontend
+    description: "mergeRoutes() and getStaticAppRoutes() removed in v3.7+. Pages must register via PageRegistry.register() in componentRegistry.generated.ts."
+    detect_pattern: 'mergeRoutes\s*\(|getStaticAppRoutes\s*\('
+    glob: "web/**/*.{ts,tsx}"
+    severity: BLOCKING
+    requires_confirmation: true
+    references:
+      - templates/skills/audit-route/references/routing-pattern.md
+      - templates/skills/application/references/smartstack-provider.md
+
+  - id: R-FE-005
+    category: frontend
+    description: "RouteGuard.tsx replaced by ProtectedRoute.tsx (API-driven permissions)."
+    detect_pattern: 'RouteGuard|from\s+["\x27][^"\x27]*\/RouteGuard["\x27]'
+    glob: "web/**/*.{ts,tsx}"
+    severity: BLOCKING
+    requires_confirmation: false
+
+  - id: R-FE-006
+    category: frontend
+    description: "useParams must use generic { id: string } (not custom names like { ticketId, userId }). Custom names go in the destructuration."
+    detect_pattern: 'useParams<\{\s*(?!id\s*:)\w+Id\s*:'
+    glob: "web/**/*.tsx"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Refactor: const { id: ticketId } = useParams<{ id: string }>(). Param URL must be 'id' for DynamicRouter."
+
+  - id: R-FE-007
+    category: frontend
+    description: "Client App.tsx must wrap with <SmartStackProvider config={...}> (replaces ad-hoc provider stacks)."
+    detect_pattern: 'AuthProvider|TenantProvider|ThemeProvider'   # if present in App.tsx without SmartStackProvider above
+    glob: "web/**/{App,main}.tsx"
+    severity: WARNING
+    requires_confirmation: true
+    references:
+      - templates/skills/application/references/smartstack-provider.md
+
+  # ──────────────────────────────────────────────────────────────────
+  # SEED — Navigation & Roles
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-SEED-001
+    category: seed
+    description: "NavigationApplicationSeedEntry must include IsPersonal + IsOpen (both bool, default false). Replaces the Zone field."
+    detect_pattern: 'NavigationApplicationSeedEntry'
+    glob: "src/**/*NavigationApplicationSeedData.cs"
+    severity: BLOCKING
+    requires_confirmation: false
+
+  - id: R-SEED-002
+    category: seed
+    description: "MySpace and Personal-scope apps should set IsPersonal = true."
+    detect_pattern: 'NavigationApplicationSeedEntry'
+    glob: "src/**/*MySpace*SeedData.cs"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Manual judgement: only set IsPersonal=true on apps that genuinely belong to user space."
+
+  # ──────────────────────────────────────────────────────────────────
+  # CONFIG — appsettings / package.json
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-CFG-001
+    category: config
+    description: "@atlashub/smartstack peer must be at least 3.46.0."
+    detect_pattern: '"@atlashub/smartstack":\s*"\^?[0-2]\.|^"@atlashub/smartstack":\s*"\^?3\.[0-3][0-9]\.|^"@atlashub/smartstack":\s*"\^?3\.4[0-5]\.'
+    glob: "web/smartstack-web/package.json"
+    severity: BLOCKING
+    requires_confirmation: false
+    note: "Bump @atlashub/smartstack to ^3.46.0 (or latest)."
+
+  - id: R-CFG-002
+    category: config
+    description: "Tailwind v4 + @tailwindcss/vite required. Old @tailwindcss/postcss configuration deprecated."
+    detect_pattern: '"@tailwindcss/postcss"'
+    glob: "web/smartstack-web/package.json"
+    severity: WARNING
+    requires_confirmation: false
+    note: "Install @tailwindcss/vite, remove @tailwindcss/postcss, update vite.config.ts plugins list."
+
+  - id: R-CFG-003
+    category: config
+    description: "appsettings.json should include the new sections : SlaMonitoring, SolutionAutoClose, AutoAssignment, WorkflowExecution (added in v3.45/v3.46)."
+    detect_pattern: '^\s*"(?:Logging|Email)\s*"'
+    glob: "src/SmartStack.Api/appsettings.json"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Compare against templates/project/appsettings.json.template ; add missing sections (defaults are safe)."
+```
+
+## Implementation recipes
+
+The rules above are declarative ; some need a step-by-step recipe when a single regex isn't enough. The skill's `--apply` mode falls back to these recipes for any rule with `requires_confirmation: true`.
+
+### R-BE-001 — `ApplicationZone` removal
+
+For each file matched :
+
+1. Remove every line that matches `^\s*Zone\s*=\s*ApplicationZone\.\w+,?\s*$`
+2. After the line `Id = ApplicationId,` (or the first property of the SeedEntry), insert :
+   ```
+   IsPersonal = false,
+   IsOpen = false,
+   ```
+3. Replace `public ApplicationZone Zone { get; init; }` (DTO) by :
+   ```csharp
+   public bool IsPersonal { get; init; }
+   public bool IsOpen { get; init; }
+   ```
+4. Remove `using` directives for `SmartStack.Domain.Navigation` if `ApplicationZone` was the only reason they were imported.
+
+### R-BE-002 — `NavigationApplication.Create()` signature
+
+For each call site :
+
+- Old signature : `NavigationApplication.Create(ApplicationZone.X, code, label, description, icon, iconType, route, displayOrder)`
+- New signature : `NavigationApplication.Create(code, label, description, icon, iconType, route, displayOrder, isOpen: bool, isPersonal: bool)`
+
+**Recipe** :
+1. Remove the first argument (`ApplicationZone.X`).
+2. Append two named arguments at the end : `isOpen: false, isPersonal: false` (or `true` based on context — see R-SEED-002).
+3. **Manual review** : if the original call passed `Personal` zone, propose `isPersonal: true`. If `Admin` zone (system app), propose `isOpen: true`.
+
+### R-FE-001 — Layout consolidation
+
+For each `.tsx` file containing `<AdminLayout>`, `<BusinessLayout>`, `<UserLayout>`, `<HRLayout>`, or `<SalesLayout>` :
+
+1. Replace the JSX tag (open + close) by `<AppLayout>` / `</AppLayout>`.
+2. Update the import : `import { AppLayout } from '@/layouts/AppLayout'`.
+3. Remove the old import line.
+
+If the file was `src/layouts/AdminLayout.tsx` (or similar), DELETE the file — it no longer has a purpose.
+
+### R-FE-002 — Tailwind tokenisation
+
+This rule is **bulk** but **noisy**. Apply only if the user accepts (default WARNING in migration ; was BLOCKING in iteration 2).
+
+Use the migration map in `templates/skills/application/references/themes-db-driven.md` Section 5. For each `(bg|text|border)-{color}-{shade}` occurrence, propose the canonical CSS-var replacement based on context :
+- Status badges (success/warning/error/info) → `var(--{status}-bg)` / `var(--{status}-text)` / `var(--{status}-border)`
+- Action buttons → `var(--color-accent-600)` / `hover:bg-[var(--color-accent-700)]`
+- Body text → `var(--text-primary)` / `var(--text-secondary)`
+- Card backgrounds → `var(--bg-card)`
+- Borders → `var(--border-color)`
+
+When the context is ambiguous (e.g. random `bg-blue-100`), prompt for the intent (info badge ? accent ? branding ?) and apply accordingly.
+
+### R-FE-004 — `mergeRoutes` / `getStaticAppRoutes` removal
+
+These calls usually live in `src/main.tsx` or `src/App.tsx`. Recipe :
+
+1. Open the file.
+2. Find the call to `mergeRoutes(...)` or `getStaticAppRoutes(...)`.
+3. For each route registered :
+   - Convert to `PageRegistry.register('module.section', lazy(() => import(...)))`
+   - Place those calls in `src/extensions/componentRegistry.generated.ts` (create the file if missing).
+4. Remove the original `mergeRoutes` call ; remove its imports.
+5. Ensure `main.tsx` imports `./extensions/componentRegistry.generated` early (before render).
+
+This is a refactor — the skill SHOULD prompt the user to confirm and provide a diff preview.
+
+### R-CFG-002 — Tailwind v4 migration
+
+```bash
+# Inside web/smartstack-web/
+npm uninstall @tailwindcss/postcss
+npm install --save-dev @tailwindcss/vite
+
+# Edit vite.config.ts:
+#  + import tailwindcss from '@tailwindcss/vite';
+#  + plugins: [react(), tailwindcss()],
+
+# Edit index.css to use the new @theme {} syntax (see themes-db-driven.md Section 3.3)
+```
+
+The skill prompts and applies one step at a time, since these touch different files.
+
+## Notes
+
+- This rule file is the single source of truth for `v3.34 → v3.46`. Add new rules here as breaking changes are discovered.
+- For future migrations (e.g. `v3.46 → v3.47`), create `references/v3.46-to-v3.47.md` and register it in the SKILL.md mapping table.
+- Always run with `--dry-run` first. Always commit before `--apply`.

package/templates/skills/sketch/SKILL.md

@@ -1,172 +1,34 @@
 ---
 name: sketch
 description: |
-  Transform a vague idea into a precise /apex command in under 5 minutes.
-  Use this skill when:
-  - User has a vague idea ("I want an HR app with employees and absences")
-  - User doesn't know the exact entities, fields, or structure needed
-  - User needs help designing a module before running /apex
-  Zero MCP, zero file generation — pure domain inference.
-model: opus
-argument-hint: "<vague idea in natural language>"
+  DEPRECATED — Redirects to /business-analyse-quick.
+  Use /business-analyse-quick instead for Mini-BA with PRD generation.
+model: sonnet
+argument-hint: "<use /business-analyse-quick instead>"
 ---
 
 <objective>
-Transform a vague user prompt into a precise, ready-to-run /apex command. /sketch is a rapid design assistant — it infers entities, properties, relationships, labels, and code patterns from minimal input using domain heuristics and LLM knowledge.
-
-**Key principles:**
-- MAX 2 questions total (1 subject guard + 1 optional confirmation)
-- Zero MCP calls — pure inference (validation is /apex's job)
-- Zero file generation — output is text in conversation only
-- Domain heuristics ACCELERATE inference, they do NOT limit it
+This skill has been renamed to `/business-analyse-quick`. Redirect the user.
 </objective>
 
-<quick_start>
-
-```bash
-/sketch une app RH avec employés et absences
-/sketch I want to manage customer orders and invoices
-/sketch gestion de projets avec tâches et jalons
-/sketch stock management
-```
-
-</quick_start>
-
-<anti_patterns>
-- DO NOT ask more than 2 questions total
-- DO NOT generate any files (no JSON, no code, no documents)
-- DO NOT call any MCP tools (validation is /apex's job)
-- DO NOT scan the entire codebase (max 1 Glob for app detection)
-- DO NOT duplicate business analysis logic (no stakeholders, risks, use cases)
-- DO NOT output structured syntax — /apex parses natural language, not custom formats
-- DO NOT call Skill("apex") directly — instruct the agent to do it based on user choice
-</anti_patterns>
-
 <algorithm>
 
-## 1. SUBJECT GUARD
-
-Check if the user prompt contains at least one identifiable business object (noun that could be an entity: employees, orders, projects, invoices, etc.).
-
-```
-IF no business object identifiable in prompt:
-  → AskUserQuestion: "What do you want to manage? (e.g., employees, orders, projects, invoices...)"
-  → Wait for answer, then continue to step 2
-  → This is the ONLY mandatory question
-```
-
-## 2. LOAD DOMAIN HEURISTICS
-
-Read `references/domain-heuristics.md` — domain pattern table with entities, properties, FK relationships, and i18n labels for 15 common business domains.
-
-## 3. ULTRA THINK — Domain Inference
-
-**ULTRA THINK deeply about the user's domain before proceeding.**
-
-From the user prompt + domain heuristics table:
-
-1. **Extract keywords** from user prompt (nouns, domain terms, action verbs)
-2. **Match against heuristics table** — find the closest domain pattern(s)
-3. **If no match:** use general LLM knowledge (the table accelerates, it does NOT limit)
-4. **Infer entities:** name, key properties, types, nullable flags
-5. **Infer FK relationships:** between entities (EmployeeId→Employee, etc.)
-6. **Infer sections:** 1 section per main entity, code = plural kebab-case (e.g., "employees")
-7. **Infer i18n labels** in 4 languages (fr, en, it, de) — from table or LLM knowledge
-8. **Deduce code_patterns:** strategy = "sequential" by default, prefix = first 3 letters of entity name
-9. **Deduce tenantMode:** "strict" by default (multi-tenant)
-10. **Deduce complexity:**
-    - `simple-crud` if ≤ 2 entities with no workflow/status transitions
-    - `crud-rules` otherwise (validations, computed fields, status)
-    - `crud-workflow` if mentions approval, email, notification
-    - `complex` if > 4 entities with specific business logic
-
-## 4. DETECT EXISTING APPLICATION
-
+Display:
 ```
-Glob("**/NavigationApplicationSeedData.cs")  ← single scan, MAX 1
+═══════════════════════════════════════════════════════════
+  /sketch has been renamed to /business-analyse-quick
+═══════════════════════════════════════════════════════════
 
-IF files found:
-  → Extract application names from seed data classes
-  → Check if the inferred module fits an existing application
-  → If multiple apps match: flag as ambiguity for step 5
-
-IF no files found:
-  → New application — infer name from domain
-  → app_name = domain-appropriate PascalCase name (e.g., "HumanResources")
+  /business-analyse-quick provides:
+  - Interactive Mini-BA (12-15 questions)
+  - Structured Mini-PRD output for /apex -d
+  - Entity, rules, use cases, permissions, screens specs
 ```
 
-## 5. CONFIRMATION GATE — MAX 1 optional question
+Then immediately invoke the new skill with the user's original arguments:
 
 ```
-IF real ambiguity exists (multiple matching apps, genuinely ambiguous domain):
-  → AskUserQuestion with specific options to resolve the ambiguity
-  → This is the ONLY optional question
-
-IF no ambiguity:
-  → Zero questions — proceed directly to output
+Skill("business-analyse-quick", args: "{original user arguments}")
 ```
 
-## 6. OUTPUT — Display result and choices
-
-Display the design summary and generated /apex prompt using the exact format below.
-
 </algorithm>
-
-<output_format>
-
-```
-══════════════════════════════════════════════════════════
-  /sketch — Module Design Complete
-══════════════════════════════════════════════════════════
-
-  Application:  {app_name}
-  Module:       {module_code}
-  Sections:     {section1_code} ({fr_label}/{en_label}/{it_label}/{de_label})
-                {section2_code} ({fr_label}/{en_label}/{it_label}/{de_label})
-  Entities:     {Entity1} ({prop1}:{type}, {prop2}:{type}, {fk}:{type} FK→{Target})
-                {Entity2} ({prop1}:{type}, {prop2}:{type}, {fk}:{type} FK→{Target})
-  Complexity:   {complexity}
-  Code:         {Entity1} → {prefix}-{tenant}-00001 | {Entity2} → {prefix}-{tenant}-00001
-
-  Ready to run:
-  ──────────────────────────────────────────────────────
-  /apex add {sections} sections to {app_name} module with
-  {Entity1} entity ({properties with types and FKs}) and
-  {Entity2} entity ({properties with types and FKs}),
-  code patterns sequential {prefixes}, complexity {complexity}
-  ──────────────────────────────────────────────────────
-
-  [1] Run this /apex command now
-  [2] Edit before running
-  [3] Cancel
-```
-
-**Rules for the generated /apex prompt:**
-- Natural language, dense but readable
-- Include ALL entities with their key properties and types
-- Include FK relationships explicitly (e.g., "EmployeeId:Guid FK→Employee")
-- Include code pattern prefixes
-- Include complexity level
-- Mention the target application name
-
-</output_format>
-
-<handoff>
-
-Based on user selection:
-
-```
-IF user selects [1]:
-  → Call: Skill("apex", args: "{the generated prompt text}")
-
-IF user selects [2]:
-  → Display the generated prompt for the user to edit
-  → Wait for edited version
-  → Re-display choices [1] Run / [3] Cancel
-
-IF user selects [3]:
-  → Display: "Cancelled. Run /sketch again when ready."
-  → STOP
-```
-
-</handoff>