---
description: Verify version alignment between package.json and documentation
agent: action
model: haiku
---

# /check-version - Version Alignment Validator

Verifies that the version in `package.json` is aligned with all documentation files in `.documentation/`.

**USAGE:** Run before releases or as part of release process to ensure documentation is up-to-date.

**INTEGRATION:** Called automatically by `/gitflow:11-finish` for release branches.

---

## STEP 1: Read Package Version

**EXECUTE:**

```bash
# Get version from package.json
PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
echo "Package version: $PKG_VERSION"
```

---

## STEP 2: Scan Documentation Files

**EXECUTE:**

```bash
# Find all HTML files with version-badge
echo ""
echo "Scanning documentation files..."
echo ""

# Extract versions from all doc files
for file in .documentation/*.html; do
  if [ -f "$file" ]; then
    DOC_VERSION=$(grep -oP 'version-badge">v?\K[^<]+' "$file" | head -1)
    if [ -n "$DOC_VERSION" ]; then
      FILENAME=$(basename "$file")
      # Remove 'v' prefix if present for comparison
      DOC_VERSION_CLEAN=${DOC_VERSION#v}

      if [ "$DOC_VERSION_CLEAN" = "$PKG_VERSION" ]; then
        echo "OK $FILENAME: v$DOC_VERSION_CLEAN"
      else
        echo "MISMATCH $FILENAME: v$DOC_VERSION_CLEAN (expected v$PKG_VERSION)"
      fi
    fi
  fi
done
```

---

## STEP 3: Generate Report

**EXECUTE:**

```bash
echo ""
echo "====================================================================="
echo "                    VERSION ALIGNMENT CHECK"
echo "====================================================================="
echo ""

PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
MISMATCH_COUNT=0
TOTAL_COUNT=0

for file in .documentation/*.html; do
  if [ -f "$file" ]; then
    DOC_VERSION=$(grep -oP 'version-badge">v?\K[^<]+' "$file" | head -1)
    if [ -n "$DOC_VERSION" ]; then
      TOTAL_COUNT=$((TOTAL_COUNT + 1))
      DOC_VERSION_CLEAN=${DOC_VERSION#v}
      if [ "$DOC_VERSION_CLEAN" != "$PKG_VERSION" ]; then
        MISMATCH_COUNT=$((MISMATCH_COUNT + 1))
      fi
    fi
  fi
done

echo "Package version: v$PKG_VERSION"
echo "Documentation files checked: $TOTAL_COUNT"
echo "Mismatches found: $MISMATCH_COUNT"
echo ""

if [ "$MISMATCH_COUNT" -eq 0 ]; then
  echo "STATUS: PASSED - All versions aligned"
else
  echo "STATUS: FAILED - Version mismatches detected"
  echo ""
  echo "Run /check-version:fix to auto-update documentation"
fi
echo ""
echo "====================================================================="
```

---

## Conditional: If Mismatches Detected

**IF** `MISMATCH_COUNT > 0`:

Use `AskUserQuestion` tool to ask:

```json
{
  "questions": [{
    "question": "Des fichiers de documentation ont des versions obsoletes. Voulez-vous les mettre a jour automatiquement ?",
    "header": "Fix versions",
    "options": [
      {
        "label": "Oui, mettre a jour (Recommended)",
        "description": "Met a jour tous les fichiers avec la version actuelle"
      },
      {
        "label": "Non, ignorer",
        "description": "Continuer sans corriger les versions"
      }
    ],
    "multiSelect": false
  }]
}
```

**IF** user selects "Oui":
- Execute the fix command below

---

## /check-version:fix - Auto-Update Documentation Versions

**EXECUTE:**

```bash
PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)

echo "Updating documentation to v$PKG_VERSION..."
echo ""

UPDATED_COUNT=0

for file in .documentation/*.html; do
  if [ -f "$file" ]; then
    DOC_VERSION=$(grep -oP 'version-badge">v?\K[^<]+' "$file" | head -1)
    if [ -n "$DOC_VERSION" ]; then
      DOC_VERSION_CLEAN=${DOC_VERSION#v}
      if [ "$DOC_VERSION_CLEAN" != "$PKG_VERSION" ]; then
        # Update version in file
        sed -i "s/version-badge\">v[^<]*/version-badge\">v$PKG_VERSION/" "$file"
        UPDATED_COUNT=$((UPDATED_COUNT + 1))
        echo "UPDATED $(basename "$file"): v$DOC_VERSION_CLEAN -> v$PKG_VERSION"
      fi
    fi
  fi
done

echo ""
if [ "$UPDATED_COUNT" -gt 0 ]; then
  echo "OK $UPDATED_COUNT file(s) updated"
  echo ""
  echo "Files modified:"
  git status --porcelain .documentation/*.html | grep "^ M" | sed 's/^ M /  /'
  echo ""
  echo "Next steps:"
  echo "  1. Review changes: git diff .documentation/"
  echo "  2. Commit: /gitflow:commit"
else
  echo "OK No files needed updating"
fi
```

---

## /check-version:report - Detailed Report

**EXECUTE:**

```bash
PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)

echo "====================================================================="
echo "         VERSION ALIGNMENT DETAILED REPORT"
echo "====================================================================="
echo ""
echo "Package: @atlashub/smartstack-cli"
echo "Current version: v$PKG_VERSION"
echo ""
echo "---------------------------------------------------------------------"
echo "FILE                          | DOC VERSION | STATUS"
echo "---------------------------------------------------------------------"

for file in .documentation/*.html; do
  if [ -f "$file" ]; then
    DOC_VERSION=$(grep -oP 'version-badge">v?\K[^<]+' "$file" | head -1)
    if [ -n "$DOC_VERSION" ]; then
      FILENAME=$(basename "$file")
      DOC_VERSION_CLEAN=${DOC_VERSION#v}

      # Pad filename to 30 chars
      PADDED_NAME=$(printf "%-28s" "$FILENAME")

      if [ "$DOC_VERSION_CLEAN" = "$PKG_VERSION" ]; then
        printf "%s | v%-10s | OK\n" "$PADDED_NAME" "$DOC_VERSION_CLEAN"
      else
        printf "%s | v%-10s | MISMATCH\n" "$PADDED_NAME" "$DOC_VERSION_CLEAN"
      fi
    fi
  fi
done

echo "---------------------------------------------------------------------"
```

---

## Integration with GitFlow Release

This command is automatically called during `/gitflow:11-finish` for release branches.

**In release finish workflow:**

```bash
# Before creating tag, verify versions are aligned
if [[ "$TYPE" = "release" ]]; then
  /check-version

  # If mismatches, prompt to fix before continuing
  if [ "$MISMATCH_COUNT" -gt 0 ]; then
    echo "WARNING: Documentation versions not aligned"
    echo "Fix with: /check-version:fix"
    # Block release until fixed
  fi
fi
```

---

## Usage Examples

| Command | Description |
|---------|-------------|
| `/check-version` | Check version alignment (interactive) |
| `/check-version:fix` | Auto-update all doc files |
| `/check-version:report` | Detailed report without prompts |

---

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All versions aligned |
| 1 | Mismatches detected (blocking for releases) |

---

## Files Checked

- `.documentation/*.html` - All HTML documentation files
- Looks for `<span class="version-badge">vX.Y.Z</span>` pattern
