@atlashub/smartstack-cli 1.14.3 → 1.17.0

package/templates/skills/mcp/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: mcp
+description: |
+  MCP server management and health check for SmartStack.
+  Use this skill when:
+  - User wants to check MCP status
+  - User mentions "mcp", "healthcheck", "mcp status"
+  - Before any MCP-dependent operation fails
+  - After MCP configuration changes
+  Subcommands: healthcheck, tools
+---
+
+# Skill MCP SmartStack
+
+Manages MCP server connectivity and health verification.
+
+## SUBCOMMANDS
+
+| Command | Description |
+|---------|-------------|
+| `/mcp:healthcheck` | Full MCP health check with version verification |
+| `/mcp:tools` | List all available MCP tools with descriptions |
+
+---
+
+## /mcp:healthcheck
+
+Performs a complete MCP health check and updates the cache.
+
+### Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MCP HEALTH CHECK                         │
+├─────────────────────────────────────────────────────────────┤
+│  1. Test MCP Connectivity                                   │
+│     └─▶ Call mcp__smartstack__validate_conventions          │
+│                                                             │
+│  2. Get MCP Version                                         │
+│     └─▶ Read SmartStack.mcp/package.json                    │
+│                                                             │
+│  3. List Available Tools                                    │
+│     └─▶ Enumerate mcp__smartstack__* tools                  │
+│                                                             │
+│  4. Update Cache                                            │
+│     └─▶ Write .claude/mcp-status.json                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Step 1: Test Connectivity
+
+Call MCP with minimal parameters:
+
+```
+mcp__smartstack__validate_conventions({
+  checks: ["tables"]
+})
+```
+
+**Expected:** Response without connection error
+
+**On failure:**
+```
+❌ MCP CONNECTION FAILED
+   Error: <error_message>
+
+   Actions:
+   1. Verify MCP is configured in Claude Code settings
+   2. Check SmartStack.mcp path: D:\01 - projets\SmartStack.mcp
+   3. Restart Claude Code
+```
+
+### Step 2: Get Version
+
+```bash
+# Read MCP version
+cat "D:\01 - projets\SmartStack.mcp\package.json" | grep '"version"'
+```
+
+### Step 3: List Tools
+
+Verify these critical tools are available:
+
+| Tool | Purpose |
+|------|---------|
+| `validate_conventions` | Convention validation |
+| `scaffold_extension` | Code generation |
+| `suggest_migration` | Migration naming |
+| `check_migrations` | Conflict detection |
+| `generate_permissions` | RBAC generation |
+
+### Step 4: Update Cache
+
+Write to `.claude/mcp-status.json`:
+
+```json
+{
+  "lastCheck": "<ISO_DATE>",
+  "mcpVersion": "<VERSION>",
+  "mcpPath": "D:\\01 - projets\\SmartStack.mcp",
+  "status": "ok",
+  "toolsAvailable": [
+    "validate_conventions",
+    "scaffold_extension",
+    "suggest_migration",
+    "check_migrations",
+    "generate_permissions"
+  ]
+}
+```
+
+### Output Format
+
+**Success:**
+```
+MCP HEALTH CHECK ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Status      : OK
+  Version     : 1.5.0
+  Path        : D:\01 - projets\SmartStack.mcp
+  Tools       : 12 available
+  Cache       : Updated (.claude/mcp-status.json)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Next check  : in 7 days (auto)
+```
+
+**Warning (update available):**
+```
+MCP HEALTH CHECK ⚠️
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Status      : UPDATE AVAILABLE
+  Current     : 1.4.0
+  Latest      : 1.5.0
+  Action      : cd SmartStack.mcp && git pull
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Error:**
+```
+MCP HEALTH CHECK ❌
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Status      : ERROR
+  Issue       : MCP server not responding
+
+  Troubleshooting:
+  1. Check Claude Code MCP configuration
+  2. Verify path: D:\01 - projets\SmartStack.mcp
+  3. Run: cd SmartStack.mcp && npm install
+  4. Restart Claude Code
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Cache File
+
+**Location:** `.claude/mcp-status.json`
+
+**Structure:**
+```json
+{
+  "lastCheck": "2024-01-15T10:30:00.000Z",
+  "mcpVersion": "1.5.0",
+  "mcpPath": "D:\\01 - projets\\SmartStack.mcp",
+  "status": "ok" | "error",
+  "toolsAvailable": ["tool1", "tool2", ...],
+  "errors": ["error1", ...] // only if status = error
+}
+```
+
+**Validity:** 7 days
+
+---
+
+## Integration with Hook
+
+The `mcp-check` hook automatically:
+1. Reads this cache before any `mcp__smartstack__*` call
+2. Displays warning if cache > 7 days
+3. Blocks if last status was "error"
+
+This skill provides the **full check** that the hook references.
+
+---
+
+## /mcp:tools
+
+Lists all available MCP tools with their descriptions.
+
+### Core Tools (6)
+| Tool | Description |
+|------|-------------|
+| `validate_conventions` | Validate SmartStack conventions (tables, migrations, services, namespaces, controllers) |
+| `check_migrations` | Analyze EF Core migrations for conflicts and ordering issues |
+| `scaffold_extension` | Generate code: feature, entity, service, controller, component, dto, validator, repository |
+| `api_docs` | Get API documentation from Swagger/OpenAPI or controller files |
+| `suggest_migration` | Suggest migration name following SmartStack conventions |
+| `generate_permissions` | Generate RBAC permissions (HasData for PermissionConfiguration.cs) |
+
+### Test Tools (4)
+| Tool | Description |
+|------|-------------|
+| `scaffold_tests` | Generate test files for entities, services, controllers |
+| `analyze_test_coverage` | Analyze test coverage and identify missing tests |
+| `validate_test_conventions` | Validate test naming and structure conventions |
+| `suggest_test_scenarios` | Suggest test scenarios based on code analysis |
+
+### Frontend Tools (5)
+| Tool | Description |
+|------|-------------|
+| `scaffold_routes` | Generate frontend routes from backend NavRoute attributes |
+| `validate_frontend_routes` | Validate frontend routes match backend NavRoutes |
+| `scaffold_api_client` | Generate TypeScript API client with React Query hooks |
+| `scaffold_frontend_extension` | Generate frontend extension infrastructure (types, slots, contexts) |
+| `analyze_extension_points` | Analyze React components for extension points |
+
+### Output Format
+
+```
+MCP TOOLS REFERENCE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CORE TOOLS (6)
+  validate_conventions    Validate SmartStack conventions
+  check_migrations        Analyze EF Core migrations
+  scaffold_extension      Generate code (entity, service, etc.)
+  api_docs                Get API documentation
+  suggest_migration       Suggest migration name
+  generate_permissions    Generate RBAC permissions
+
+TEST TOOLS (4)
+  scaffold_tests          Generate test files
+  analyze_test_coverage   Analyze test coverage
+  validate_test_conventions  Validate test conventions
+  suggest_test_scenarios  Suggest test scenarios
+
+FRONTEND TOOLS (5)
+  scaffold_routes         Generate frontend routes
+  validate_frontend_routes  Validate route alignment
+  scaffold_api_client     Generate TypeScript API client
+  scaffold_frontend_extension  Generate extension infrastructure
+  analyze_extension_points  Analyze React extension points
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total: 15 tools available
+```

package/templates/skills/review-code/SKILL.md

@@ -7,8 +7,83 @@ description: This skill should be used when the user asks to "review code", "rev
 Provide expert-level code review guidance that focuses on high-impact issues: security vulnerabilities, logic errors, maintainability problems, and architectural concerns. Skip nitpicks and style issues that should be automated.
 
 Based on research from Google, Microsoft, OWASP, and academic studies on code review effectiveness.
+
+**For SmartStack projects**: Automatically validates SmartStack-specific conventions via MCP.
 </objective>
 
+<smartstack_integration>
+## SmartStack Project Detection & MCP Validation
+
+**CRITICAL**: Before starting any code review, detect if this is a SmartStack project and run MCP validation.
+
+<detection>
+**Detect SmartStack project by checking for ANY of these:**
+- `.claude/mcp-status.json` exists
+- `SmartStack.Domain/` or `SmartStack.Application/` directories
+- `*.sln` file containing "SmartStack"
+- `package.json` with `@smartstack/` dependencies
+</detection>
+
+<mcp_validation>
+**If SmartStack detected, run MCP validation FIRST:**
+
+1. **Validate conventions** (BLOCKING issues):
+   ```
+   mcp__smartstack__validate_conventions
+   checks: ["all"]
+   ```
+
+2. **Validate security** (when available):
+   ```
+   mcp__smartstack__validate_security
+   checks: ["all"]
+   ```
+
+3. **Analyze code quality** (when available):
+   ```
+   mcp__smartstack__analyze_code_quality
+   metrics: ["all"]
+   ```
+
+4. **Validate test conventions**:
+   ```
+   mcp__smartstack__validate_test_conventions
+   checks: ["all"]
+   ```
+</mcp_validation>
+
+<mcp_checks>
+**SmartStack-specific checks via MCP:**
+
+| Category | MCP Tool | What it validates |
+|----------|----------|-------------------|
+| **Tables** | `validate_conventions` | Préfixes (auth_, nav_, cfg_), schemas (core/extensions) |
+| **Migrations** | `validate_conventions` | Nommage `{context}_v{version}_{sequence}_{Description}` |
+| **Services** | `validate_conventions` | Interfaces I*Service |
+| **Entities** | `validate_conventions` | ITenantEntity, factory methods, private constructors |
+| **Controllers** | `validate_conventions` | [NavRoute] attributes, route format |
+| **Multi-tenant** | `validate_conventions` | TenantId isolation, no cross-tenant access |
+| **Tests** | `validate_test_conventions` | Naming, structure, patterns AAA |
+</mcp_checks>
+
+<output_integration>
+**Merge MCP results into review output:**
+
+```markdown
+## SmartStack Conventions (via MCP)
+
+| Severity | Issue | Location | Fix |
+|----------|-------|----------|-----|
+| BLOCKING | {MCP error} | `file:line` | {MCP suggestion} |
+| WARNING | {MCP warning} | `file:line` | {MCP suggestion} |
+```
+
+**Priority mapping:**
+- MCP errors → `[BLOCKING]`
+- MCP warnings → `[SUGGESTION]`
+</output_integration>
+</smartstack_integration>
+
 <quick_start>
 <review_priority>
 **Priority order**: Security > Correctness > Maintainability > Performance
@@ -207,6 +282,7 @@ A good code review:
 - Avoids nitpicks on style/formatting
 - Completes in reasonable time (<4 hours for small PRs)
 - **[React/Next.js]** Includes Vercel best practices review when applicable
+- **[SmartStack]** Runs MCP validation and integrates results into review output
 </success_criteria>
 
 <reference_guides>
@@ -216,4 +292,5 @@ For detailed guidance and patterns:
 - **`references/clean-code-principles.md`** - SOLID principles, naming conventions, function design, code smell detection
 - **`references/feedback-patterns.md`** - Valuable vs wasteful feedback patterns, communication strategies, priority labeling
 - **`references/code-quality-metrics.md`** - Complexity calculations, maintainability index, measurement techniques
+- **`references/smartstack-conventions.md`** - SmartStack-specific conventions, MCP integration, multi-tenant patterns
 </reference_guides>

package/templates/skills/review-code/references/smartstack-conventions.md

@@ -0,0 +1,302 @@
+<overview>
+SmartStack-specific conventions and patterns. This reference is used when reviewing SmartStack projects to ensure compliance with the architecture and security standards.
+
+**IMPORTANT**: All convention validation MUST be delegated to the MCP SmartStack tools. This file documents what to look for; the MCP validates automatically.
+</overview>
+
+<mcp_tools>
+## MCP SmartStack Tools for Code Review
+
+| Tool | Purpose | When to use |
+|------|---------|-------------|
+| `mcp__smartstack__validate_conventions` | Validate all SmartStack conventions | Always run first |
+| `mcp__smartstack__validate_test_conventions` | Validate test patterns | When tests are in scope |
+| `mcp__smartstack__validate_security` | Security-specific checks | Security-focused reviews |
+| `mcp__smartstack__analyze_code_quality` | Code metrics analysis | Quality-focused reviews |
+| `mcp__smartstack__check_migrations` | EF Core migration conflicts | When migrations are modified |
+</mcp_tools>
+
+<architecture>
+## SmartStack Architecture (Clean Architecture)
+
+```
+SmartStack/
+├── SmartStack.Domain/           # Entities, Value Objects, Domain Events
+├── SmartStack.Application/      # Services, DTOs, Commands/Queries
+├── SmartStack.Infrastructure/   # EF Core, External services
+├── SmartStack.Api/              # Controllers, Middleware
+└── SmartStack.Web/              # React frontend
+```
+
+**Dependency rule**: Dependencies point inward only (Api → Application → Domain).
+</architecture>
+
+<entities>
+## Entity Conventions
+
+<tenant_aware>
+**Tenant-aware entities** (most business entities):
+```csharp
+public class Order : BaseEntity, ITenantEntity
+{
+    public Guid TenantId { get; private set; }
+
+    private Order() { } // EF Core constructor
+
+    public static Order Create(Guid tenantId, ...)
+    {
+        return new Order { TenantId = tenantId, ... };
+    }
+}
+```
+
+**Requirements:**
+- [ ] Implements `ITenantEntity`
+- [ ] Has `TenantId` property
+- [ ] Private parameterless constructor
+- [ ] Static `Create()` factory method with `tenantId` as first parameter
+</tenant_aware>
+
+<system_entity>
+**System entities** (platform-level, no tenant):
+```csharp
+public class Permission : SystemEntity
+{
+    private Permission() { }
+
+    public static Permission Create(...)
+    {
+        return new Permission { ... };
+    }
+}
+```
+
+**Requirements:**
+- [ ] Inherits from `SystemEntity`
+- [ ] NO `TenantId` property
+- [ ] Private parameterless constructor
+- [ ] Static `Create()` factory method
+</system_entity>
+</entities>
+
+<tables>
+## Table Naming Conventions
+
+**Schema**: All tables MUST specify schema explicitly.
+```csharp
+builder.ToTable("auth_users", SchemaConstants.Core);
+```
+
+**Prefixes by domain:**
+| Prefix | Domain | Examples |
+|--------|--------|----------|
+| `auth_` | Authentication | auth_users, auth_roles |
+| `nav_` | Navigation | nav_menus, nav_routes |
+| `cfg_` | Configuration | cfg_settings, cfg_features |
+| `ai_` | AI/Prompts | ai_prompts, ai_models |
+| `ntf_` | Notifications | ntf_templates, ntf_logs |
+| `wkf_` | Workflows | wkf_definitions, wkf_instances |
+| `doc_` | Documents | doc_files, doc_versions |
+| `tkt_` | Tickets/Support | tkt_tickets, tkt_comments |
+
+**Schemas:**
+- `core` (SchemaConstants.Core): SmartStack platform tables
+- `extensions` (SchemaConstants.Extensions): Client-specific tables
+</tables>
+
+<migrations>
+## Migration Naming
+
+**Format**: `{context}_v{version}_{sequence}_{Description}.cs`
+
+**Examples:**
+- `core_v1.0.0_001_CreateAuthUsers.cs`
+- `core_v1.2.0_001_AddUserProfiles.cs`
+- `extensions_v1.0.0_001_CreateClientOrders.cs`
+
+**Rules:**
+- [ ] Context: `core` or `extensions`
+- [ ] Version: semver format (1.0.0)
+- [ ] Sequence: 3-digit padded (001, 002)
+- [ ] Description: PascalCase, descriptive
+</migrations>
+
+<controllers>
+## Controller Conventions
+
+**NavRoute attribute** (preferred):
+```csharp
+[ApiController]
+[NavRoute("platform.administration.users")]
+public class UsersController : ControllerBase
+{
+    // Routes generated from NavRoute: /api/platform/administration/users
+}
+```
+
+**NavRoute format:**
+- Lowercase only
+- Dot-separated hierarchy
+- Minimum 2 levels: `context.application`
+- Full path: `context.application.module`
+
+**Examples:**
+- `platform.administration.users`
+- `platform.administration.roles`
+- `business.crm.contacts`
+- `personal.myspace.dashboard`
+</controllers>
+
+<services>
+## Service Conventions
+
+**Interface pattern:**
+```csharp
+// Interface
+public interface IUserService
+{
+    Task<UserDto> GetByIdAsync(Guid id, CancellationToken ct);
+    Task<UserDto> CreateAsync(CreateUserDto dto, CancellationToken ct);
+}
+
+// Implementation
+public class UserService : IUserService
+{
+    // ...
+}
+```
+
+**Requirements:**
+- [ ] Interface named `I{Name}Service`
+- [ ] Implementation named `{Name}Service`
+- [ ] All methods async with CancellationToken
+- [ ] Return DTOs, not entities
+</services>
+
+<security>
+## SmartStack Security Patterns
+
+<multi_tenant>
+**Multi-tenant isolation:**
+- ALL queries MUST filter by TenantId (automatic via EF Core global filters)
+- NEVER expose TenantId in URLs
+- NEVER allow cross-tenant data access
+- Create methods MUST require tenantId parameter
+
+**Check for violations:**
+```csharp
+// BAD: No tenant filter
+var users = await _context.Users.ToListAsync();
+
+// GOOD: Tenant filter applied (via global filter or explicit)
+var users = await _context.Users
+    .Where(u => u.TenantId == _tenantId)
+    .ToListAsync();
+```
+</multi_tenant>
+
+<authorization>
+**RBAC with NavRoute:**
+- Controllers use `[NavRoute]` for automatic permission mapping
+- Permissions follow NavRoute pattern: `{navroute}.{action}`
+- Actions: `read`, `create`, `update`, `delete`, `*` (wildcard)
+
+**Example permissions:**
+- `platform.administration.users.read`
+- `platform.administration.users.create`
+- `platform.administration.users.*` (all actions)
+</authorization>
+
+<input_validation>
+**FluentValidation:**
+```csharp
+public class CreateUserDtoValidator : AbstractValidator<CreateUserDto>
+{
+    public CreateUserDtoValidator()
+    {
+        RuleFor(x => x.Email)
+            .NotEmpty()
+            .EmailAddress()
+            .MaximumLength(256);
+    }
+}
+```
+</input_validation>
+</security>
+
+<tests>
+## Test Conventions
+
+**Naming pattern:** `{Method}_When{Condition}_Should{Result}`
+```csharp
+public class UserServiceTests
+{
+    [Fact]
+    public async Task GetById_WhenUserExists_ShouldReturnUser() { }
+
+    [Fact]
+    public async Task GetById_WhenUserNotFound_ShouldThrowNotFoundException() { }
+
+    [Fact]
+    public async Task Create_WhenValidDto_ShouldCreateAndReturnUser() { }
+}
+```
+
+**Structure:**
+```
+Tests/
+├── Unit/
+│   ├── Services/
+│   └── Validators/
+└── Integration/
+    └── Controllers/
+```
+
+**Patterns:**
+- [ ] AAA pattern (Arrange, Act, Assert)
+- [ ] FluentAssertions for assertions
+- [ ] Moq for mocking
+- [ ] Tenant isolation tests for all tenant-aware services
+</tests>
+
+<review_checklist>
+## SmartStack Code Review Checklist
+
+**Run MCP validation first:**
+```
+mcp__smartstack__validate_conventions checks: ["all"]
+```
+
+**Then verify manually:**
+
+<security_checks>
+### Security (BLOCKING)
+- [ ] No hardcoded credentials or secrets
+- [ ] TenantId isolation enforced
+- [ ] Authorization on all endpoints
+- [ ] Input validation present
+- [ ] No SQL injection risks (use EF Core properly)
+</security_checks>
+
+<architecture_checks>
+### Architecture (BLOCKING)
+- [ ] Entities use correct base class (BaseEntity/SystemEntity)
+- [ ] Services have interfaces
+- [ ] Controllers use [NavRoute]
+- [ ] Migrations follow naming convention
+</architecture_checks>
+
+<quality_checks>
+### Quality (SUGGESTION)
+- [ ] Tests exist for new functionality
+- [ ] Factory methods used for entity creation
+- [ ] DTOs used for API boundaries
+- [ ] Async methods have CancellationToken
+</quality_checks>
+</review_checklist>
+
+<sources>
+- SmartStack Architecture Documentation
+- SmartStack.mcp validation tools
+- Clean Architecture by Robert C. Martin
+</sources>