@atlashub/smartstack-cli 1.1.0

package/templates/commands/controller.md

@@ -0,0 +1,278 @@
+# /controller - Skill Controller SmartStack
+
+> **Synergie Skill/Commande:**
+> - **Skill** (`.claude/skills/controller/`) → Invocation automatique par Claude
+> - **Commande** (`/controller:create`) → Invocation manuelle par l'utilisateur
+> - Templates partagés dans `.claude/skills/controller/templates.md`
+
+---
+
+## ARGUMENTS
+
+```
+/controller:create <area> <module> [entity]
+```
+
+| Variable | Extraction | Valeurs |
+|----------|------------|---------|
+| `$AREA` | Premier mot | `Admin`, `Support`, `Business`, `User`, `Auth` |
+| `$MODULE` | Deuxième mot | Nom du module (PascalCase) |
+| `$ENTITY` | Troisième mot (optionnel) | Nom de l'entité Domain (défaut = singulier de $MODULE) |
+
+**Exemples:**
+```
+/controller:create Admin Users
+/controller:create Support Tickets Ticket
+/controller:create Business Leads Lead
+```
+
+---
+
+## VALIDATION CONTEXTES (CRITIQUE)
+
+> **RAPPEL:** Les controllers client doivent être dans l'Area `Business`.
+
+### Mapping Area → Context
+
+| Area | Route Prefix | Permission Context | Autorisé Client |
+|------|--------------|-------------------|-----------------|
+| `Admin` | `api/admin/` | `platform.administration.*` | ❌ NON |
+| `Support` | `api/support/` | `platform.support.*` | ❌ NON |
+| `Business` | `api/business/` | `business.*` | ✅ OUI |
+| `User` | `api/user/` | `personal.myspace.*` | ❌ NON |
+| `Auth` | `api/auth/` | (AllowAnonymous) | ❌ NON |
+
+### Validation Automatique
+
+```
+AVANT génération:
+
+SI $AREA NOT IN ["Admin", "Support", "Business", "User", "Auth"]:
+    ❌ ERREUR: "Area '$AREA' non reconnue"
+    SUGGÉRER: "Utilisez 'Business' pour les modules client"
+    ABORT
+
+SI création par client ET $AREA IN ["Admin", "Support", "User", "Auth"]:
+    ⚠️ WARNING: "L'area '$AREA' est réservée au core SmartStack"
+    SUGGÉRER: "Utilisez '/controller:create Business $MODULE $ENTITY'"
+```
+
+---
+
+## RÈGLES ABSOLUES
+
+1. **TOUJOURS** utiliser `[RequirePermission(Permissions.*)]` - jamais de strings
+2. **TOUJOURS** ajouter `[ProducesResponseType]` pour chaque status possible
+3. **TOUJOURS** logger les opérations (Info pour CRUD, Warning pour Delete/Sensitive)
+4. **TOUJOURS** protéger les comptes système (UserType.System/LocalAdmin)
+5. **JAMAIS** de SQL direct - utiliser EF Core
+6. **JAMAIS** d'endpoint sans permission (sauf [AllowAnonymous] pour auth)
+
+---
+
+## WORKFLOW
+
+### ÉTAPE 1: PARSING DES ARGUMENTS
+
+```
+EXTRAIRE $AREA = premier mot des arguments (PascalCase)
+EXTRAIRE $MODULE = deuxième mot des arguments (PascalCase)
+EXTRAIRE $ENTITY = troisième mot OU singulier de $MODULE
+
+SI $AREA absent → AskUserQuestion (options: Admin, Support, Business, User, Auth)
+SI $MODULE absent → AskUserQuestion (texte libre)
+```
+
+### ÉTAPE 2: ANALYSE EXISTANTE
+
+| Action | Commande |
+|--------|----------|
+| Entity Domain | `Glob "Domain/**/{Entity}.cs"` |
+| Permissions existantes | `Read Permissions.cs` |
+| DbContext DbSet | `Grep "{Entity}s" ApplicationDbContext.cs` |
+| Controller existant | `Glob "Controllers/{Area}/{Module}Controller.cs"` |
+
+### ÉTAPE 3: CONFIRMATION UTILISATEUR
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "Type",
+      question: "Quel type de controller ?",
+      options: [
+        { label: "CRUD Complet (Recommended)", description: "GET list, GET by ID, POST, PUT, PATCH, DELETE" },
+        { label: "Read-Only", description: "GET list, GET by ID uniquement" },
+        { label: "Custom", description: "Actions spécifiques à définir" }
+      ]
+    },
+    {
+      header: "Postman",
+      question: "Générer les tests Postman ?",
+      options: [
+        { label: "Oui (Recommended)", description: "Ajoute tests dans SmartStack.Security.postman_collection.json" },
+        { label: "Non", description: "Controller uniquement" }
+      ]
+    }
+  ]
+})
+```
+
+### ÉTAPE 4: VALIDATION SÉCURITÉ
+
+**Vérifications obligatoires avant génération:**
+
+1. ✅ Permission path existe ou sera créée
+2. ✅ Format permission: `context.application.module.action`
+3. ✅ DbSet existe dans ApplicationDbContext
+4. ✅ Entity a les méthodes Create/Update nécessaires
+
+### ÉTAPE 5: GÉNÉRATION
+
+| Fichier | Chemin | Action |
+|---------|--------|--------|
+| Controller | `src/SmartStack.Api/Controllers/{Area}/{Module}Controller.cs` | CREATE |
+| Permissions | `src/SmartStack.Application/Common/Authorization/Permissions.cs` | UPDATE |
+| Tests Postman | `tests/SmartStack.Security.postman_collection.json` | UPDATE (si choisi) |
+
+**Utiliser templates de** → `.claude/skills/controller/templates.md`
+
+### ÉTAPE 6: SYNCHRONISATION BASE DE DONNÉES (OBLIGATOIRE)
+
+> **CRITIQUE:** Un controller avec `[RequirePermission]` retournera **403 Forbidden** pour TOUS les utilisateurs si la permission n'existe pas dans la base de données.
+
+#### Workflow obligatoire
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                     WORKFLOW SYNCHRONISATION PERMISSIONS                     │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  1. GÉNÉRER CONTROLLER                                                       │
+│     └─→ [RequirePermission(Permissions.{Module}.View)]                       │
+│                                                                              │
+│  2. AJOUTER À Permissions.cs (Application layer)                             │
+│     └─→ public static class {Module} { ... }                                 │
+│                                                                              │
+│  3. AJOUTER À PermissionConfiguration.cs (Infrastructure layer)              │
+│     └─→ HasData(new { Path = "...", ModuleId = ..., ... })                   │
+│                                                                              │
+│  4. CRÉER MIGRATION EF CORE                                                  │
+│     └─→ /efcore:migration Add{Module}Permissions                             │
+│                                                                              │
+│  5. VALIDER COHÉRENCE                                                        │
+│     └─→ Vérifier que TOUS les paths dans Permissions.cs                      │
+│         existent dans PermissionConfiguration.cs                             │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+### ÉTAPE 7: LOGS CRITIQUES - VÉRIFICATION
+
+Après génération, **VÉRIFIER** que le controller contient :
+
+| Événement | Niveau Requis | Présent ? |
+|-----------|---------------|-----------|
+| Login échoué (si auth) | `LogCritical` | ☐ |
+| Compte verrouillé (si auth) | `LogCritical` | ☐ |
+| Password change | `LogWarning` | ☐ |
+| Création | `LogInformation` | ☐ |
+| Modification | `LogInformation` | ☐ |
+| Suppression | `LogWarning` | ☐ |
+| Désactivation | `LogWarning` | ☐ |
+
+### ÉTAPE 8: RÉSUMÉ FINAL
+
+Afficher:
+- ✅ Fichiers créés (chemins cliquables)
+- 🔐 Permissions ajoutées
+- 🧪 Tests Postman générés (si applicable)
+- 📝 Prochaines étapes:
+  - Vérifier les DTOs
+  - Ajouter validation métier si nécessaire
+  - Tester avec Swagger/Postman
+
+---
+
+## SOURCES DE DONNÉES
+
+| Donnée | Source |
+|--------|--------|
+| Entity Domain | `src/SmartStack.Domain/**/{Entity}.cs` |
+| DbContext | `src/SmartStack.Application/Common/Interfaces/IApplicationDbContext.cs` |
+| Permissions | `src/SmartStack.Application/Common/Authorization/Permissions.cs` |
+| Controllers existants | `src/SmartStack.Api/Controllers/**/*.cs` |
+| Tests Postman | `tests/SmartStack.Security.postman_collection.json` |
+
+---
+
+## RÈGLES SÉCURITÉ - LOGS CRITIQUES (OBLIGATOIRE)
+
+| Événement | Niveau | Pattern |
+|-----------|--------|---------|
+| Login échoué | `Critical` | `LogCritical("Login attempt on locked account...")` |
+| Permission refusée | `Critical` | Auto via `SecurityAuditMiddleware` |
+| Compte verrouillé | `Critical` | `LogCritical("Account locked...")` |
+| Password change | `Warning` | `LogWarning("Password changed...")` |
+| Création/MAJ | `Information` | `LogInformation("User {User} creating...")` |
+| Suppression | `Warning` | `LogWarning("User {User} deleting...")` |
+
+---
+
+## CONTRAINTES TECHNIQUES
+
+### Injection de Dépendances (Obligatoire)
+
+```csharp
+public {Module}Controller(
+    IApplicationDbContext context,     // TOUJOURS
+    ICurrentUserService currentUser,   // TOUJOURS
+    ILogger<{Module}Controller> logger // TOUJOURS
+    // + services spécifiques au module
+)
+```
+
+### ProducesResponseType (Obligatoire)
+
+```csharp
+[ProducesResponseType(typeof(PagedResult<T>), StatusCodes.Status200OK)]
+[ProducesResponseType(StatusCodes.Status401Unauthorized)]  // Si [Authorize]
+[ProducesResponseType(StatusCodes.Status403Forbidden)]     // Si [RequirePermission]
+[ProducesResponseType(StatusCodes.Status404NotFound)]      // Si GET/PUT/DELETE by ID
+```
+
+### Logging Pattern (Obligatoire)
+
+```csharp
+// Information - opérations standard
+_logger.LogInformation("User {User} created {Entity} {Id}",
+    _currentUser.Email, entity.Id);
+
+// Warning - opérations sensibles
+_logger.LogWarning("User {User} deleted {Entity} {Id} ({Name})",
+    _currentUser.Email, id, entity.Name);
+
+// Critical - sécurité (automatique via middleware pour 401/403)
+_logger.LogCritical("SECURITY: Login attempt on locked account - {Email} from {IP}",
+    email, ipAddress);
+```
+
+---
+
+## TEMPLATES
+
+→ **Voir `.claude/skills/controller/templates.md`**
+
+Templates disponibles:
+- CRUD Controller (standard)
+- Auth Controller (login/logout/change-password)
+- Controller avec Relations (nested resources)
+- Patterns réutilisables (pagination, error responses)
+
+→ **Voir `.claude/skills/controller/postman-templates.md`**
+
+Templates tests:
+- GET list (200, 403, 401)
+- POST create (201, 403)
+- DELETE (403)
+- Auth (login success/fail, invalid token)

package/templates/commands/debug.md

@@ -0,0 +1,95 @@
+---
+description: Systematic bug debugging with deep analysis and resolution
+argument-hint: <log|error|problem-description>
+allowed-tools: Bash, Read, Edit, MultiEdit, Write, Grep, Glob, Task, WebSearch, WebFetch
+---
+
+You are a systematic debugging specialist. Follow this ultra-deep analysis workflow to identify, understand, and resolve bugs.
+
+**You need to always ULTRA THINK.**
+
+## Workflow
+
+1. **ANALYZE**: Deep log/error analysis
+   - Parse the provided log/error message carefully
+   - Extract key error patterns, stack traces, and symptoms
+   - Identify error types: runtime, compile-time, logic, performance
+   - **CRITICAL**: Document exact error context and reproduction steps
+
+2. **EXPLORE**: Targeted codebase investigation
+   - Launch **parallel subagents** to search for error-related code (`explore-codebase`, `explore-docs`, `websearch`)
+   - Search for similar error patterns in codebase using Grep
+   - Find all files related to the failing component/module
+   - Examine recent changes that might have introduced the bug
+   - **ULTRA THINK**: Connect error symptoms to potential root causes
+
+3. **ULTRA-THINK**: Deep root cause analysis
+   - **THINK DEEPLY** about the error chain: symptoms → immediate cause → root cause
+   - Consider all possible causes:
+     - Code logic errors
+     - Configuration issues
+     - Environment problems
+     - Race conditions
+     - Memory issues
+     - Network problems
+   - **CRITICAL**: Map the complete failure path from root cause to visible symptom
+   - Validate hypotheses against the evidence
+
+4. **RESEARCH**: Solution investigation
+   - Launch **parallel subagents** for web research (`websearch`)
+   - Search for similar issues and solutions online
+   - Check documentation for affected libraries/frameworks
+   - Look for known bugs, workarounds, and best practices
+   - **THINK**: Evaluate solution approaches for this specific context
+
+5. **IMPLEMENT**: Systematic resolution
+   - Choose the most appropriate solution based on analysis
+   - Follow existing codebase patterns and conventions
+   - Implement minimal, targeted fixes
+   - **STAY IN SCOPE**: Fix only what's needed for this specific bug
+   - Add defensive programming where appropriate
+
+6. **VERIFY**: Comprehensive testing
+   - Test the specific scenario that was failing
+   - Run related tests to ensure no regressions
+   - Check edge cases around the fix
+   - **CRITICAL**: Verify the original error is completely resolved
+
+## Deep Analysis Techniques
+
+### Log Analysis
+
+- Extract timestamps, error codes, stack traces
+- Identify error propagation patterns
+- Look for correlation with system events
+
+### Code Investigation
+
+- Trace execution path to error location
+- Check variable states and data flow
+- Examine error handling patterns
+- Review recent commits affecting the area
+
+### Root Cause Mapping
+
+- **WHY technique**: Ask "why" 5 times minimum
+- Consider environmental factors
+- Check for timing/concurrency issues
+- Validate assumptions about data/state
+
+## Execution Rules
+
+- **ULTRA THINK** at each phase transition
+- Use parallel agents for comprehensive investigation
+- Document findings and reasoning at each step
+- **NEVER guess** - validate all hypotheses with evidence
+- **MINIMAL CHANGES**: Fix root cause, not symptoms
+- Test thoroughly before declaring resolution complete
+
+## Priority
+
+Understanding > Speed > Completeness. Every bug must be fully understood before attempting fixes.
+
+---
+
+User: $ARGUMENTS

package/templates/commands/documentation/module.md

@@ -0,0 +1,202 @@
+# /documentation:module - Génération Documentation SmartStack
+
+> **Synergie Skill/Commande:**
+> - **Skill** (`.claude/skills/documentation/`) → Invocation automatique par Claude
+> - **Commande** (`/documentation:module`) → Invocation manuelle par l'utilisateur
+> - Templates partagés dans `.claude/skills/documentation/templates.md`
+
+---
+
+## ARGUMENTS
+
+```
+/documentation:module <type> <target>
+```
+
+| Variable | Extraction | Valeurs |
+|----------|------------|---------|
+| `$TYPE` | Premier mot | `user` \| `developer` \| `database` \| `testing` |
+| `$TARGET` | Reste de la ligne | Nom du module, outil, ou schéma |
+
+---
+
+## RÈGLES ABSOLUES
+
+1. **JAMAIS** de texte en dur → `useTranslation('docs')`
+2. **JAMAIS** d'ASCII art → composants React/HTML pour MCD
+3. **TOUJOURS** lire les sources existantes avant de générer
+4. **TOUJOURS** demander confirmation avant de créer les fichiers
+5. **TOUJOURS** mettre à jour App.tsx et les index parents
+
+---
+
+## WORKFLOW
+
+### ÉTAPE 1: PARSING DES ARGUMENTS
+
+```
+EXTRAIRE $TYPE = premier mot des arguments
+EXTRAIRE $TARGET = reste des arguments
+
+SI $TYPE absent OU non reconnu → AskUserQuestion
+SI $TARGET absent → AskUserQuestion
+```
+
+### ÉTAPE 2: ANALYSE (selon $TYPE)
+
+#### SI $TYPE == "user"
+
+| Action | Commande |
+|--------|----------|
+| Trouver le module | `Grep "code.*$TARGET" src/.../Navigation/` |
+| Composants React | `Glob "web/.../pages/**/*$TARGET*"` |
+| Permissions | `Grep "$TARGET" src/.../Permissions.cs` |
+| Endpoints API | `Grep "$TARGET" src/.../Controllers/` |
+
+#### SI $TYPE == "database"
+
+| Action | Commande |
+|--------|----------|
+| Tables du schéma | `Read ApplicationDbContextModelSnapshot.cs` |
+| Configurations | `Glob "Persistence/Configurations/$TARGET/*.cs"` |
+| Entités Domain | `Glob "Domain/Entities/$TARGET/*.cs"` |
+
+#### SI $TYPE == "developer" ou "testing"
+
+| Action | Commande |
+|--------|----------|
+| Doc existante | `Glob "pages/docs/developer/**/*$TARGET*"` |
+| Fichiers config | `Glob "**/$TARGET*.{json,yaml}"` |
+| Doc officielle | `WebSearch` |
+
+### ÉTAPE 3: CONFIRMATION UTILISATEUR
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Détail",
+    question: "Quel niveau de détail pour '$TARGET' ?",
+    options: [
+      { label: "Complet (Recommended)", description: "Toutes sections" },
+      { label: "Standard", description: "Sections principales" },
+      { label: "Minimal", description: "Référence rapide" }
+    ]
+  }]
+})
+```
+
+### ÉTAPE 4: GÉNÉRATION
+
+| $TYPE | Fichier | Chemin |
+|-------|---------|--------|
+| `user` | `{Module}DocPage.tsx` | `pages/docs/user/{context}/` |
+| `developer` | `{Tool}Page.tsx` | `pages/docs/developer/tools/` |
+| `database` | `{Schema}SchemaPage.tsx` | `pages/docs/developer/database/` |
+| `testing` | `{Tool}TestingPage.tsx` | `pages/docs/developer/testing/` |
+
+**Fichiers à créer/modifier:**
+1. Page React (utiliser template de `templates.md`)
+2. Traductions EN → `i18n/locales/en/docs.json`
+3. Traductions FR → `i18n/locales/fr/docs.json`
+4. Route → `App.tsx`
+5. Index parent → lien de navigation
+6. **UserIndexPage.tsx** → Ajouter le module à la hiérarchie (SI $TYPE == "user")
+
+### ÉTAPE 4bis: INTÉGRATION UserIndexPage (SI $TYPE == "user")
+
+**OBLIGATOIRE** pour les modules utilisateur: Vérifier et mettre à jour `UserIndexPage.tsx`
+
+```typescript
+// Fichier: web/smartstack-web/src/pages/docs/user/UserIndexPage.tsx
+
+// 1. Ajouter l'icône si nécessaire
+import { ..., {IconName} } from 'lucide-react';
+
+// 2. Trouver l'application parente dans la hiérarchie
+//    - Platform > Administration: pour les modules admin
+//    - Platform > Support: pour les modules support
+//    - Personal > MySpace: pour les modules personnels
+
+// 3. Ajouter le module dans le tableau `modules` de l'application:
+{
+  name: t('user.modules.{module}.name'),
+  icon: {IconName},
+  href: '/docs/user/{slug}',
+  description: t('user.modules.{module}.description')
+},
+
+// 4. Ajouter les traductions dans docs.json (fr + en):
+"modules": {
+  "{module}": {
+    "name": "Nom du module",
+    "description": "Description courte"
+  }
+}
+```
+
+**Vérification:**
+- Le module doit apparaître dans la page `/docs/user` sous son application parente
+- Le lien doit pointer vers `/docs/user/{slug}`
+
+### ÉTAPE 5: INTÉGRATION
+
+```typescript
+// App.tsx
+import { {Name}DocPage } from '@/pages/docs/{path}/{Name}DocPage';
+<Route path="{slug}" element={<{Name}DocPage />} />
+```
+
+### ÉTAPE 6: RÉSUMÉ FINAL
+
+Afficher:
+- ✅ Fichiers créés (chemins cliquables)
+- 🔗 URL: `/docs/{path}/{slug}`
+- 📝 Prochaines étapes
+
+---
+
+## TEMPLATES
+
+→ **Voir `.claude/skills/documentation/templates.md`**
+
+Templates disponibles:
+- User Module (maquettes UI, FAQ, API)
+- Database Schema (MCD HTML, tables détaillées)
+- Developer Tool (installation, config, CI/CD)
+- Patterns réutilisables (CodeBlock, Stats, Badges)
+
+---
+
+## SOURCES DE DONNÉES
+
+| Donnée | Source |
+|--------|--------|
+| Tables DB | `ApplicationDbContextModelSnapshot.cs` |
+| Configurations | `Persistence/Configurations/{schema}/*.cs` |
+| Permissions | `Domain/Authorization/Permissions.cs` |
+| Routes | `App.tsx` |
+| Traductions | `i18n/locales/*/docs.json` |
+| Doc outils | WebSearch |
+
+---
+
+## STRUCTURE i18n
+
+```json
+{
+  "breadcrumb": { "documentation": "...", "user": "...", "developer": "..." },
+  "common": { "tableOfContents": "...", "externalResources": "..." },
+  "user": { "{module}": { "title": "...", "sections": {...} } },
+  "developer": { "tools": {...}, "database": {...} }
+}
+```
+
+---
+
+## CONTRAINTES
+
+- Variables CSS: `var(--text-primary)`, `var(--bg-secondary)`, `var(--color-primary-600)`
+- Responsive: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`
+- Icônes: `lucide-react` uniquement
+- Liens externes: avec `<ExternalLink />` icon
+- MCD: composants React/HTML (JAMAIS ASCII)