@atlashub/smartstack-cli 1.11.0 → 1.13.1

package/templates/commands/gitflow/_shared.md

@@ -0,0 +1,196 @@
+# GitFlow - Fonctions Partagées
+
+> **Usage:** Ce fichier contient les fonctions réutilisables. Référencer avec `{{REF:section_name}}` dans les autres fichiers.
+
+---
+
+## DETECT_PROVIDER
+
+Détecte GitHub ou Azure DevOps depuis le remote.
+
+```bash
+detect_git_provider() {
+  REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+
+  if [[ "$REMOTE_URL" == *"dev.azure.com"* ]] || [[ "$REMOTE_URL" == *"visualstudio.com"* ]]; then
+    GIT_PROVIDER="azuredevops"
+    [[ "$REMOTE_URL" =~ dev\.azure\.com/([^/]+)/([^/]+)/_git/([^/]+) ]] && {
+      AZURE_ORG="${BASH_REMATCH[1]}"
+      AZURE_PROJECT="${BASH_REMATCH[2]}"
+      AZURE_REPO="${BASH_REMATCH[3]}"
+    }
+  elif [[ "$REMOTE_URL" == *"github.com"* ]]; then
+    GIT_PROVIDER="github"
+  else
+    GIT_PROVIDER="unknown"
+  fi
+}
+```
+
+---
+
+## NORMALIZE_NAME
+
+Normalise un nom de branche (accents, espaces, caractères spéciaux).
+
+```bash
+normalize_branch_name() {
+  local input="$1" max_length="${2:-50}"
+  echo "$input" | tr '[:upper:]' '[:lower:]' | \
+    sed 'y/àâäéèêëïîôùûüçœæ/aaaeeeeiioouucoa/' | \
+    sed "s/[ _']/-/g" | sed 's/[^a-z0-9-]//g' | \
+    sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-$max_length | sed 's/-$//'
+}
+```
+
+---
+
+## DETECT_WORKTREE_MODE
+
+Détecte le mode worktree (organized, adjacent, none).
+
+```bash
+detect_worktree_mode() {
+  if [ -d "../features" ] && [ -d "../releases" ] && [ -d "../hotfixes" ]; then
+    WORKTREE_MODE="organized"
+  elif [ -d "../01-Main" ] && [ -d "../02-Develop" ]; then
+    WORKTREE_MODE="organized"
+  elif [ -d "../worktrees" ]; then
+    WORKTREE_MODE="adjacent"
+  else
+    CONFIG_FILE=".claude/gitflow/config.json"
+    [ -f "$CONFIG_FILE" ] && WORKTREE_MODE=$(grep -oP '"mode":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+    WORKTREE_MODE=${WORKTREE_MODE:-adjacent}
+  fi
+}
+```
+
+---
+
+## CLEANUP_WORKTREE
+
+Nettoie un worktree pour une branche donnée.
+
+```bash
+cleanup_worktree_for_branch() {
+  local BRANCH=$1 WORKTREE_BASE="../worktrees" WORKTREE_PATH=""
+
+  case "$BRANCH" in
+    feature/*) WORKTREE_PATH="$WORKTREE_BASE/features/${BRANCH#feature/}" ;;
+    release/*) WORKTREE_PATH="$WORKTREE_BASE/releases/${BRANCH#release/}" ;;
+    hotfix/*)  WORKTREE_PATH="$WORKTREE_BASE/hotfixes/${BRANCH#hotfix/}" ;;
+  esac
+
+  # Mode organized
+  [ -d "../features" ] && case "$BRANCH" in
+    feature/*) WORKTREE_PATH="../features/${BRANCH#feature/}" ;;
+    release/*) WORKTREE_PATH="../releases/${BRANCH#release/}" ;;
+    hotfix/*)  WORKTREE_PATH="../hotfixes/${BRANCH#hotfix/}" ;;
+  esac
+
+  [ -d "$WORKTREE_PATH" ] && {
+    git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || rm -rf "$WORKTREE_PATH"
+    git worktree prune
+    echo "✓ Worktree nettoyé: $WORKTREE_PATH"
+  }
+}
+```
+
+---
+
+## SYNC_REMOTE
+
+Synchronise avec le remote et affiche l'état.
+
+```bash
+sync_with_remote() {
+  git fetch --all --quiet
+  local BRANCH=$(git branch --show-current)
+  local AHEAD=$(git rev-list --count origin/$BRANCH..HEAD 2>/dev/null || echo "0")
+  local BEHIND=$(git rev-list --count HEAD..origin/$BRANCH 2>/dev/null || echo "0")
+
+  [ "$BEHIND" -gt 0 ] && echo "⚠️ $BRANCH: $BEHIND commit(s) en retard"
+  [ "$AHEAD" -gt 0 ] && echo "ℹ️ $BRANCH: $AHEAD commit(s) non poussé(s)"
+}
+```
+
+---
+
+## READ_GITFLOW_CONFIG
+
+Lit la configuration GitFlow.
+
+```bash
+read_gitflow_config() {
+  local CONFIG_FILE=".claude/gitflow/config.json"
+  [ ! -f "$CONFIG_FILE" ] && return 1
+
+  # Variables exportées
+  GF_LANG=$(grep -oP '"code":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+  GF_WORKTREE_MODE=$(grep -oP '"mode":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+  GF_MAIN_BRANCH=$(grep -oP '"main":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+  GF_DEVELOP_BRANCH=$(grep -oP '"develop":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+
+  GF_LANG=${GF_LANG:-en}
+  GF_WORKTREE_MODE=${GF_WORKTREE_MODE:-adjacent}
+  GF_MAIN_BRANCH=${GF_MAIN_BRANCH:-main}
+  GF_DEVELOP_BRANCH=${GF_DEVELOP_BRANCH:-develop}
+}
+```
+
+---
+
+## CONFIG_TEMPLATE
+
+Template JSON de configuration GitFlow (version minimale).
+
+```json
+{
+  "version": "1.3.0",
+  "branches": { "main": "main", "develop": "develop" },
+  "prefixes": { "feature": "feature/", "release": "release/", "hotfix": "hotfix/" },
+  "worktrees": { "mode": "organized" },
+  "language": { "code": "fr" }
+}
+```
+
+**Options worktrees.mode:**
+- `organized`: `../features/`, `../releases/`, `../hotfixes/`
+- `adjacent`: `../worktrees/{type}/`
+- `disabled`: Pas de worktrees
+
+---
+
+## PR_COMMANDS
+
+Commandes PR par provider.
+
+### GitHub
+```bash
+gh pr create --title "$TITLE" --body "$BODY" --base "$BASE"
+gh pr view $NUMBER --json state,mergeable,reviews
+gh pr merge $NUMBER --squash --delete-branch
+```
+
+### Azure DevOps
+```bash
+az repos pr create --title "$TITLE" --description "$BODY" --source-branch "$SOURCE" --target-branch "$BASE"
+az repos pr show --id $NUMBER --query "{status:status,mergeStatus:mergeStatus}"
+az repos pr update --id $NUMBER --status completed --squash true --delete-source-branch true
+```
+
+---
+
+## OUTPUT_FORMAT
+
+Format de sortie standard (remplace ASCII art).
+
+```bash
+output_header() { echo -e "\n## $1\n"; }
+output_section() { echo "### $1"; }
+output_item() { echo "- $1"; }
+output_success() { echo "✓ $1"; }
+output_warning() { echo "⚠️ $1"; }
+output_error() { echo "❌ $1"; }
+output_next() { echo "→ Prochain: $1"; }
+```

package/templates/commands/quickstart.md

@@ -0,0 +1,154 @@
+---
+description: "Quick start guide for SmartStack CLI"
+---
+
+# SmartStack Quick Start Guide
+
+## Installation (3 steps)
+
+### Step 1: Install SmartStack CLI
+```bash
+npm install -g @atlashub/smartstack-cli
+```
+
+### Step 2: Activate License
+```bash
+smartstack license activate <your-license-key>
+```
+
+### Step 3: Install Templates
+```bash
+smartstack install
+```
+
+## Verify Setup
+
+Run the doctor command to verify everything is configured:
+```bash
+smartstack doctor
+```
+
+Expected output:
+```
+✓ License valid
+✓ Node.js v20.x.x
+✓ Claude Code CLI installed
+✓ MCP: context7 available
+✓ MCP: smartstack available
+✓ SmartStack Commands installed
+```
+
+## MCP Servers
+
+SmartStack requires two MCP servers for full functionality:
+
+### Check MCP Status
+```bash
+smartstack check-mcp
+```
+
+### Install Missing MCPs
+```bash
+smartstack check-mcp --install
+```
+
+Or manually:
+```bash
+claude mcp add context7
+claude mcp add smartstack
+```
+
+## Create Your First Project
+
+```bash
+# Create a new SmartStack project
+smartstack init MyProject
+
+# Navigate to the project
+cd MyProject
+
+# Start backend
+dotnet run --project src/MyProject.Api
+
+# Start frontend (in another terminal)
+cd web/myproject-web
+npm install
+npm run dev
+```
+
+## Ralph Automation
+
+Ralph Weegund is an AI-powered iterative development loop.
+
+### Setup Ralph
+```bash
+# Verify Ralph prerequisites
+smartstack ralph start
+
+# Initialize Ralph in your project (if not done by init)
+smartstack ralph init
+```
+
+### Use Ralph in Claude Code
+```
+/ralph-loop "Implement user authentication with JWT"
+```
+
+### Monitor Ralph
+```bash
+# Check status
+smartstack ralph status
+
+# View logs
+smartstack ralph logs
+
+# View reports
+smartstack ralph report --list
+```
+
+## Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `smartstack doctor` | Full system diagnostic |
+| `smartstack check-mcp` | Verify MCP servers |
+| `smartstack status` | Show installation status |
+| `smartstack ralph start` | Prepare Ralph for use |
+| `/gitflow` | GitFlow workflow |
+| `/apex` | APEX methodology |
+| `/ralph-loop` | Start automation loop |
+
+## Troubleshooting
+
+### "License required" error
+```bash
+smartstack license activate <key>
+```
+
+### "MCP server not found"
+```bash
+smartstack check-mcp --install
+```
+
+### "Ralph not configured"
+```bash
+smartstack ralph init
+```
+
+### Full diagnostic
+```bash
+smartstack doctor --verbose
+```
+
+## Next Steps
+
+1. **Explore Commands**: `smartstack docs commands`
+2. **Learn GitFlow**: `smartstack docs gitflow`
+3. **Try APEX**: `/apex "Build a feature"`
+4. **Use Ralph**: `/ralph-loop "Your task"`
+
+## Resources
+
+- Documentation: https://docs.smartstack.app
+- Support: https://github.com/atlashub/smartstack-cli/issues
+- Website: https://smartstack.app

package/templates/commands/ralph-loop/ralph-loop.md

@@ -13,6 +13,108 @@ Execute the setup script to initialize the Ralph loop:
 "${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
 ```
 
-Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+---
+
+## RALPH WEEGUND - AUTOMATED DEVELOPMENT LOOP
+
+You are now operating in **Ralph Weegund** mode - an iterative AI development loop for SmartStack projects.
+
+### MANDATORY MCP VALIDATION
+
+**BEFORE STARTING ANY WORK**, you MUST verify MCP servers are available:
+
+1. **Check context7 MCP**: Use `mcp__plugin_context7_context7__resolve-library-id` to verify connectivity
+2. **Check smartstack MCP**: Use `mcp__smartstack__validate_conventions` with a simple check
+
+**IF ANY MCP SERVER IS UNAVAILABLE:**
+- DO NOT proceed with the task
+- Log the failure to `.ralph/logs/`
+- Output a clear error message explaining which MCP is down
+- Suggest running `smartstack check-mcp` to diagnose
+
+### STRICT MCP USAGE REQUIREMENTS
+
+Throughout your work, you MUST:
+
+1. **Use SmartStack MCP for all validations**:
+   - `mcp__smartstack__validate_conventions` - Before any commit
+   - `mcp__smartstack__check_migrations` - Before any EF Core changes
+   - `mcp__smartstack__scaffold_extension` - For code generation
+   - `mcp__smartstack__api_docs` - For API documentation
+
+2. **Use Context7 MCP for documentation**:
+   - `mcp__plugin_context7_context7__resolve-library-id` - Find library docs
+   - `mcp__plugin_context7_context7__query-docs` - Query specific documentation
+
+3. **Track all MCP calls** by logging them mentally for the final report
+
+### LOGGING PROTOCOL
+
+For each significant action, maintain an internal log:
+- MCP tool calls (which tool, parameters, success/failure)
+- Files created/modified
+- Validations performed
+- Errors encountered
+
+### ITERATION BEHAVIOR
+
+When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+**CRITICAL RULE**: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
+
+### COMPLETION REPORT
+
+When the task is GENUINELY COMPLETE, generate a feature report in `.ralph/reports/`:
+
+```markdown
+# Feature Report: [Feature Name]
+
+## Summary
+- **Date**: YYYY-MM-DD HH:MM
+- **Duration**: X iterations
+- **Status**: COMPLETE
+
+## MCP Usage Statistics
+| Tool | Calls | Success | Failures |
+|------|-------|---------|----------|
+| validate_conventions | X | X | 0 |
+| check_migrations | X | X | 0 |
+| scaffold_extension | X | X | 0 |
+| context7 query-docs | X | X | 0 |
+
+## Files Created
+- path/to/file1.cs
+- path/to/file2.tsx
+
+## Files Modified
+- path/to/existing1.cs
+- path/to/existing2.ts
+
+## Validations Performed
+- [ ] SmartStack conventions validated
+- [ ] EF Core migrations checked
+- [ ] No conflicts detected
+
+## Notes
+Any relevant observations about the implementation.
+```
+
+### ERROR HANDLING
+
+If you encounter an error:
+1. Log the error details
+2. Attempt recovery if possible
+3. If MCP server fails mid-task:
+   - Save current progress
+   - Log the MCP failure
+   - DO NOT continue without MCP
+   - Request manual intervention
+
+### COMMANDS AVAILABLE
+
+- `/ralph-loop:cancel-ralph` - Cancel the current loop
+- `/ralph-loop:help` - Show Ralph Loop documentation
+
+---
 
-CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
+**NOW PROCEED WITH THE TASK**, ensuring you follow all MCP validation and logging requirements above.

package/templates/hooks/hooks.json

@@ -9,6 +9,15 @@
             "command": "bun ${CLAUDE_PLUGIN_ROOT}/claude-code-config/scripts/validate-command.js"
           }
         ]
+      },
+      {
+        "matcher": "mcp__*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_HOOKS_DIR}/ralph-mcp-logger.sh"
+          }
+        ]
       }
     ],
     "Stop": [
@@ -17,6 +26,10 @@
           {
             "type": "command",
             "command": "${CLAUDE_HOOKS_DIR}/stop-hook.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_HOOKS_DIR}/ralph-session-end.sh"
           }
         ]
       }

package/templates/hooks/ralph-mcp-logger.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Ralph MCP Logger Hook
+# Logs MCP tool calls to .ralph/logs/
+#
+# This hook is called by Claude Code before MCP tool invocations
+# when Ralph Loop is active.
+
+# Check if Ralph is active
+if [[ -z "$RALPH_STARTED" ]]; then
+  exit 0
+fi
+
+# Configuration
+RALPH_LOG_DIR=".ralph/logs"
+LOG_FILE="${RALPH_LOG_DIR}/ralph-$(date +%Y-%m-%d).log"
+
+# Ensure log directory exists
+mkdir -p "$RALPH_LOG_DIR"
+
+# Get tool info from environment (set by Claude Code)
+TOOL_NAME="${CLAUDE_TOOL_NAME:-unknown}"
+TOOL_PARAMS="${CLAUDE_TOOL_PARAMS:-}"
+
+# Timestamp
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+
+# Log the MCP call
+if [[ "$TOOL_NAME" == mcp__* ]]; then
+  echo "[$TIMESTAMP] [MCP] Tool: $TOOL_NAME" >> "$LOG_FILE"
+
+  # Extract MCP server name
+  if [[ "$TOOL_NAME" == mcp__smartstack__* ]]; then
+    echo "[$TIMESTAMP] [MCP]   Server: smartstack" >> "$LOG_FILE"
+  elif [[ "$TOOL_NAME" == mcp__plugin_context7* ]]; then
+    echo "[$TIMESTAMP] [MCP]   Server: context7" >> "$LOG_FILE"
+  fi
+
+  # Log params if not too long
+  if [[ ${#TOOL_PARAMS} -lt 500 ]]; then
+    echo "[$TIMESTAMP] [MCP]   Params: $TOOL_PARAMS" >> "$LOG_FILE"
+  else
+    echo "[$TIMESTAMP] [MCP]   Params: (truncated - ${#TOOL_PARAMS} chars)" >> "$LOG_FILE"
+  fi
+fi
+
+exit 0

package/templates/hooks/ralph-session-end.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Ralph Session End Hook
+# Generates a session summary when Ralph loop ends
+#
+# This hook is called when Claude Code session stops
+# and Ralph was active.
+
+# Check if Ralph was active
+if [[ -z "$RALPH_STARTED" ]] || [[ -z "$RALPH_SESSION_ID" ]]; then
+  exit 0
+fi
+
+# Configuration
+RALPH_DIR=".ralph"
+RALPH_LOG_DIR="${RALPH_DIR}/logs"
+RALPH_REPORTS_DIR="${RALPH_DIR}/reports"
+SESSION_LOG="${RALPH_LOG_DIR}/ralph-session-${RALPH_SESSION_ID}.log"
+
+# Ensure directories exist
+mkdir -p "$RALPH_REPORTS_DIR"
+
+# Get session info
+SESSION_END=$(date '+%Y-%m-%d %H:%M:%S')
+PROMPT="${RALPH_PROMPT:-Unknown task}"
+
+# Count MCP calls from log
+MCP_CALLS=0
+SMARTSTACK_CALLS=0
+CONTEXT7_CALLS=0
+
+if [[ -f "$SESSION_LOG" ]]; then
+  MCP_CALLS=$(grep -c '\[MCP\] Tool:' "$SESSION_LOG" 2>/dev/null || echo 0)
+  SMARTSTACK_CALLS=$(grep -c 'Server: smartstack' "$SESSION_LOG" 2>/dev/null || echo 0)
+  CONTEXT7_CALLS=$(grep -c 'Server: context7' "$SESSION_LOG" 2>/dev/null || echo 0)
+fi
+
+# Generate session report
+REPORT_FILE="${RALPH_REPORTS_DIR}/session-${RALPH_SESSION_ID}.md"
+
+cat > "$REPORT_FILE" << EOF
+# Ralph Session Report
+
+## Session Info
+- **Session ID**: ${RALPH_SESSION_ID}
+- **End Time**: ${SESSION_END}
+- **Task**: ${PROMPT}
+
+## MCP Usage Summary
+| Server | Calls |
+|--------|-------|
+| SmartStack | ${SMARTSTACK_CALLS} |
+| Context7 | ${CONTEXT7_CALLS} |
+| **Total** | **${MCP_CALLS}** |
+
+## Session Log
+See: \`${SESSION_LOG}\`
+
+---
+*Auto-generated by Ralph Weegund*
+EOF
+
+echo "[Ralph] Session report generated: $REPORT_FILE"
+
+# Log session end
+echo "" >> "$SESSION_LOG"
+echo "# Session ended: $SESSION_END" >> "$SESSION_LOG"
+echo "# MCP Calls: $MCP_CALLS (SmartStack: $SMARTSTACK_CALLS, Context7: $CONTEXT7_CALLS)" >> "$SESSION_LOG"
+
+exit 0

package/templates/ralph/README.md

@@ -0,0 +1,91 @@
+# Ralph Weegund - SmartStack Automation Loop
+
+Ralph Weegund is an iterative AI loop that enables autonomous feature development with mandatory MCP server integration.
+
+## Directory Structure
+
+```
+.ralph/
+├── ralph.config.yaml    # Configuration (DO NOT DELETE)
+├── logs/                # Execution logs
+│   └── ralph-YYYY-MM-DD.log
+├── reports/             # Feature completion reports
+│   └── feature-name-TIMESTAMP.md
+└── README.md            # This file
+```
+
+## Configuration
+
+Edit `ralph.config.yaml` to customize:
+
+- **MCP servers**: Required servers and behavior
+- **Logging**: What to log and retention
+- **Reports**: Auto-generation and format
+- **Iteration**: Max iterations and completion detection
+
+## Required MCP Servers
+
+Ralph **requires** these MCP servers to function:
+
+1. **context7** - Library documentation
+   ```bash
+   claude mcp add context7
+   ```
+
+2. **smartstack** - Validation and scaffolding
+   ```bash
+   claude mcp add smartstack
+   ```
+
+## Usage
+
+1. Ensure MCP servers are installed:
+   ```bash
+   smartstack check-mcp
+   ```
+
+2. Start Ralph:
+   ```bash
+   smartstack ralph start
+   ```
+
+3. In Claude Code, use:
+   ```
+   /ralph-loop "Your feature description"
+   ```
+
+## Logs
+
+Logs are stored in `.ralph/logs/` with daily rotation.
+
+View recent logs:
+```bash
+smartstack ralph logs
+```
+
+## Reports
+
+Feature completion reports are auto-generated in `.ralph/reports/`.
+
+View last report:
+```bash
+smartstack ralph report --last
+```
+
+## Troubleshooting
+
+### Ralph won't start
+
+1. Check MCP servers: `smartstack check-mcp`
+2. Run diagnostics: `smartstack doctor`
+3. Check logs: `smartstack ralph logs`
+
+### MCP server unavailable
+
+Ralph will abort if required MCP servers are unavailable.
+This is by design - no fallback mode exists.
+
+## More Information
+
+- Documentation: https://atlashub.ch/docs/ralph
+- Issues: https://github.com/atlashub/smartstack-cli/issues