@atlashub/smartstack-cli 1.14.2 → 1.16.0

package/templates/skills/application/steps/step-05-frontend.md

@@ -0,0 +1,218 @@
+---
+name: step-05-frontend
+description: Generate frontend code using MCP tools (component, API client, routes, i18n)
+prev_step: steps/step-04-backend.md
+next_step: steps/step-06-migration.md
+---
+
+# Step 5: Frontend Generation
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use MCP tools for frontend generation
+- ALWAYS generate i18n for 4 languages (fr, en, it, de)
+- ALWAYS use nested routes (not flat)
+- YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+
+## YOUR TASK
+
+Use MCP tools to generate:
+1. React component (scaffold_extension type: component)
+2. TypeScript API client (scaffold_api_client)
+3. Route configuration (scaffold_routes)
+4. i18n files (scaffold_translations for UI)
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{full_path}` | Complete navigation path (navRoute) |
+| `{entity_name}` | PascalCase entity name |
+| `{entity_code}` | kebab-case code |
+| `{labels}` | Object with fr, en, it, de |
+| `{api_route}` | API endpoint path |
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Generate React Component
+
+```
+Tool: mcp__smartstack__scaffold_extension
+Args:
+  type: "component"
+  name: "{entity_name}"
+  options:
+    outputPath: "web/src/pages/{context}/{application}/{module}"
+    dryRun: false
+```
+
+This generates:
+- `{EntityName}Page.tsx` - Main page component
+- `{EntityName}ListView.tsx` - Reusable list view
+- `use{EntityName}.ts` - Custom hook for data
+
+### 2. Generate API Client
+
+```
+Tool: mcp__smartstack__scaffold_api_client
+Args:
+  navRoute: "{full_path}"
+  name: "{entity_name}"
+  methods: ["getAll", "getById", "create", "update", "delete"]
+  options:
+    includeTypes: true
+    includeHook: true
+```
+
+This generates:
+- `services/api/{entityCode}Api.ts` - API service
+- `types/{entityName}.types.ts` - TypeScript interfaces
+- `hooks/use{EntityName}Api.ts` - React Query hook (optional)
+
+### 3. Update Route Configuration
+
+```
+Tool: mcp__smartstack__scaffold_routes
+Args:
+  source: "controllers"
+  scope: "all"
+  options:
+    includeGuards: true
+    generateRegistry: true
+```
+
+This updates:
+- `navRoutes.generated.ts` - Route registry
+- `routes.tsx` - React Router configuration
+
+### 4. Generate i18n Files
+
+Create translation files for each language:
+
+```markdown
+### French (fr/{entityCode}.json)
+```json
+{
+  "title": "{labels.fr}",
+  "subtitle": "Gestion de {labels.fr}",
+  "columns": {
+    "code": "Code",
+    "name": "Nom",
+    "createdAt": "Créé le",
+    "actions": "Actions"
+  },
+  "form": {
+    "code": "Code",
+    "name": "Nom",
+    "submit": "Enregistrer",
+    "cancel": "Annuler"
+  },
+  "messages": {
+    "created": "{labels.fr} créé avec succès",
+    "updated": "{labels.fr} mis à jour avec succès",
+    "deleted": "{labels.fr} supprimé avec succès",
+    "error": "Une erreur est survenue"
+  }
+}
+```
+
+Repeat for en, it, de with appropriate translations.
+
+### 5. Present Output to User
+
+```markdown
+## Frontend Code Generated
+
+### Components
+- `pages/{context}/{application}/{module}/{EntityName}Page.tsx`
+- `pages/{context}/{application}/{module}/{EntityName}ListView.tsx`
+- `hooks/use{EntityName}.ts`
+
+### API Client
+- `services/api/{entityCode}Api.ts`
+- `types/{entityName}.types.ts`
+
+### Routes
+- Updated `navRoutes.generated.ts`
+- Updated `routes.tsx` with nested route
+
+### i18n
+- `locales/fr/{entityCode}.json`
+- `locales/en/{entityCode}.json`
+- `locales/it/{entityCode}.json`
+- `locales/de/{entityCode}.json`
+
+### Route Configuration
+```tsx
+// In routes.tsx - NESTED routes (not flat!)
+<Route path="{application}">
+  <Route index element={<Navigate to="{module}" replace />} />
+  <Route path="{module}" element={<{EntityName}Page />} />
+</Route>
+```
+```
+
+---
+
+## ROUTING RULES
+
+**CRITICAL:** SmartStack requires NESTED routes:
+
+```tsx
+// ✅ CORRECT - Nested routes
+<Route path="sales">
+  <Route index element={<Navigate to="products" replace />} />
+  <Route path="products" element={<ProductsPage />} />
+  <Route path="orders" element={<OrdersPage />} />
+</Route>
+
+// ❌ FORBIDDEN - Flat routes (cause redirect issues)
+<Route path="sales" element={<Navigate to="products" />} />
+<Route path="sales/products" element={<ProductsPage />} />
+```
+
+---
+
+## I18N STRUCTURE
+
+All i18n files must follow this structure:
+
+```
+locales/
+├── fr/
+│   └── {entityCode}.json
+├── en/
+│   └── {entityCode}.json
+├── it/
+│   └── {entityCode}.json
+└── de/
+    └── {entityCode}.json
+```
+
+---
+
+## SUCCESS METRICS
+
+- React component generated
+- API client generated with types
+- Routes updated (nested structure)
+- i18n files created (4 languages)
+- Proceeded to step-06-migration.md
+
+## FAILURE MODES
+
+- Component generation failed (check entity name)
+- API client generation failed (check navRoute)
+- Route configuration failed (check existing routes)
+
+---
+
+## NEXT STEP
+
+After displaying frontend code, proceed to `./step-06-migration.md`

package/templates/skills/application/steps/step-06-migration.md

@@ -0,0 +1,190 @@
+---
+name: step-06-migration
+description: Create EF Core migration and finalize application setup
+prev_step: steps/step-05-frontend.md
+next_step: null
+---
+
+# Step 6: Migration & Finalization
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use MCP `suggest_migration` to get proper migration name
+- ALWAYS use `/efcore:migration` skill for migration creation
+- NEVER use raw SQL in migrations
+- YOU ARE AN ORCHESTRATOR, finalizing the application setup
+
+## YOUR TASK
+
+1. Get suggested migration name from MCP
+2. Create the EF Core migration
+3. Provide final checklist to user
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{entity_name}` | PascalCase entity name |
+| `{full_path}` | Complete navigation path |
+| `{level}` | Navigation level |
+| `{labels}` | Translated labels |
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Get Migration Name Suggestion
+
+```
+Tool: mcp__smartstack__suggest_migration
+Args:
+  description: "Add {entity_name} with navigation and permissions"
+  context: "core"
+```
+
+Response example:
+```
+Migration name: core_v1.2.0_003_Add{EntityName}WithNavigationAndPermissions
+Command: dotnet ef migrations add core_v1.2.0_003_Add{EntityName}WithNavigationAndPermissions --context CoreDbContext -o Persistence/Migrations
+```
+
+### 2. Create Migration
+
+Use the /efcore:migration skill or direct command:
+
+```bash
+cd Infrastructure
+dotnet ef migrations add {suggested_migration_name} --context CoreDbContext -o Persistence/Migrations
+```
+
+### 3. Verify Migration Content
+
+The migration should include:
+- Navigation entity (Context/Application/Module/Section)
+- Navigation translations (4 languages)
+- Permissions (CRUD + wildcard)
+- RolePermissions (role assignments)
+- Domain entity table
+- Indexes and constraints
+
+### 4. Apply Migration
+
+```bash
+dotnet ef database update --context CoreDbContext
+```
+
+### 5. Present Final Checklist
+
+```markdown
+## Application Setup Complete
+
+### Summary
+
+| Item | Status |
+|------|--------|
+| Navigation | ✅ {level}: {full_path} |
+| Translations | ✅ 4 languages (fr, en, it, de) |
+| Permissions | ✅ CRUD + Wildcard |
+| Role Mappings | ✅ PlatformAdmin, TenantAdmin, StandardUser |
+| Entity | ✅ {entity_name} |
+| Service | ✅ I{entity_name}Service |
+| Controller | ✅ {entity_name}Controller |
+| DTOs | ✅ Create, Update, Response |
+| Frontend | ✅ Page, ListView, Hook |
+| API Client | ✅ TypeScript with types |
+| i18n | ✅ 4 languages |
+| Routes | ✅ Nested configuration |
+| Migration | ✅ {migration_name} |
+
+### Final Steps
+
+1. **Verify DbSet registration:**
+   ```csharp
+   // In ICoreDbContext.cs
+   public DbSet<{entity_name}> {entity_name}s => Set<{entity_name}>();
+   ```
+
+2. **Verify DI registration:**
+   ```csharp
+   // In DependencyInjection.cs
+   services.AddScoped<I{entity_name}Service, {entity_name}Service>();
+   ```
+
+3. **Test the application:**
+   ```bash
+   # Backend
+   dotnet run --project Api
+
+   # Frontend
+   cd web && npm run dev
+   ```
+
+4. **Verify navigation:**
+   - Login to the application
+   - Navigate to {full_path}
+   - Verify CRUD operations work
+
+### API Endpoints
+
+| Method | Endpoint | Permission |
+|--------|----------|------------|
+| GET | /api/{entity_code} | {full_path}.read |
+| GET | /api/{entity_code}/{id} | {full_path}.read |
+| POST | /api/{entity_code} | {full_path}.create |
+| PUT | /api/{entity_code}/{id} | {full_path}.update |
+| DELETE | /api/{entity_code}/{id} | {full_path}.delete |
+```
+
+---
+
+## TROUBLESHOOTING
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Migration conflicts | Run `/efcore:conflicts` to analyze |
+| Permission 403 errors | Verify Permissions.cs and PermissionConfiguration.cs are in sync |
+| Navigation not visible | Check user role has appropriate permissions |
+| Route not found | Verify nested route structure in routes.tsx |
+| i18n missing | Check locale files exist and are properly loaded |
+
+### Quick Fixes
+
+```bash
+# Rebuild and restart
+dotnet build
+dotnet ef database update
+
+# Clear frontend cache
+cd web && rm -rf node_modules/.cache && npm run dev
+```
+
+---
+
+## SUCCESS METRICS
+
+- Migration name suggested via MCP
+- Migration created and applied
+- All checklist items verified
+- Application functional
+
+## COMPLETION
+
+The /application skill workflow is complete. The user now has:
+- Full navigation structure
+- RBAC permissions
+- Backend CRUD API
+- Frontend components
+- i18n support
+- Database migration
+
+---
+
+## END OF WORKFLOW
+
+This is the final step. No further steps to proceed.

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
+```