@atlashub/smartstack-cli 1.4.0 → 1.5.0

package/templates/commands/controller/create.md

@@ -1,216 +1,216 @@
-# /controller:create - Génération Controller API 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 Support Sla SlaDefinition
-```
-
----
-
-## 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: 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 7: 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` |
-
----
-
-## MAPPING AREA → ROUTE
-
-| Area | Route Prefix | Permission Context |
-|------|--------------|-------------------|
-| `Admin` | `api/admin/` | `platform.administration.` |
-| `Support` | `api/support/` | `platform.support.` |
-| `Business` | `api/business/` | `business.` |
-| `User` | `api/user/` | `personal.myspace.` |
-| `Auth` | `api/auth/` | (AllowAnonymous pour login) |
-
----
-
-## 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)
-
----
-
-## 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);
-```
+# /controller:create - Génération Controller API 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 Support Sla SlaDefinition
+```
+
+---
+
+## 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: 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 7: 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` |
+
+---
+
+## MAPPING AREA → ROUTE
+
+| Area | Route Prefix | Permission Context |
+|------|--------------|-------------------|
+| `Admin` | `api/admin/` | `platform.administration.` |
+| `Support` | `api/support/` | `platform.support.` |
+| `Business` | `api/business/` | `business.` |
+| `User` | `api/user/` | `personal.myspace.` |
+| `Auth` | `api/auth/` | (AllowAnonymous pour login) |
+
+---
+
+## 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)
+
+---
+
+## 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);
+```

package/templates/commands/controller.md

@@ -5,6 +5,65 @@
 > - **Commande** (`/controller:create`) → Invocation manuelle par l'utilisateur
 > - Templates partagés dans `.claude/skills/controller/templates.md`
 
+> **MCP INTEGRATION:** This command can use `mcp__smartstack__scaffold_extension` for code generation.
+
+---
+
+## MCP SCAFFOLDING (Recommended)
+
+> **NEW:** Use SmartStack MCP for consistent code generation across all projects.
+
+### When to Use MCP
+
+| Scenario | Use MCP | Use Templates |
+|----------|---------|---------------|
+| Standard CRUD controller | Yes | - |
+| Controller with custom logic | - | Yes |
+| Need validation before | Yes | - |
+| Offline mode | - | Yes |
+
+### MCP Invocation
+
+**Claude instruction:** For standard controller generation, invoke MCP first:
+
+```json
+{
+  "tool": "mcp__smartstack__scaffold_extension",
+  "parameters": {
+    "type": "controller",
+    "name": "{MODULE}",
+    "options": {
+      "namespace": "SmartStack.Api.Controllers.{AREA}",
+      "methods": ["GetAll", "GetById", "Create", "Update", "Delete"]
+    }
+  }
+}
+```
+
+The MCP returns a `ScaffoldResult`:
+
+```typescript
+interface ScaffoldResult {
+  success: boolean;
+  files: GeneratedFile[];
+  instructions: string[];
+}
+
+interface GeneratedFile {
+  path: string;
+  content: string;
+  type: 'created' | 'modified';
+}
+```
+
+### Post-MCP Steps
+
+After MCP generates the controller:
+1. Review generated code
+2. Add to `Permissions.cs` (STEP 6 below)
+3. Add to `PermissionConfiguration.cs`
+4. Create migration if needed
+
 ---
 
 ## ARGUMENTS

package/templates/commands/create/agent.md

@@ -0,0 +1,138 @@
+---
+description: Create a SmartStack agent extension project
+argument-hint: <name> [description]
+---
+
+# Create Agent Extension
+
+Scaffold a complete SmartStack **agent** extension project.
+
+## What is an Agent?
+
+An agent is a specialized execution unit:
+- Launched by commands for parallel execution
+- Focused on specific tasks (search, analysis, etc.)
+- Defined in markdown with YAML frontmatter
+- Optimized with model selection (haiku/sonnet/opus)
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+- **name** (required): Agent name in kebab-case
+- **description** (optional): What the agent does
+
+## Project Structure
+
+```
+smartstack-{name}/
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── README.md
+├── .gitignore
+├── src/
+│   └── index.ts
+└── templates/
+    └── agents/
+        └── {name}.md          # Agent template
+```
+
+## Generated Agent Template
+
+Create `templates/agents/{name}.md`:
+
+```markdown
+---
+name: {name}
+description: {description}
+color: yellow
+model: haiku
+---
+
+# {PascalCaseName} Agent
+
+{description}
+
+## Purpose
+
+This agent specializes in:
+- [Primary capability 1]
+- [Primary capability 2]
+- [Primary capability 3]
+
+## Search Strategy
+
+### 1. Initial Discovery
+- Use `Glob` to find files matching patterns
+- Focus on: `**/*.{relevant-extensions}`
+
+### 2. Deep Analysis
+- Use `Grep` for specific code patterns
+- Look for: `pattern1`, `pattern2`
+
+### 3. Context Building
+- Use `Read` to examine key files
+- Extract: imports, exports, dependencies
+
+### 4. Synthesis
+- Compile findings
+- Identify patterns
+- Generate recommendations
+
+## Output Format
+
+**CRITICAL**: Output findings directly in response. NEVER create files.
+
+### Findings Report
+
+#### Relevant Files
+| File | Purpose | Key Patterns |
+|------|---------|--------------|
+| path/to/file | description | patterns found |
+
+#### Analysis
+[Detailed analysis of findings]
+
+#### Recommendations
+1. [First recommendation]
+2. [Second recommendation]
+3. [Third recommendation]
+
+## Tool Usage
+
+Preferred tools for this agent:
+- `Glob` - File discovery
+- `Grep` - Pattern search
+- `Read` - File content
+
+## Anti-Patterns
+
+- **NEVER** create markdown files
+- **NEVER** guess without evidence
+- **NEVER** skip verification
+- **ALWAYS** cite specific file paths
+
+## Priority
+
+Accuracy > Completeness > Speed
+```
+
+## Model Selection Guide
+
+| Use Case | Model | Reason |
+|----------|-------|--------|
+| Simple search | haiku | Fast, cheap |
+| Analysis | sonnet | Good balance |
+| Complex reasoning | opus | Best quality |
+
+## Workflow
+
+1. Parse name and description from `$ARGUMENTS`
+2. Validate name is kebab-case
+3. Create project directory
+4. Generate all files using Write tool
+5. Display success message
+
+---
+
+User: $ARGUMENTS