@atlashub/smartstack-cli 1.5.0 → 1.5.2

package/templates/commands/mcp-integration.md

@@ -1,330 +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
-```
+---
+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
+```