@atlashub/smartstack-cli 1.4.1 → 1.5.0

package/templates/commands/mcp-integration.md

@@ -0,0 +1,330 @@
+---
+description: SmartStack MCP Integration Guide
+---
+
+# SmartStack MCP Integration
+
+This document describes how SmartStack CLI commands integrate with the **SmartStack MCP Server** for consistent, structured operations across all development environments.
+
+---
+
+## Overview
+
+The SmartStack MCP Server provides four main tools:
+
+| MCP Tool | CLI Commands Using It | Purpose |
+|----------|----------------------|---------|
+| `validate_conventions` | `/validate` | Check naming conventions |
+| `check_migrations` | `/efcore:conflicts`, `/efcore:scan`, `/efcore:db-status` | Migration analysis |
+| `scaffold_extension` | `/controller:create`, `/application:create` | Code generation |
+| `api_docs` | (future) `/docs:api` | API documentation |
+
+---
+
+## MCP Tools Reference
+
+### 1. validate_conventions
+
+**Description:** Validate SmartStack conventions for SQL schemas, table prefixes, migration naming, service interfaces, and namespace structure.
+
+**Parameters:**
+
+```typescript
+{
+  path?: string;           // Project path (default: auto-detect)
+  checks: Array<'tables' | 'migrations' | 'services' | 'namespaces' | 'all'>;
+}
+```
+
+**Response:**
+
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+  summary: string;
+}
+```
+
+**Used by:** `/validate`, `/validate:tables`, `/validate:migrations`, etc.
+
+---
+
+### 2. check_migrations
+
+**Description:** Analyze EF Core migrations for conflicts, ordering issues, and ModelSnapshot discrepancies between branches.
+
+**Parameters:**
+
+```typescript
+{
+  projectPath?: string;    // EF Core project path
+  branch?: string;         // Git branch to check (default: current)
+  compareBranch?: string;  // Branch to compare against
+}
+```
+
+**Response:**
+
+```typescript
+interface MigrationCheckResult {
+  hasConflicts: boolean;
+  migrations: MigrationInfo[];
+  conflicts: MigrationConflict[];
+  suggestions: string[];
+}
+
+interface MigrationInfo {
+  name: string;
+  context: string;      // core, extensions
+  version: string;      // 1.0.0, 1.2.0
+  sequence: string;     // 001, 002
+  description: string;
+  file: string;
+  applied: boolean;
+}
+
+interface MigrationConflict {
+  type: 'order' | 'snapshot' | 'dependency' | 'naming';
+  description: string;
+  files: string[];
+  resolution: string;
+}
+```
+
+**Used by:** `/efcore:conflicts`, `/efcore:scan`, `/efcore:db-status`
+
+---
+
+### 3. scaffold_extension
+
+**Description:** Generate code to extend SmartStack: services, entities, controllers, or React components.
+
+**Parameters:**
+
+```typescript
+{
+  type: 'service' | 'entity' | 'controller' | 'component';
+  name: string;          // e.g., "UserProfile", "Order"
+  options?: {
+    namespace?: string;
+    baseEntity?: string;
+    methods?: string[];
+    outputPath?: string;
+  }
+}
+```
+
+**Response:**
+
+```typescript
+interface ScaffoldResult {
+  success: boolean;
+  files: GeneratedFile[];
+  instructions: string[];
+}
+
+interface GeneratedFile {
+  path: string;
+  content: string;
+  type: 'created' | 'modified';
+}
+```
+
+**Used by:** `/controller:create`, `/application:create`
+
+---
+
+### 4. api_docs
+
+**Description:** Get API documentation from Swagger/OpenAPI or by parsing controller files.
+
+**Parameters:**
+
+```typescript
+{
+  endpoint?: string;     // Filter by path, e.g., "/api/users"
+  format?: 'markdown' | 'json' | 'openapi';
+  controller?: string;   // Filter by controller name
+}
+```
+
+**Used by:** Future `/docs:api` command
+
+---
+
+## Convention Alignment
+
+### Migration Naming
+
+Both CLI and MCP use the same format:
+
+```
+{context}_v{version}_{sequence}_{Description}
+```
+
+| Component | Values | Example |
+|-----------|--------|---------|
+| context | `core`, `extensions` | `core` |
+| version | Semver | `1.2.0` |
+| sequence | 3-digit | `001` |
+| Description | PascalCase | `AddUserRoles` |
+
+**Full example:** `core_v1.2.0_001_AddUserRoles`
+
+### Table Prefixes
+
+Valid prefixes enforced by `validate_conventions`:
+
+- `auth_` - Authentication
+- `nav_` - Navigation
+- `usr_` - User data
+- `ai_` - AI features
+- `cfg_` - Configuration
+- `wkf_` - Workflow
+- `support_` - Support
+- `entra_` - Entra ID
+- `ref_` - Reference data
+- `loc_` - Localization
+- `lic_` - Licensing
+
+### Service Pattern
+
+```
+Interface:      I{Name}Service
+Implementation: {Name}Service
+```
+
+### Namespaces
+
+```
+SmartStack.Domain.*
+SmartStack.Application.*
+SmartStack.Infrastructure.*
+SmartStack.Api.*
+```
+
+---
+
+## Command to MCP Mapping
+
+### /efcore:conflicts
+
+```
+1. Get current branch
+2. CALL mcp__smartstack__check_migrations({
+     branch: currentBranch,
+     compareBranch: "develop"
+   })
+3. Display conflicts from response
+4. Exit 1 if hasConflicts is true
+```
+
+### /efcore:scan
+
+```
+1. List all worktrees
+2. FOR each branch:
+   CALL mcp__smartstack__check_migrations({
+     branch: branchName,
+     compareBranch: "develop"
+   })
+3. Aggregate results
+4. Calculate merge order by risk level
+5. Display summary
+```
+
+### /validate
+
+```
+1. CALL mcp__smartstack__validate_conventions({
+     checks: ["all"]
+   })
+2. Display errors and warnings
+3. Exit 1 if not valid
+```
+
+### /controller:create
+
+```
+1. Parse arguments (area, module, entity)
+2. CALL mcp__smartstack__scaffold_extension({
+     type: "controller",
+     name: moduleName,
+     options: { namespace: "SmartStack.Api.Controllers.{area}" }
+   })
+3. Write generated files
+4. Add permissions
+5. Create migration if needed
+```
+
+---
+
+## Benefits of MCP Integration
+
+1. **Single Source of Truth**
+   - Convention rules defined once in MCP config
+   - No duplication between CLI and other tools
+
+2. **Consistency**
+   - Same logic in CLI, CI/CD, IDE
+   - Identical results everywhere
+
+3. **Structured Output**
+   - Typed responses instead of text parsing
+   - Easier automation and scripting
+
+4. **Maintainability**
+   - Update logic in one place (MCP)
+   - All commands automatically benefit
+
+5. **Extensibility**
+   - Add new checks/features in MCP
+   - Available to all consumers immediately
+
+---
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions example
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate conventions
+        run: |
+          OUTPUT=$(claude-code "/validate --json")
+          if [ "$(echo $OUTPUT | jq '.valid')" != "true" ]; then
+            echo "::error::Convention violations detected"
+            exit 1
+          fi
+
+      - name: Check migration conflicts
+        run: |
+          OUTPUT=$(claude-code "/efcore:conflicts --json")
+          if [ "$(echo $OUTPUT | jq '.hasConflicts')" = "true" ]; then
+            echo "::error::Migration conflicts detected"
+            exit 1
+          fi
+```
+
+---
+
+## Fallback Behavior
+
+When MCP is unavailable, commands fall back to:
+
+1. **Local bash scripts** for simple operations
+2. **Manual template generation** for scaffolding
+3. **Warning message** indicating degraded mode
+
+To check MCP availability:
+
+```bash
+# MCP health check
+claude-code --mcp-status smartstack
+```

package/templates/commands/notification.md

@@ -1,129 +1,129 @@
-# /notification - Integration Notifications SmartStack
-
-> **Synergie Skill/Commande:**
-> - **Skill** (`templates/skills/notification/`) → Invocation automatique par Claude
-> - **Commande** (`/notification`) → Invocation manuelle par l'utilisateur
-
----
-
-## ARGUMENTS
-
-```
-/notification <action> [options]
-```
-
-| Action | Description |
-|--------|-------------|
-| `add` | Ajouter une notification dans un service existant |
-| `type` | Creer un nouveau type de notification |
-| `hook` | Creer le hook frontend avec SignalR |
-
----
-
-## WORKFLOW
-
-### /notification add
-
-Ajoute l'envoi de notification dans un service existant.
-
-**Questions:**
-1. Quel service modifier ? (liste des services)
-2. Quelle methode ? (Create, Update, Delete, etc.)
-3. Qui notifier ? (createur, assigne, role, liste)
-4. Quel type de notification ? (existant ou nouveau)
-
-**Actions:**
-1. Injecter `INotificationService` si pas present
-2. Ajouter l'appel `SendNotificationAsync` dans la methode
-3. Logger l'envoi de notification
-
-### /notification type
-
-Cree un nouveau type de notification.
-
-**Questions:**
-1. Nom du type ? (ex: `ProductCreated`)
-2. Categorie ? (Support, Admin, System, SLA)
-3. Description ?
-
-**Actions:**
-1. Ajouter dans `NotificationType.cs`
-2. Creer migration EF Core
-
-### /notification hook
-
-Cree le hook frontend pour recevoir les notifications en temps reel.
-
-**Questions:**
-1. Quel module ?
-2. Quel type d'entite ?
-
-**Actions:**
-1. Creer `use{Module}Notifications.ts`
-2. Integrer `useSignalR`
-3. Configurer les callbacks
-
----
-
-## TEMPLATES
-
-### Template SendNotification
-
-```csharp
-await _notificationService.SendNotificationAsync(
-    userId: $USER_ID,
-    type: NotificationType.$TYPE,
-    title: "$TITLE",
-    message: $"$MESSAGE",
-    relatedEntityType: "$ENTITY_TYPE",
-    relatedEntityId: $ENTITY_ID,
-    actionUrl: $"/$MODULE/$ENTITY_ID",
-    cancellationToken: ct);
-
-_logger.LogInformation(
-    "Notification sent to {UserId}: {Type}",
-    $USER_ID, NotificationType.$TYPE);
-```
-
-### Template Hook
-
-```typescript
-// hooks/use{Module}Notifications.ts
-import { useSignalR } from '@/hooks/useSignalR';
-import { useQueryClient } from '@tanstack/react-query';
-import { toast } from 'sonner';
-
-export function use{Module}Notifications() {
-  const queryClient = useQueryClient();
-
-  useSignalR({
-    onNotification: (notification) => {
-      if (notification.relatedEntityType === '{Entity}') {
-        queryClient.invalidateQueries(['{module}']);
-        toast.info(notification.title, {
-          description: notification.message,
-          action: notification.actionUrl ? {
-            label: 'Voir',
-            onClick: () => window.location.href = notification.actionUrl,
-          } : undefined,
-        });
-      }
-    },
-  });
-}
-```
-
----
-
-## FICHIERS CLES
-
-| Fichier | Role |
-|---------|------|
-| `Domain/Support/Enums/NotificationType.cs` | Types de notification |
-| `Application/Common/Interfaces/INotificationService.cs` | Interface |
-| `Infrastructure/Services/Support/NotificationService.cs` | Implementation |
-| `web/src/hooks/useSignalR.ts` | Hook SignalR |
-
----
-
-User: $ARGUMENTS
+# /notification - Integration Notifications SmartStack
+
+> **Synergie Skill/Commande:**
+> - **Skill** (`templates/skills/notification/`) → Invocation automatique par Claude
+> - **Commande** (`/notification`) → Invocation manuelle par l'utilisateur
+
+---
+
+## ARGUMENTS
+
+```
+/notification <action> [options]
+```
+
+| Action | Description |
+|--------|-------------|
+| `add` | Ajouter une notification dans un service existant |
+| `type` | Creer un nouveau type de notification |
+| `hook` | Creer le hook frontend avec SignalR |
+
+---
+
+## WORKFLOW
+
+### /notification add
+
+Ajoute l'envoi de notification dans un service existant.
+
+**Questions:**
+1. Quel service modifier ? (liste des services)
+2. Quelle methode ? (Create, Update, Delete, etc.)
+3. Qui notifier ? (createur, assigne, role, liste)
+4. Quel type de notification ? (existant ou nouveau)
+
+**Actions:**
+1. Injecter `INotificationService` si pas present
+2. Ajouter l'appel `SendNotificationAsync` dans la methode
+3. Logger l'envoi de notification
+
+### /notification type
+
+Cree un nouveau type de notification.
+
+**Questions:**
+1. Nom du type ? (ex: `ProductCreated`)
+2. Categorie ? (Support, Admin, System, SLA)
+3. Description ?
+
+**Actions:**
+1. Ajouter dans `NotificationType.cs`
+2. Creer migration EF Core
+
+### /notification hook
+
+Cree le hook frontend pour recevoir les notifications en temps reel.
+
+**Questions:**
+1. Quel module ?
+2. Quel type d'entite ?
+
+**Actions:**
+1. Creer `use{Module}Notifications.ts`
+2. Integrer `useSignalR`
+3. Configurer les callbacks
+
+---
+
+## TEMPLATES
+
+### Template SendNotification
+
+```csharp
+await _notificationService.SendNotificationAsync(
+    userId: $USER_ID,
+    type: NotificationType.$TYPE,
+    title: "$TITLE",
+    message: $"$MESSAGE",
+    relatedEntityType: "$ENTITY_TYPE",
+    relatedEntityId: $ENTITY_ID,
+    actionUrl: $"/$MODULE/$ENTITY_ID",
+    cancellationToken: ct);
+
+_logger.LogInformation(
+    "Notification sent to {UserId}: {Type}",
+    $USER_ID, NotificationType.$TYPE);
+```
+
+### Template Hook
+
+```typescript
+// hooks/use{Module}Notifications.ts
+import { useSignalR } from '@/hooks/useSignalR';
+import { useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+export function use{Module}Notifications() {
+  const queryClient = useQueryClient();
+
+  useSignalR({
+    onNotification: (notification) => {
+      if (notification.relatedEntityType === '{Entity}') {
+        queryClient.invalidateQueries(['{module}']);
+        toast.info(notification.title, {
+          description: notification.message,
+          action: notification.actionUrl ? {
+            label: 'Voir',
+            onClick: () => window.location.href = notification.actionUrl,
+          } : undefined,
+        });
+      }
+    },
+  });
+}
+```
+
+---
+
+## FICHIERS CLES
+
+| Fichier | Role |
+|---------|------|
+| `Domain/Support/Enums/NotificationType.cs` | Types de notification |
+| `Application/Common/Interfaces/INotificationService.cs` | Interface |
+| `Infrastructure/Services/Support/NotificationService.cs` | Implementation |
+| `web/src/hooks/useSignalR.ts` | Hook SignalR |
+
+---
+
+User: $ARGUMENTS