@atlashub/smartstack-cli 1.14.2 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "1.14.2",
+  "version": "1.16.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, APEX, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/agents/efcore/migration.md

@@ -1,6 +1,6 @@
 ---
 name: efcore-migration
-description: EF Core migration manager - create with smart naming (1 per feature)
+description: EF Core migration manager - orchestrates MCP for naming (1 per feature)
 color: magenta
 model: sonnet
 tools: Bash, Glob, Read, Edit
@@ -8,10 +8,24 @@ tools: Bash, Glob, Read, Edit
 
 # EF Core Migration Agent
 
-Manages migration creation with the "1 migration per feature" rule.
+Orchestrates migration creation with the "1 migration per feature" rule.
+
+> **IMPORTANT:** Cet agent **ORCHESTRE** uniquement. Le nommage est **DÉLÉGUÉ AU MCP**.
 
 > **CLAUDE INSTRUCTION:** The `AskUserQuestion({...})` blocks are instructions to use the `AskUserQuestion` tool **interactively**. You MUST execute the tool with these parameters to get the user's response BEFORE continuing.
 
+## Principe : Délégation au MCP
+
+```
+┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
+│  Agent (CLI)    │─────▶│  MCP            │─────▶│  dotnet ef      │
+│  Orchestre      │      │  Génère le nom  │      │  Crée migration │
+└─────────────────┘      └─────────────────┘      └─────────────────┘
+```
+
+**INTERDIT :** Calculer le nom de migration dans cet agent.
+**OBLIGATOIRE :** Appeler `mcp__smartstack__suggest_migration` pour obtenir le nom.
+
 ## Dual DbContext Architecture
 
 SmartStack uses two separate DbContexts with separate migration histories:
@@ -29,53 +43,51 @@ SmartStack uses two separate DbContexts with separate migration histories:
 ## Workflow
 
 1. **Detect** DbContext type (Core vs Extensions)
-2. **Analyze** current branch (feature/hotfix/release)
-3. **Extract** version from package.json or *.csproj
+2. **Ask** user for migration description
+3. **Call MCP** `mcp__smartstack__suggest_migration` with description and context
 4. **Search** for existing migration for this branch
 5. **If exists**: propose to recreate (delete + create)
-6. **Generate** name: `{context}_v{version}_{sequence}_{Description}`
-7. **Create** migration with `dotnet ef migrations add --context {DbContext}`
-8. **Validate** generated content
+6. **Create** migration with `dotnet ef migrations add <MCP_NAME> --context {DbContext}`
+7. **Validate** generated content
+
+## Naming : Délégation MCP
 
-## Naming Pattern
+**TOUJOURS appeler le MCP pour le nommage :**
 
 ```
-{context}_v{version}_{sequence}_{Description}
+mcp__smartstack__suggest_migration({
+  description: "<user_description>",
+  context: "core" | "extensions"
+})
 ```
 
-**Core migrations:**
-- `core_v1.8.0_001_CreateAuthUsers`
-- `core_v1.8.0_002_AddEntraSync`
+Le MCP retourne le nom complet conforme : `{context}_v{version}_{sequence}_{Description}`
 
-**Extensions migrations:**
+**Exemples de noms générés par le MCP :**
+- `core_v1.8.0_001_CreateAuthUsers`
 - `ext_v1.0.0_001_CreateOrders`
-- `ext_v1.0.0_002_AddOrderItems`
 
 ## Commands
 
 ```bash
-# Branch
-git branch --show-current
-
-# Version
-grep -oP '"version":\s*"\K[^"]+' package.json
-
 # Existing migrations for Core
 find Migrations -name "core_*.cs" | grep -v Designer | grep -v Snapshot
 
 # Existing migrations for Extensions
 find Persistence/Migrations -name "ext_*.cs" | grep -v Designer | grep -v Snapshot
 
-# Create Core migration
-dotnet ef migrations add $MIGRATION_NAME --context CoreDbContext -o Persistence/Migrations
+# Create Core migration (use MCP_NAME from suggest_migration)
+dotnet ef migrations add $MCP_NAME --context CoreDbContext -o Persistence/Migrations
 
-# Create Extensions migration
-dotnet ef migrations add $MIGRATION_NAME --context ExtensionsDbContext -o Persistence/Migrations
+# Create Extensions migration (use MCP_NAME from suggest_migration)
+dotnet ef migrations add $MCP_NAME --context ExtensionsDbContext -o Persistence/Migrations
 
-# Delete
+# Delete existing migration
 rm Persistence/Migrations/*${OLD_NAME}*.cs
 ```
 
+> **Note:** `$MCP_NAME` est obtenu via l'appel MCP, jamais calculé localement.
+
 ## Context Detection
 
 If unable to auto-detect:

package/templates/agents/mcp-healthcheck.md

@@ -0,0 +1,161 @@
+---
+name: mcp-healthcheck
+description: Verifies MCP server availability, version and configuration before operations
+color: cyan
+model: haiku
+tools: Bash, Read, Write, Glob
+---
+
+# MCP Health Check Agent
+
+Validates that SmartStack MCP is properly configured and up-to-date before any operation.
+
+## Status File
+
+Location: `.claude/mcp-status.json`
+
+```json
+{
+  "lastCheck": "2024-01-15T10:30:00Z",
+  "mcpVersion": "1.5.0",
+  "mcpPath": "D:\\01 - projets\\SmartStack.mcp",
+  "status": "ok",
+  "tools": ["validate_conventions", "scaffold_extension", "check_migrations", "..."]
+}
+```
+
+## Workflow
+
+### 1. Check Status File Age
+
+```bash
+# Read last check timestamp
+cat .claude/mcp-status.json 2>/dev/null | grep lastCheck
+```
+
+**Decision:**
+- File missing → Full check required
+- Last check > 7 days → Full check required
+- Last check ≤ 7 days → Quick validation only
+
+### 2. Quick Validation (≤ 7 days)
+
+Test MCP connectivity with a lightweight call:
+
+```
+Call: mcp__smartstack__validate_conventions with checks=["tables"]
+Expected: Response without connection error
+```
+
+If fails → Run full check
+
+### 3. Full Check (> 7 days or missing)
+
+#### 3.1 Verify MCP Server Configuration
+
+```bash
+# Check Claude Code MCP config
+cat ~/.claude/settings.json | grep -A 20 "smartstack"
+```
+
+#### 3.2 Test MCP Tools Availability
+
+Call each critical tool to verify availability:
+
+| Tool | Test Call |
+|------|-----------|
+| `validate_conventions` | `checks=["tables"]` |
+| `suggest_migration` | `description="test"` |
+| `check_migrations` | (no params) |
+
+#### 3.3 Check MCP Version
+
+```bash
+# Read MCP package.json
+cat "D:\\01 - projets\\SmartStack.mcp\\package.json" | grep version
+```
+
+#### 3.4 Compare with Latest Release
+
+```bash
+# Check npm registry for latest version
+npm view @anthropic/smartstack-mcp version 2>/dev/null || echo "Not published"
+```
+
+### 4. Update Status File
+
+```javascript
+Write(".claude/mcp-status.json", {
+  lastCheck: new Date().toISOString(),
+  mcpVersion: "<detected_version>",
+  mcpPath: "<configured_path>",
+  status: "ok" | "error",
+  tools: ["<available_tools>"],
+  errors: ["<any_errors>"] // if status = error
+})
+```
+
+## Output Format
+
+### Success
+```
+MCP HEALTH CHECK
+  Status: ✓ OK
+  Version: 1.5.0 (latest)
+  Last check: 2024-01-15
+  Tools available: 12/12
+```
+
+### Warning (outdated)
+```
+MCP HEALTH CHECK
+  Status: ⚠️ UPDATE AVAILABLE
+  Current: 1.4.0
+  Latest: 1.5.0
+  Action: Run `cd SmartStack.mcp && git pull`
+```
+
+### Error
+```
+MCP HEALTH CHECK
+  Status: ❌ ERROR
+  Issue: MCP server not responding
+  Action: Verify MCP configuration in Claude Code settings
+```
+
+## Integration
+
+This agent should be called:
+1. **Before any MCP-dependent operation** (scaffold, validate, migrate)
+2. **On CLI installation/update**
+3. **Manually via `/mcp:healthcheck`**
+
+## Caching Logic
+
+```
+┌─────────────────────┐
+│  Operation Start    │
+└──────────┬──────────┘
+           ▼
+┌─────────────────────┐
+│ Read mcp-status.json│
+└──────────┬──────────┘
+           ▼
+    ┌──────────────┐
+    │ File exists? │
+    └──────┬───────┘
+           │
+     No ───┼─── Yes
+           │     │
+           ▼     ▼
+    ┌──────────────────┐
+    │   > 7 days old?  │
+    └──────┬───────────┘
+           │
+     Yes ──┼─── No
+           │     │
+           ▼     ▼
+┌──────────────┐  ┌──────────────┐
+│  Full Check  │  │ Quick Check  │
+└──────────────┘  └──────────────┘
+```

package/templates/hooks/mcp-check.md

@@ -0,0 +1,64 @@
+---
+description: Quick MCP availability check before MCP tool calls
+trigger: tool-use
+match: mcp__smartstack__*
+blocking: false
+---
+
+# MCP Quick Check (Low Token)
+
+Lightweight pre-check before MCP calls. Reads cache only, no LLM processing.
+
+## Script
+
+```bash
+#!/bin/bash
+STATUS_FILE=".claude/mcp-status.json"
+MAX_AGE_DAYS=7
+
+# Create .claude if missing
+mkdir -p .claude
+
+# Check if status file exists
+if [ ! -f "$STATUS_FILE" ]; then
+  echo "⚠️ MCP: First use - run /mcp:healthcheck"
+  exit 0
+fi
+
+# Check file age (cross-platform)
+if command -v stat &> /dev/null; then
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    FILE_AGE=$(( ($(date +%s) - $(stat -f %m "$STATUS_FILE")) / 86400 ))
+  else
+    FILE_AGE=$(( ($(date +%s) - $(stat -c %Y "$STATUS_FILE")) / 86400 ))
+  fi
+
+  if [ "$FILE_AGE" -gt "$MAX_AGE_DAYS" ]; then
+    echo "⚠️ MCP: Cache expired ($FILE_AGE days) - run /mcp:healthcheck"
+  fi
+fi
+
+# Check last status
+STATUS=$(grep -o '"status":\s*"[^"]*"' "$STATUS_FILE" 2>/dev/null | cut -d'"' -f4)
+if [ "$STATUS" = "error" ]; then
+  echo "❌ MCP: Last check failed - run /mcp:healthcheck"
+  exit 1
+fi
+
+exit 0
+```
+
+## Behavior
+
+| Condition | Output | Blocks? |
+|-----------|--------|---------|
+| No cache file | Warning message | No |
+| Cache > 7 days | Warning message | No |
+| Last status = error | Error message | Yes |
+| All OK | Silent (no output) | No |
+
+## Token Cost
+
+- **Normal case (cache valid):** 0 tokens (pure bash, no LLM)
+- **Warning case:** ~10 tokens (displays message)
+- **Full healthcheck:** ~100-200 tokens (only when explicitly called)

package/templates/skills/application/SKILL.md

@@ -13,6 +13,39 @@ description: |
 
 **Reference:** [_shared.md](../_shared.md) for architecture, permissions, i18n
 
+## ENTRY POINT
+
+> **FIRST ACTION:** Load `steps/step-00-init.md`
+
+This skill uses progressive step loading. Each step calls MCP tools for generation.
+
+## STEP FILES
+
+| Step | File | MCP Tool Called |
+|------|------|-----------------|
+| 00 | `steps/step-00-init.md` | `validate_conventions` (MCP check) |
+| 01 | `steps/step-01-navigation.md` | `scaffold_navigation` |
+| 02 | `steps/step-02-permissions.md` | `generate_permissions` |
+| 03 | `steps/step-03-roles.md` | `scaffold_role_permissions` |
+| 04 | `steps/step-04-backend.md` | `scaffold_extension` |
+| 05 | `steps/step-05-frontend.md` | `scaffold_api_client`, `scaffold_routes` |
+| 06 | `steps/step-06-migration.md` | `suggest_migration` |
+
+## MCP INTEGRATION
+
+> **CRITICAL:** This skill MUST use MCP tools for all generation.
+> Templates in this folder are for REFERENCE ONLY - never use them directly.
+
+| MCP Tool | Purpose |
+|----------|---------|
+| `mcp__smartstack__scaffold_navigation` | Navigation entity + translations |
+| `mcp__smartstack__generate_permissions` | Permissions.cs + HasData |
+| `mcp__smartstack__scaffold_role_permissions` | Role-permission mappings |
+| `mcp__smartstack__scaffold_extension` | Entity, Service, Controller, DTOs |
+| `mcp__smartstack__scaffold_api_client` | TypeScript API client |
+| `mcp__smartstack__scaffold_routes` | React Router configuration |
+| `mcp__smartstack__suggest_migration` | Migration name suggestion |
+
 ## WHEN THIS SKILL ACTIVATES
 
 | Trigger | Example |
@@ -134,7 +167,20 @@ await _workflowService.TriggerAsync("{entity}.created", new Dictionary<string, o
 
 ## ASSOCIATED FILES
 
-- [templates-backend.md](templates-backend.md)
-- [templates-frontend.md](templates-frontend.md)
-- [templates-i18n.md](templates-i18n.md)
-- [templates-seed.md](templates-seed.md)
+### Step Files (ACTIVE - Use These)
+- [steps/step-00-init.md](steps/step-00-init.md) - Initialize parameters
+- [steps/step-01-navigation.md](steps/step-01-navigation.md) - Generate navigation
+- [steps/step-02-permissions.md](steps/step-02-permissions.md) - Generate permissions
+- [steps/step-03-roles.md](steps/step-03-roles.md) - Assign roles
+- [steps/step-04-backend.md](steps/step-04-backend.md) - Generate backend
+- [steps/step-05-frontend.md](steps/step-05-frontend.md) - Generate frontend
+- [steps/step-06-migration.md](steps/step-06-migration.md) - Create migration
+
+### Templates (REFERENCE ONLY - Do Not Use Directly)
+> These templates are kept for documentation purposes.
+> All generation is done via MCP tools in step files.
+
+- [templates-backend.md](templates-backend.md) - Backend patterns reference
+- [templates-frontend.md](templates-frontend.md) - Frontend patterns reference
+- [templates-i18n.md](templates-i18n.md) - i18n structure reference
+- [templates-seed.md](templates-seed.md) - Seed data patterns reference

package/templates/skills/application/steps/step-00-init.md

@@ -0,0 +1,153 @@
+---
+name: step-00-init
+description: Initialize application/module creation - parse parameters and validate context
+next_step: steps/step-01-navigation.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES
+
+- NEVER skip parameter validation
+- ALWAYS detect the navigation level from user request
+- ALWAYS validate MCP availability before proceeding
+- YOU ARE AN INITIALIZER, not an executor
+- FORBIDDEN to call MCP tools until init is complete
+
+## YOUR TASK
+
+Initialize the application/module creation by parsing parameters, detecting level, and validating the SmartStack context.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Detect Navigation Level
+
+From user request, identify the level:
+
+| Hint in Request | → Level | Parent Required |
+|-----------------|---------|-----------------|
+| "context", "workspace", "nouveau contexte" | context | No |
+| "application", "app", "nouvelle application" | application | Yes (context) |
+| "module", "feature", "nouveau module" | module | Yes (context.application) |
+| "section", "tab", "nouvelle section" | section | Yes (context.app.module) |
+
+### 2. Extract Parameters
+
+```yaml
+# Required
+level: context | application | module | section
+code: kebab-case (e.g., "products", "order-management")
+labels:
+  fr: "Label français"
+  en: "English label"
+  it: "Etichetta italiana"
+  de: "Deutsche Bezeichnung"
+icon: Lucide icon name (e.g., "Package", "ShoppingCart")
+displayOrder: number
+
+# Conditional (required for non-context levels)
+parentPath: "context.application.module" (dot-separated)
+```
+
+### 3. Validate MCP Availability
+
+**CRITICAL:** Before proceeding, verify SmartStack MCP is available:
+
+```
+Call: mcp__smartstack__validate_conventions
+Args: { checks: ["all"] }
+```
+
+If MCP call fails:
+- Display warning: "SmartStack MCP not available"
+- Provide manual instructions instead of automated generation
+- Do NOT proceed with step files
+
+### 4. Build Full Path
+
+```
+{full_path} = {parentPath}.{code}  (if parentPath exists)
+{full_path} = {code}               (if context level)
+
+Example:
+  level: module
+  parentPath: erp.sales
+  code: products
+  → full_path: erp.sales.products
+```
+
+### 5. Infer Descriptions (if not provided)
+
+```yaml
+descriptions:
+  fr: "Gestion de {labels.fr}"
+  en: "{labels.en} management"
+  it: "Gestione di {labels.it}"
+  de: "Verwaltung von {labels.de}"
+```
+
+### 6. Show Summary
+
+```
+## Application Skill: {level} - {code}
+
+| Parameter | Value |
+|-----------|-------|
+| Level | {level} |
+| Code | {code} |
+| Full Path | {full_path} |
+| Parent | {parentPath} |
+| Icon | {icon} |
+| Display Order | {displayOrder} |
+
+### Labels
+| Language | Label |
+|----------|-------|
+| FR | {labels.fr} |
+| EN | {labels.en} |
+| IT | {labels.it} |
+| DE | {labels.de} |
+
+→ Proceeding to navigation generation...
+```
+
+---
+
+## STATE VARIABLES TO PERSIST
+
+| Variable | Description |
+|----------|-------------|
+| `{level}` | context, application, module, or section |
+| `{code}` | kebab-case identifier |
+| `{full_path}` | Complete navigation path |
+| `{parent_path}` | Parent path (null for context) |
+| `{labels}` | Object with fr, en, it, de |
+| `{descriptions}` | Object with fr, en, it, de |
+| `{icon}` | Lucide icon name |
+| `{display_order}` | Numeric display order |
+| `{mcp_available}` | Boolean - MCP connectivity status |
+
+---
+
+## SUCCESS METRICS
+
+- Level correctly detected
+- All required parameters extracted
+- MCP availability verified
+- Full path computed correctly
+- Summary displayed
+- Proceeded to step-01-navigation.md
+
+## FAILURE MODES
+
+- Missing required parameters (ask user)
+- Invalid level detection (clarify with user)
+- MCP not available (provide manual instructions)
+
+---
+
+## NEXT STEP
+
+After showing initialization summary, proceed to `./step-01-navigation.md`

package/templates/skills/application/steps/step-01-navigation.md

@@ -0,0 +1,144 @@
+---
+name: step-01-navigation
+description: Generate navigation entity seeds using MCP scaffold_navigation
+prev_step: steps/step-00-init.md
+next_step: steps/step-02-permissions.md
+---
+
+# Step 1: Navigation Generation
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use MCP `scaffold_navigation` tool - NEVER use templates
+- NEVER generate code manually - let MCP handle it
+- ALWAYS verify the output includes translations for 4 languages
+- YOU ARE AN ORCHESTRATOR calling MCP, not a generator
+
+## YOUR TASK
+
+Call the SmartStack MCP `scaffold_navigation` tool to generate:
+1. Navigation entity HasData() code
+2. NavigationTranslation entries (4 languages)
+
+---
+
+## AVAILABLE STATE
+
+From step-00-init:
+
+| Variable | Description |
+|----------|-------------|
+| `{level}` | context, application, module, or section |
+| `{code}` | kebab-case identifier |
+| `{full_path}` | Complete navigation path |
+| `{parent_path}` | Parent path (null for context) |
+| `{labels}` | Object with fr, en, it, de |
+| `{descriptions}` | Object with fr, en, it, de |
+| `{icon}` | Lucide icon name |
+| `{display_order}` | Numeric display order |
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Call MCP scaffold_navigation
+
+```
+Tool: mcp__smartstack__scaffold_navigation
+Args:
+  level: "{level}"
+  code: "{code}"
+  parentPath: "{parent_path}"  # Omit if level is "context"
+  labels:
+    fr: "{labels.fr}"
+    en: "{labels.en}"
+    it: "{labels.it}"
+    de: "{labels.de}"
+  descriptions:
+    fr: "{descriptions.fr}"
+    en: "{descriptions.en}"
+    it: "{descriptions.it}"
+    de: "{descriptions.de}"
+  icon: "{icon}"
+  displayOrder: {display_order}
+```
+
+### 2. Parse MCP Response
+
+The tool returns:
+- Navigation entity GUID (deterministic)
+- HasData() code for NavigationXxxConfiguration.cs
+- HasData() code for NavigationTranslationConfiguration.cs
+- SeedData class template (optional)
+
+### 3. Present Output to User
+
+```markdown
+## Navigation Seeds Generated
+
+**Entity:** {level} - {code}
+**GUID:** {generated_guid}
+**Path:** {full_path}
+
+### Files to Update
+
+1. **{NavigationLevelConfiguration}.cs**
+   [Show HasData code from MCP response]
+
+2. **NavigationTranslationConfiguration.cs**
+   [Show translation HasData code from MCP response]
+
+### Recommended: Create SeedData Class
+
+[Show SeedData class from MCP response]
+```
+
+### 4. Store Generated GUID
+
+**CRITICAL:** Store the navigation entity GUID for use in step-02-permissions:
+
+```
+{navigation_guid} = [GUID from MCP response]
+```
+
+This GUID will be referenced when creating permissions.
+
+---
+
+## MCP RESPONSE HANDLING
+
+### Success Case
+
+If MCP returns successfully:
+- Extract and display all HasData code
+- Store `{navigation_guid}` for next step
+- Proceed to step-02-permissions.md
+
+### Error Case
+
+If MCP call fails:
+- Display error message
+- Suggest manual alternatives
+- Do NOT proceed automatically
+
+---
+
+## SUCCESS METRICS
+
+- MCP scaffold_navigation called successfully
+- Navigation entity GUID obtained
+- HasData code displayed to user
+- Translation code displayed (4 languages)
+- Proceeded to step-02-permissions.md
+
+## FAILURE MODES
+
+- MCP call failed (display error, stop)
+- Missing parent path for non-context level (return to step-00)
+- Invalid level (return to step-00)
+
+---
+
+## NEXT STEP
+
+After displaying navigation seeds, proceed to `./step-02-permissions.md`