npm package: @luisito10/elitecore-cli
Description: EliteCore™ Feature Flags CLI Tool (ffctl)
Author: EliteCore Team
Latest version: 3.1.1

# @luisito10/elitecore-cli

🏭 **EliteCore™ Feature Flag Management CLI Toolkit**

Un CLI completo y robusto para gestionar feature flags, rollouts canary, despliegues por anillos y evaluación automatizada de riesgo usando ML.

## 🚀 Instalación

### Instalación Global (Recomendada)
```bash
npm install -g @luisito10/elitecore-cli
```

### Instalación Local en Proyecto
```bash
npm install --save-dev @luisito10/elitecore-cli
npx elitecore --help
```

### Verificar Instalación
```bash
elitecore --version
elitecore --help
```

## ⚙️ Configuración

### Variables de Entorno Requeridas

```bash
# URL del API de EliteCore (requerido)
export ELITECORE_API_URL="http://localhost:3005"

# Token JWT para autenticación (requerido)
export ELITECORE_API_KEY="your-jwt-token-here"

# Opcional: Timeout para requests en milisegundos
export ELITECORE_TIMEOUT="30000"
```

### Autenticación Interactiva

```bash
# Configurar credenciales paso a paso
elitecore login

# Configurar con parámetros directos
elitecore login --endpoint https://api.elitecore.com --key your-api-key
```

## 📋 Comandos Disponibles

### 🎯 **Gestión de Rollouts**

#### Canary Deployments
```bash
# Actualizar ratio canary al 25%
elitecore rollout canary rollout_001 --ratio 25

# Ejemplo de salida:
# 🚀 Actualizando canary ratio para rollout: rollout_001
# ✅ Canary ratio actualizado exitosamente
# 📊 Usuarios expuestos: 12,500 (25%)
```

#### Ring-Based Rollouts
```bash
# Configurar múltiples anillos de despliegue
elitecore rollout rings rollout_002 --rings '[
  {"name":"canary","percentage":5},
  {"name":"early-adopters","percentage":15},
  {"name":"general","percentage":80}
]'

# Ejemplo básico con 2 anillos
elitecore rollout rings rollout_002 --rings '[{"name":"ring1","percentage":10},{"name":"ring2","percentage":90}]'
```

#### Percentage-Based Rollouts
```bash
# Actualizar porcentaje de exposición
elitecore rollout percentage rollout_001 --percent 45

# Ejemplo de salida:
# 📊 Percentage actualizado a 45%
# 👥 Usuarios expuestos: 22,500 de 50,000
# 📈 Tasa de exposición: 45.0%
```

#### Control de Estado
```bash
# Pausar rollout con confirmación
elitecore rollout pause rollout_001

# Pausar sin confirmación (para scripts)
elitecore rollout pause rollout_001 --yes

# Reanudar rollout pausado
elitecore rollout resume rollout_001

# Reanudar sin confirmación
elitecore rollout resume rollout_001 --yes
```

### 🎯 **Gestión de Segmentos**

```bash
# Crear segmento interactivamente
elitecore segment create

# Crear con parámetros directos
elitecore segment create \
  --name "premium-users" \
  --rules '{"field":"plan","operator":"in","value":["premium","enterprise"]}'

# Reglas complejas con múltiples condiciones
elitecore segment create \
  --name "target-audience" \
  --rules '[
    {"field":"country","operator":"eq","value":"US"},
    {"field":"age","operator":"gte","value":18},
    {"field":"plan","operator":"ne","value":"free"}
  ]'
```

**Operadores de Segmentación Soportados:**
- `eq`: Igual a
- `ne`: No igual a  
- `gt`: Mayor que
- `gte`: Mayor o igual que
- `lt`: Menor que
- `lte`: Menor o igual que
- `in`: Está en la lista
- `not_in`: No está en la lista
- `contains`: Contiene (strings)
- `starts_with`: Comienza con
- `ends_with`: Termina con

### 🔍 **Evaluación de Riesgo**

```bash
# Análisis ML-powered de riesgo
elitecore risk assess rollout_001

# Ejemplo de salida:
# 🔍 Evaluando riesgo para rollout: rollout_001
# ✅ Evaluación completada
# 
# 🎯 Score de Riesgo: 34/100
# ████████░░░░░░░░░░░░ MEDIUM
# Confianza: 87%
# 
# 💡 Recomendaciones:
#   1. Monitorear error rates por 1 hora
#   2. Considerar reducir percentage si aumentan errores
```

### 📊 **Feature Flags (Comandos Existentes)**

```bash
# Listar todas las flags
elitecore list-flags

# Filtrar por ambiente y formato
elitecore list-flags --environment staging --format json

# Toggle de flags
elitecore toggle --flag new-ui --on --environment production

# Crear nueva flag
elitecore create --name new-feature --description "Nueva funcionalidad"
```

### ℹ️ **Información y Estado**

```bash
# Estado del CLI y configuración
elitecore status

# Usuario autenticado actual
elitecore whoami

# Ayuda general
elitecore --help

# Ayuda específica por comando
elitecore rollout --help
elitecore risk --help
elitecore segment --help
```

## 🔧 Casos de Uso Avanzado

### Rollout Progresivo Automatizado

```bash
#!/bin/bash
# Script de rollout progresivo con evaluación de riesgo

ROLLOUT_ID="rollout_001"
PERCENTAGES=(5 10 25 50 75 100)

for percent in "${PERCENTAGES[@]}"; do
  echo "📊 Actualizando a $percent%..."
  elitecore rollout percentage $ROLLOUT_ID --percent $percent
  
  # Esperar 10 minutos
  echo "⏳ Esperando 10 minutos..."
  sleep 600
  
  # Evaluar riesgo
  echo "🔍 Evaluando riesgo..."
  RISK=$(elitecore risk assess $ROLLOUT_ID --format json | jq -r '.riskLevel')
  
  if [ "$RISK" == "high" ] || [ "$RISK" == "critical" ]; then
    echo "⚠️ Riesgo alto detectado en $percent%, pausando rollout"
    elitecore rollout pause $ROLLOUT_ID --yes
    break
  fi
  
  echo "✅ Riesgo: $RISK - continuando..."
done
```

### Monitoreo Continuo con Alertas

```bash
#!/bin/bash
# Monitoreo de rollout con alertas automáticas

ROLLOUT_ID="rollout_001"

while true; do
  RISK=$(elitecore risk assess $ROLLOUT_ID --format json | jq -r '.riskLevel')
  
  case $RISK in
    "critical"|"high")
      echo "🚨 ALERTA: Riesgo $RISK detectado"
      elitecore rollout pause $ROLLOUT_ID --yes
      # Enviar notificación (Slack, email, etc.)
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"🚨 Rollout '$ROLLOUT_ID' pausado por riesgo: '$RISK'"}' \
        $SLACK_WEBHOOK_URL
      break
      ;;
    "medium")
      echo "⚠️ Riesgo medio - monitoreando..."
      ;;
    "low")
      echo "✅ Riesgo bajo - todo normal"
      ;;
  esac
  
  sleep 60  # Verificar cada minuto
done
```

### Integración con CI/CD (GitHub Actions)

```yaml
name: Deploy with EliteCore Rollout
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
          
      - name: Install EliteCore CLI
        run: npm install -g @luisito10/elitecore-cli
        
      - name: Deploy with Canary Strategy
        env:
          ELITECORE_API_URL: ${{ secrets.ELITECORE_API_URL }}
          ELITECORE_API_KEY: ${{ secrets.ELITECORE_API_KEY }}
        run: |
          # Crear rollout para el deploy
          ROLLOUT_ID="deploy-${{ github.sha }}"
          
          # Iniciar con 5% canary
          elitecore rollout canary $ROLLOUT_ID --ratio 5
          
          # Esperar 5 minutos y evaluar
          sleep 300
          RISK=$(elitecore risk assess $ROLLOUT_ID --format json | jq -r '.riskLevel')
          
          if [ "$RISK" == "low" ]; then
            echo "✅ Canary exitoso, promoviendo a 100%"
            elitecore rollout canary $ROLLOUT_ID --ratio 100
          else
            echo "❌ Canary falló, pausando deploy"
            elitecore rollout pause $ROLLOUT_ID --yes
            exit 1
          fi
```

## 🛠️ Desarrollo Local

### Setup para Contribuidores

```bash
# Clonar repositorio
git clone https://github.com/Luchito2023EG/elitecore-system.git
cd elitecore-system/packages/cli

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Ejecutar en modo desarrollo
npm run dev -- --help

# Ejecutar tests
npm test

# Linting
npm run lint

# Link para testing local
npm link
```

### Estructura del Proyecto

```
packages/cli/
├── src/
│   ├── commands/
│   │   ├── rollout/          # Comandos de rollout
│   │   │   ├── canary.ts     # Canary deployments
│   │   │   ├── rings.ts      # Ring-based rollouts
│   │   │   ├── percentage.ts # Percentage rollouts
│   │   │   ├── pause.ts      # Pausar rollout
│   │   │   └── resume.ts     # Reanudar rollout
│   │   ├── segment/
│   │   │   └── create.ts     # Crear segmentos
│   │   ├── risk/
│   │   │   └── assess.ts     # Evaluación de riesgo
│   │   └── ...               # Comandos existentes
│   ├── utils/
│   │   └── api.ts           # Cliente API
│   └── cli.ts               # Entry point
├── bin/elitecore            # Script ejecutable
├── dist/                    # Código compilado
└── package.json
```

## 🐛 Resolución de Problemas

### Errores Comunes

**Error: ELITECORE_API_KEY not set**
```bash
export ELITECORE_API_KEY="your-jwt-token-here"
```

**Error: Connection refused**
```bash
# Verificar que el API esté ejecutándose
curl http://localhost:3005/health

# O cambiar la URL del API
export ELITECORE_API_URL="https://api.elitecore.com"
```

**Error: Permission denied (Unix/Linux)**
```bash
chmod +x /usr/local/bin/elitecore
```

### Verificar Configuración

```bash
# Verificar variables de entorno
elitecore status

# Verificar conectividad
elitecore whoami

# Debug mode (verbose logging)
DEBUG=elitecore:* elitecore rollout canary rollout_001 --ratio 25
```

## 📈 Ejemplos por Escenario

### Escenario 1: Rollout Canary Simple
```bash
# 1. Iniciar con 5%
elitecore rollout canary rollout_001 --ratio 5

# 2. Monitorear por 30 minutos
watch -n 300 'elitecore risk assess rollout_001'

# 3. Si todo va bien, aumentar a 25%
elitecore rollout canary rollout_001 --ratio 25

# 4. Finalmente promover a 100%
elitecore rollout canary rollout_001 --ratio 100
```

### Escenario 2: Rollout por Anillos
```bash
# 1. Configurar anillos progresivos
elitecore rollout rings rollout_002 --rings '[
  {"name":"internal","percentage":2},
  {"name":"beta-users","percentage":8},
  {"name":"early-adopters","percentage":20},
  {"name":"general","percentage":70}
]'

# 2. Monitorear progresión automática
elitecore risk assess rollout_002
```

### Escenario 3: Segmentación de Usuarios
```bash
# 1. Crear segmento de usuarios premium
elitecore segment create \
  --name "premium-segment" \
  --rules '{"field":"subscription","operator":"in","value":["premium","enterprise"]}'

# 2. Usar en rollout dirigido
elitecore rollout create --segment premium-segment --percentage 50
```

## 📞 Soporte

- **Issues:** [GitHub Issues](https://github.com/Luchito2023EG/elitecore-system/issues)
- **Documentación:** [Docs Completa](https://docs.elitecore.com)
- **Email:** support@elitecore.com

## 📄 Licencia

MIT © EliteCore Team

---

**Desarrollado con ❤️ por el equipo EliteCore™**