specleap-framework 2.1.0 → 2.1.5

package/openspec/cli/README.md

@@ -0,0 +1,189 @@
+# OpenSpec CLI — Spec-Driven Development
+
+CLI para implementar el workflow completo de SpecLeap.
+
+## Instalación
+
+```bash
+# Desde la raíz del proyecto
+export PATH="$PATH:$(pwd)/openspec/cli"
+
+# O crear symlink en /usr/local/bin
+ln -s $(pwd)/openspec/cli/openspec /usr/local/bin/openspec
+```
+
+## Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `openspec enrich` | Refinar user story con AI |
+| `openspec new` | Crear nueva propuesta de cambio |
+| `openspec ff` | Fast-forward: generar propuesta completa |
+| `openspec apply` | Implementar propuesta aprobada |
+| `openspec verify` | Verificar tests y specs |
+| `openspec code-review` | Solicitar review de CodeRabbit |
+| `openspec archive` | Archivar propuesta completada |
+| `openspec report` | Generar testing report |
+| `openspec status` | Ver estado de propuestas activas |
+
+**📖 Referencia completa:** Ver [COMMAND_REFERENCE.md](./COMMAND_REFERENCE.md) para documentación detallada de cada comando con todas las opciones, ejemplos, y exit codes.
+
+## Ciclo Completo de Desarrollo
+
+```bash
+# 1. Refinar user story
+openspec enrich "Como usuario quiero hacer login" --output us-refined.md
+
+# 2. Crear propuesta
+openspec new --auto "Implementar autenticación JWT" --from us-refined.md --ticket app-tienda-23
+
+# 3. (Opcional) Generar propuesta completa con AI
+openspec ff CHANGE-001
+
+# 4. Revisar y ajustar manualmente proposal.md, design.md, tasks.md
+
+# 5. Aplicar propuesta (crear branch, scaffolding)
+openspec apply CHANGE-001
+
+# 6. Implementar código (manual o con AI assistant)
+# ... usar Continue.dev, Copilot, Cursor según specs ...
+
+# 7. Verificar tests y specs
+openspec verify CHANGE-001
+
+# 8. Solicitar code review
+openspec code-review CHANGE-001 --create-pr
+
+# 9. (AI review automático por CodeRabbit)
+# ... revisar comentarios y aplicar cambios ...
+
+# 10. Archivar al completar
+openspec archive CHANGE-001
+```
+
+## Ejemplos de Uso
+
+### Crear propuesta rápida con AI
+
+```bash
+# Generar todo automáticamente
+openspec enrich "Sistema de notificaciones push" | \
+openspec new --auto --from - --ticket app-tienda-24
+openspec ff CHANGE-002
+openspec apply CHANGE-002
+```
+
+### Ver estado de propuestas
+
+```bash
+openspec status
+openspec status --all
+openspec status --state in_progress --format json
+```
+
+### Generar testing report
+
+```bash
+openspec report CHANGE-001
+openspec report --format json --output report.json
+```
+
+## Prerequisitos
+
+- **Git:** Para branch management
+- **AI CLI:** oracle, gh copilot, o ai-cli (para `/enrich` y `/ff`)
+- **GitHub CLI (gh):** Para crear PRs y verificar merges
+- **Test frameworks:** PHPUnit, Jest, etc. (según proyecto)
+
+## Configuración
+
+Edita `openspec/config.yaml` para personalizar:
+
+- Estados de specs y changes
+- Integración con ticket tracker (Asana recomendado en SpecLeap; el CLI es agnóstico al backend)
+- Umbrales de testing
+- Formato de IDs
+
+## Integración con AI Assistants
+
+Los scripts CLI están diseñados para trabajar con:
+
+- **Continue.dev:** Lee `.continue/rules/*.md` para seguir metodología
+- **Copilot:** Usa `codex.md`
+- **Cursor:** Sigue `.cursorrules`
+- **Cline:** Usa `.clinerules`
+- **Claude Code:** Sigue `AGENTS.md`
+
+Todos los AI assistants tienen acceso a las specs en `openspec/specs/` y las propuestas en `openspec/changes/`.
+
+## Testing Report Automation
+
+El comando `openspec report` detecta automáticamente:
+
+- **PHPUnit:** `phpunit.xml` o `phpunit.xml.dist`
+- **Jest:** `package.json` con jest configurado
+- **Otros:** Puedes extender `report.sh`
+
+## Code Review con CodeRabbit
+
+CodeRabbit se activa automáticamente en PRs si está configurado en el repo.
+
+Configuración en `.coderabbit.yaml`:
+
+```yaml
+language: es
+early_access: true
+enable_free_tier: true
+reviews:
+  profile: assertive
+  request_changes_workflow: true
+  high_level_summary: true
+  poem: false
+  collapse_walkthrough: false
+```
+
+## Troubleshooting
+
+### "Comando no encontrado: openspec"
+
+Asegúrate de que `openspec/cli` esté en tu `$PATH`:
+
+```bash
+export PATH="$PATH:$(pwd)/openspec/cli"
+```
+
+### "No se encontró CLI de AI"
+
+Instala uno de estos:
+
+- **oracle:** https://github.com/djmango/oracle
+- **gh copilot:** `gh extension install github/gh-copilot`
+- **ai-cli:** https://ai-cli.ai
+
+### "PHPUnit/Jest no encontrado"
+
+Instala las dependencias del proyecto:
+
+```bash
+# PHP
+composer install
+
+# Node
+npm install
+```
+
+## Contribuir
+
+Para añadir nuevos comandos o mejorar existentes:
+
+1. Crear `openspec/cli/mi-comando.sh`
+2. Seguir estructura de scripts existentes
+3. Usar funciones de `common.sh`
+4. Documentar en esta README
+
+## Referencias
+
+- Metodología: `../.continue/rules/01-sdd-methodology.md`
+- Templates: `../templates/`
+- Config: `../config.yaml`
+- Docs: `../README.md`

package/openspec/cli/apply.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# openspec apply — Implementar propuesta aprobada
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+source "$SCRIPT_DIR/common.sh"
+
+usage() {
+    cat <<EOF
+openspec apply — Implementar propuesta aprobada
+
+USAGE:
+    openspec apply <CHANGE-ID> [options]
+
+OPTIONS:
+    --no-branch         No crear branch de Git
+    --base <branch>     Branch base (default: develop)
+    --dry-run           Simular sin hacer cambios
+    -h, --help          Mostrar ayuda
+
+DESCRIPTION:
+    Implementa una propuesta aprobada:
+    1. Crea branch de Git (feat/CHANGE-ID-nombre)
+    2. Aplica delta specs (si existen)
+    3. Genera scaffolding según design.md
+    4. Actualiza estado a "in_progress"
+
+    NOTA: No genera código automáticamente.
+          Use AI assistant (Continue, Copilot) para implementar según specs.
+
+EXAMPLES:
+    openspec apply CHANGE-001
+    openspec apply CHANGE-002 --base main
+    openspec apply CHANGE-003 --dry-run
+
+PREREQUISITES:
+    - Propuesta completada y revisada
+    - Git repositorio inicializado
+    - Base branch existente
+
+EOF
+}
+
+# Parse arguments
+CHANGE_ID=""
+NO_BRANCH=false
+BASE_BRANCH="develop"
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        --no-branch)
+            NO_BRANCH=true
+            shift
+            ;;
+        --base)
+            BASE_BRANCH="$2"
+            shift 2
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        CHANGE-*)
+            CHANGE_ID="$1"
+            shift
+            ;;
+        *)
+            error "Argumento desconocido: $1"
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+# Validate
+validate_project
+
+if [[ -z "$CHANGE_ID" ]]; then
+    error "Debe proporcionar CHANGE-ID"
+    usage
+    exit 1
+fi
+
+# Find change directory
+CHANGE_DIR=$(find "$PROJECT_ROOT/openspec/changes" -maxdepth 1 -type d -name "${CHANGE_ID}-*" | head -n1)
+
+if [[ -z "$CHANGE_DIR" ]] || [[ ! -d "$CHANGE_DIR" ]]; then
+    error "Propuesta no encontrada: $CHANGE_ID"
+    exit 1
+fi
+
+CHANGE_NAME=$(basename "$CHANGE_DIR" | sed "s/^${CHANGE_ID}-//")
+
+info "Aplicando propuesta: $CHANGE_ID — $CHANGE_NAME"
+
+# Verify required files exist
+for file in proposal.md design.md tasks.md; do
+    if [[ ! -f "$CHANGE_DIR/$file" ]]; then
+        error "Archivo requerido no encontrado: $file"
+        exit 1
+    fi
+done
+
+# Check Git status
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    error "No estás en un repositorio Git"
+    exit 1
+fi
+
+if git_has_changes && [[ "$DRY_RUN" == false ]]; then
+    warning "Hay cambios sin commitear en el working directory"
+    read -p "¿Continuar de todos modos? (y/N) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        info "Operación cancelada"
+        exit 0
+    fi
+fi
+
+# Create feature branch
+if [[ "$NO_BRANCH" == false ]]; then
+    BRANCH_NAME="feat/${CHANGE_ID}-${CHANGE_NAME}"
+    
+    step "Creando branch: $BRANCH_NAME desde $BASE_BRANCH"
+    
+    if [[ "$DRY_RUN" == false ]]; then
+        # Check if base branch exists
+        if ! git show-ref --verify --quiet "refs/heads/$BASE_BRANCH"; then
+            error "Branch base no existe: $BASE_BRANCH"
+            exit 1
+        fi
+        
+        # Create and checkout new branch
+        git checkout -b "$BRANCH_NAME" "$BASE_BRANCH" || {
+            error "No se pudo crear branch. Puede que ya exista."
+            exit 1
+        }
+        success "Branch creado: $BRANCH_NAME"
+    else
+        info "[DRY RUN] Crearía branch: $BRANCH_NAME"
+    fi
+fi
+
+# Apply delta specs if they exist
+if [[ -d "$CHANGE_DIR/specs" ]] && [[ -n "$(ls -A "$CHANGE_DIR/specs" 2>/dev/null)" ]]; then
+    step "Aplicando delta specs..."
+    
+    for delta_spec in "$CHANGE_DIR/specs"/**/*.spec.md; do
+        if [[ -f "$delta_spec" ]]; then
+            # Extract relative path
+            rel_path="${delta_spec#$CHANGE_DIR/specs/}"
+            target_spec="$PROJECT_ROOT/openspec/specs/$rel_path"
+            
+            info "  Delta: $rel_path"
+            
+            if [[ "$DRY_RUN" == false ]]; then
+                # Create target directory if needed
+                target_dir=$(dirname "$target_spec")
+                ensure_dir "$target_dir"
+                
+                # Apply delta (simple: copy for now, later implement merge)
+                if [[ -f "$target_spec" ]]; then
+                    warning "    Spec existente será actualizada: $target_spec"
+                    # TODO: Implement proper delta merge
+                    cp "$delta_spec" "$target_spec"
+                else
+                    cp "$delta_spec" "$target_spec"
+                fi
+                success "    Aplicada: $target_spec"
+            else
+                info "[DRY RUN] Aplicaría delta a: $target_spec"
+            fi
+        fi
+    done
+else
+    info "No hay delta specs para aplicar"
+fi
+
+# Update proposal state
+step "Actualizando estado de propuesta a: in_progress"
+
+if [[ "$DRY_RUN" == false ]]; then
+    # Update state in proposal.md
+    sed -i.bak 's/Estado | draft/Estado | in_progress/' "$CHANGE_DIR/proposal.md"
+    sed -i.bak 's/Estado | review/Estado | in_progress/' "$CHANGE_DIR/proposal.md"
+    sed -i.bak 's/Estado | approved/Estado | in_progress/' "$CHANGE_DIR/proposal.md"
+    rm -f "$CHANGE_DIR/proposal.md.bak"
+    
+    # Commit the state change
+    git add "$CHANGE_DIR/proposal.md"
+    git commit -m "chore(openspec): iniciar implementación de $CHANGE_ID
+
+## Qué se hizo
+- Cambiar estado de propuesta a in_progress
+- Aplicar delta specs
+
+## Refs
+- Propuesta: openspec/changes/$CHANGE_ID-$CHANGE_NAME/
+" || true
+    
+    success "Estado actualizado"
+else
+    info "[DRY RUN] Actualizaría estado a: in_progress"
+fi
+
+# Show next steps
+success "Propuesta aplicada exitosamente"
+info ""
+info "Branch activo: $(git_current_branch)"
+info "Propuesta: $CHANGE_DIR"
+info ""
+info "Próximos pasos:"
+info "  1. Implementar según design.md y tasks.md"
+info "  2. Usar AI assistant (Continue, Copilot) con las specs"
+info "  3. Escribir tests según Testing Strategy"
+info "  4. openspec verify $CHANGE_ID (verificar tests)"
+info "  5. openspec code-review $CHANGE_ID (solicitar review)"
+info ""
+info "Archivos clave:"
+info "  - $(basename "$CHANGE_DIR")/design.md — Diseño técnico"
+info "  - $(basename "$CHANGE_DIR")/tasks.md — Tareas y criterios"
+info "  - openspec/specs/ — Especificaciones source of truth"

package/openspec/cli/archive.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# openspec archive — Archivar propuesta completada
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+source "$SCRIPT_DIR/common.sh"
+
+usage() {
+    cat <<EOF
+openspec archive — Archivar propuesta completada
+
+USAGE:
+    openspec archive <CHANGE-ID> [options]
+
+OPTIONS:
+    --keep-branch       No eliminar branch feature
+    --no-merge          No verificar merge (útil si ya mergeado manualmente)
+    -h, --help          Mostrar ayuda
+
+DESCRIPTION:
+    Archiva una propuesta completada y mergeada:
+    1. Verifica que PR esté mergeado
+    2. Actualiza estado a "completed"
+    3. Elimina branch feature (opcional)
+    4. Genera reporte final
+
+EXAMPLES:
+    openspec archive CHANGE-001
+    openspec archive CHANGE-002 --keep-branch
+    openspec archive CHANGE-003 --no-merge
+
+PREREQUISITES:
+    - PR mergeado a base branch
+    - Code review aprobado
+
+EOF
+}
+
+# Parse arguments
+CHANGE_ID=""
+KEEP_BRANCH=false
+NO_MERGE_CHECK=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        --keep-branch)
+            KEEP_BRANCH=true
+            shift
+            ;;
+        --no-merge)
+            NO_MERGE_CHECK=true
+            shift
+            ;;
+        CHANGE-*)
+            CHANGE_ID="$1"
+            shift
+            ;;
+        *)
+            error "Argumento desconocido: $1"
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+# Validate
+validate_project
+
+if [[ -z "$CHANGE_ID" ]]; then
+    error "Debe proporcionar CHANGE-ID"
+    usage
+    exit 1
+fi
+
+# Find change directory
+CHANGE_DIR=$(find "$PROJECT_ROOT/openspec/changes" -maxdepth 1 -type d -name "${CHANGE_ID}-*" | head -n1)
+
+if [[ -z "$CHANGE_DIR" ]] || [[ ! -d "$CHANGE_DIR" ]]; then
+    error "Propuesta no encontrada: $CHANGE_ID"
+    exit 1
+fi
+
+CHANGE_NAME=$(basename "$CHANGE_DIR" | sed "s/^${CHANGE_ID}-//")
+
+info "Archivando propuesta: $CHANGE_ID — $CHANGE_NAME"
+
+# Check if PR is merged (if gh is available)
+if [[ "$NO_MERGE_CHECK" == false ]] && command -v gh &> /dev/null; then
+    step "Verificando estado de PR..."
+    
+    # Find PR for this change
+    FEATURE_BRANCH="feat/${CHANGE_ID}-${CHANGE_NAME}"
+    PR_STATE=$(gh pr list --head "$FEATURE_BRANCH" --state all --json state --jq '.[0].state' 2>/dev/null || echo "")
+    
+    if [[ "$PR_STATE" != "MERGED" ]]; then
+        warning "PR no parece estar mergeado (estado: ${PR_STATE:-desconocido})"
+        read -p "¿Continuar de todos modos? (y/N) " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            info "Operación cancelada"
+            exit 0
+        fi
+    else
+        success "PR verificado como mergeado"
+    fi
+fi
+
+# Update proposal state
+step "Actualizando estado a: completed"
+
+sed -i.bak 's/Estado | .*/Estado | completed/' "$CHANGE_DIR/proposal.md"
+rm -f "$CHANGE_DIR/proposal.md.bak"
+
+# Add completion date
+COMPLETION_DATE=$(current_date)
+echo -e "\n## Completada\n- Fecha: $COMPLETION_DATE" >> "$CHANGE_DIR/proposal.md"
+
+# Update spec states if delta specs were applied
+if [[ -d "$CHANGE_DIR/specs" ]]; then
+    for delta_spec in "$CHANGE_DIR/specs"/**/*.spec.md; do
+        if [[ -f "$delta_spec" ]]; then
+            rel_path="${delta_spec#$CHANGE_DIR/specs/}"
+            target_spec="$PROJECT_ROOT/openspec/specs/$rel_path"
+            
+            if [[ -f "$target_spec" ]]; then
+                # Update state to implemented
+                sed -i.bak 's/Estado: draft/Estado: implemented/' "$target_spec"
+                sed -i.bak 's/Estado: review/Estado: implemented/' "$target_spec"
+                sed -i.bak 's/Estado: approved/Estado: implemented/' "$target_spec"
+                rm -f "$target_spec.bak"
+                
+                success "Spec marcada como implemented: $rel_path"
+            fi
+        fi
+    done
+fi
+
+# Commit archive changes
+git add "$CHANGE_DIR/proposal.md"
+if [[ -d "$PROJECT_ROOT/openspec/specs" ]]; then
+    git add "$PROJECT_ROOT/openspec/specs"
+fi
+
+git commit -m "chore(openspec): archivar $CHANGE_ID como completed
+
+## Qué se hizo
+- Marcar propuesta como completed
+- Actualizar specs a implemented
+
+## Refs
+- Propuesta: openspec/changes/$CHANGE_ID-$CHANGE_NAME/
+" || true
+
+success "Propuesta archivada"
+
+# Delete feature branch if requested
+if [[ "$KEEP_BRANCH" == false ]]; then
+    FEATURE_BRANCH="feat/${CHANGE_ID}-${CHANGE_NAME}"
+    
+    step "Eliminando branch feature: $FEATURE_BRANCH"
+    
+    # Switch to base branch first
+    BASE_BRANCH="develop"
+    if git show-ref --verify --quiet "refs/heads/$BASE_BRANCH"; then
+        git checkout "$BASE_BRANCH" || true
+    elif git show-ref --verify --quiet "refs/heads/main"; then
+        git checkout main || true
+    fi
+    
+    # Delete local branch
+    git branch -d "$FEATURE_BRANCH" 2>/dev/null || warning "Branch local no encontrado"
+    
+    # Delete remote branch
+    git push origin --delete "$FEATURE_BRANCH" 2>/dev/null || warning "Branch remoto no encontrado o ya eliminado"
+    
+    success "Branch eliminado"
+else
+    info "Branch feature conservado (--keep-branch)"
+fi
+
+# Generate final report
+step "Generando reporte final..."
+
+REPORT_FILE="$CHANGE_DIR/COMPLETION_REPORT.md"
+
+cat > "$REPORT_FILE" <<EOF
+# Reporte de Completación: $CHANGE_ID
+
+| Campo | Valor |
+|-------|-------|
+| ID | $CHANGE_ID |
+| Título | $CHANGE_NAME |
+| Completada | $COMPLETION_DATE |
+
+## Archivos Generados
+
+- proposal.md
+- design.md
+- tasks.md
+- $(find "$CHANGE_DIR/specs" -name "*.spec.md" 2>/dev/null | wc -l) delta specs
+
+## Specs Actualizadas
+
+$(if [[ -d "$CHANGE_DIR/specs" ]]; then
+    find "$CHANGE_DIR/specs" -name "*.spec.md" -exec basename {} \; 2>/dev/null | sed 's/^/- /'
+else
+    echo "Ninguna"
+fi)
+
+## Commits
+
+\`\`\`bash
+$(git log --oneline --grep="$CHANGE_ID" 2>/dev/null || echo "No commits found")
+\`\`\`
+
+## Estado Final
+
+✅ Propuesta completada y archivada
+✅ Specs actualizadas a "implemented"
+$(if [[ "$KEEP_BRANCH" == false ]]; then echo "✅ Branch feature eliminado"; else echo "⚠️ Branch feature conservado"; fi)
+
+---
+Generado: $(current_datetime)
+EOF
+
+success "Reporte generado: $REPORT_FILE"
+
+# Final message
+success "✅ $CHANGE_ID archivado exitosamente"
+info ""
+info "Reporte final: $REPORT_FILE"
+info ""
+info "La propuesta está completada y puede consultarse en:"
+info "  openspec/changes/$CHANGE_ID-$CHANGE_NAME/"