specleap-framework 2.1.11 → 2.1.12

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.12] - 2026-04-30
+
+### Added
+
+- **`scripts/convert-docs.sh`** — wrapper sobre [Microsoft markitdown](https://github.com/microsoft/markitdown) para convertir PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, EPub, imágenes (OCR) y audio (transcripción) a Markdown que el framework pueda usar como contexto. markitdown es una **dependencia opcional** (no se incluye en el tarball npm, no se instala automáticamente): si no está presente, el script muestra el mensaje de instalación (`pip install markitdown` o `uv tool install markitdown`) y termina con exit 1 sin tocar ningún archivo. Bilingüe ES/EN según `SPECLEAP_LANG`.
+- Acepta tanto un archivo individual (`brief.pdf` → `brief.md`) como una carpeta entera (recursivo, max 3 niveles, filtra por extensiones soportadas).
+- Documentación en `README.md` (sección "Convertir documentos a Markdown") y `SETUP.md` (sección "Herramientas Opcionales") con caso de uso típico (briefs de cliente, user stories exportadas, reference docs).
+
+### Notes
+
+- Decisión de diseño: markitdown se queda como opcional para no imponer Python 3.10+ a usuarios que no lo necesiten. SpecLeap solo requiere bash + node + git + curl + jq como antes.
+- Caso de uso típico: cliente entrega brief en PDF → `bash scripts/convert-docs.sh brief.pdf` → `brief.md` → se referencia desde el cuestionario inicial. El AI gana contexto rico desde el primer comando.
+
 ## [2.1.11] - 2026-04-30
 
 ### Fixed

package/README.md

@@ -20,7 +20,7 @@
 
 SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo spec-first. Combina un contrato de proyecto inmutable, agentes conversacionales especializados, 34 Agent Skills profesionales y un pipeline de validación en tres capas para entregar código consistente y probado sin improvisación.
 
-**Versión actual:** 2.1.11 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
+**Versión actual:** 2.1.12 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
 
 ---
 
@@ -245,6 +245,41 @@ Ambos modos coexisten. Lo habitual es trabajar conversacionalmente en el día a
 
 ---
 
+## Convertir documentos a Markdown (opcional)
+
+Si tienes el brief de un cliente en PDF, user stories en Word, o specs antiguas en Excel, SpecLeap incluye un wrapper sobre [Microsoft markitdown](https://github.com/microsoft/markitdown) para convertirlos a Markdown que el framework pueda usar como contexto.
+
+**Instalación de markitdown** (dependencia opcional):
+
+```bash
+pip install markitdown
+# o, si usas uv:
+uv tool install markitdown
+```
+
+Requiere Python 3.10+. No es obligatorio: SpecLeap funciona perfectamente sin él. Solo lo necesitas si vas a alimentar archivos no-Markdown.
+
+**Uso:**
+
+```bash
+# Un archivo individual
+bash scripts/convert-docs.sh brief.pdf
+# → genera brief.md
+
+# Una carpeta entera (recursivo, max 3 niveles)
+bash scripts/convert-docs.sh ./briefings/
+# → convierte todos los pdf/docx/xlsx/pptx/html/csv/json/xml/epub que encuentre
+
+# Ayuda
+bash scripts/convert-docs.sh --help
+```
+
+Formatos soportados: **PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, EPub, imágenes (con OCR), audio (con transcripción)**.
+
+Si markitdown no está instalado, el script muestra un mensaje claro con las instrucciones de instalación y termina sin tocar nada.
+
+---
+
 ## Preguntas Frecuentes (FAQ)
 
 Las preguntas habituales están respondidas en archivos dedicados:

package/SETUP.md

@@ -254,6 +254,50 @@ El commit es rechazado. Corrige y vuelve a intentar.
 
 ---
 
+## 🔄 Herramientas Opcionales
+
+### markitdown — Convertir PDF/Word/Excel a Markdown
+
+Útil cuando un cliente te entrega el brief en PDF, las user stories en Word, o cualquier doc de referencia que quieras alimentar a SpecLeap como contexto. **No es obligatorio**: SpecLeap funciona sin él, sólo lo necesitas si trabajas con archivos no-Markdown.
+
+**Requisito previo:** Python 3.10 o superior.
+
+**Instalación:**
+
+```bash
+pip install markitdown
+# o, si prefieres uv:
+uv tool install markitdown
+```
+
+**Uso (vía wrapper de SpecLeap):**
+
+```bash
+# Un archivo
+bash scripts/convert-docs.sh ./brief-cliente.pdf
+
+# Una carpeta entera (max 3 niveles de profundidad)
+bash scripts/convert-docs.sh ./referencias/
+
+# Ayuda
+bash scripts/convert-docs.sh --help
+```
+
+**Formatos soportados:** PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), HTML, CSV, JSON, XML, EPub, imágenes (con OCR), audio (con transcripción).
+
+Si markitdown no está instalado, el script muestra el mensaje de instalación y termina con exit 1. No toca ningún archivo. Es seguro ejecutarlo aunque no lo tengas.
+
+**Caso típico de uso en SpecLeap:**
+
+1. Recibes el brief de un cliente en PDF.
+2. `bash scripts/convert-docs.sh ./brief.pdf` → genera `brief.md`.
+3. Lo pegas o referencias en el cuestionario al responder "¿Qué hace este proyecto?" / "¿Qué problema resuelve?".
+4. El AI tiene contexto rico desde el primer comando.
+
+Más info sobre markitdown: https://github.com/microsoft/markitdown
+
+---
+
 ## 📚 Documentación Completa
 
 ### Guías Detalladas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleap-framework",
-  "version": "2.1.11",
+  "version": "2.1.12",
   "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
   "keywords": [
     "spec-driven-development",

package/scripts/convert-docs.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# SpecLeap — Wrapper para convertir documentos a Markdown.
+#
+# Usa Microsoft markitdown (https://github.com/microsoft/markitdown) por
+# debajo. markitdown es una dependencia OPCIONAL: si no está instalada,
+# este script muestra cómo instalarla y termina sin tocar nada.
+#
+# Formatos soportados (por markitdown): PDF, Word (.docx), PowerPoint
+# (.pptx), Excel (.xlsx), HTML, imágenes (con OCR), audio (con
+# transcripción), CSV, JSON, XML, ZIP, EPub, YouTube URLs.
+#
+# Uso:
+#   bash scripts/convert-docs.sh <archivo-o-carpeta>
+#
+# Ejemplos:
+#   bash scripts/convert-docs.sh brief.pdf
+#   bash scripts/convert-docs.sh ./docs/
+#   bash scripts/convert-docs.sh user-stories.docx
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ─── Detectar idioma ──────────────────────────────────────────────────────
+SPECLEAP_LANG="${SPECLEAP_LANG:-}"
+
+if [ -z "$SPECLEAP_LANG" ] && [ -f "$SCRIPT_DIR/../.specleap/config.json" ]; then
+    SPECLEAP_LANG=$(grep -o '"language": "[^"]*"' "$SCRIPT_DIR/../.specleap/config.json" 2>/dev/null | cut -d'"' -f4 || true)
+fi
+SPECLEAP_LANG="${SPECLEAP_LANG:-es}"
+
+# ─── Mensajes bilingües ───────────────────────────────────────────────────
+if [ "$SPECLEAP_LANG" = "en" ]; then
+    MSG_USAGE="Usage: bash scripts/convert-docs.sh <file-or-directory>"
+    MSG_NOT_INSTALLED="markitdown is not installed."
+    MSG_INSTALL_TIP="Install with: pip install markitdown   (or: uv tool install markitdown)"
+    MSG_PYTHON_REQ="Requires Python 3.10 or higher."
+    MSG_DOCS="Docs: https://github.com/microsoft/markitdown"
+    MSG_CONVERTING="Converting"
+    MSG_DONE="Done"
+    MSG_NOT_FOUND="File or directory not found"
+    MSG_CONVERTED_TO="→"
+    MSG_NO_FILES="No convertible files found in"
+    MSG_SUMMARY="Summary"
+    MSG_FAIL="FAIL"
+    MSG_PROCESSING_DIR="Processing directory"
+    MSG_HELP_INTRO="Convert documents (PDF, Word, Excel, HTML, etc.) to Markdown using markitdown."
+    MSG_HELP_FORMATS="Supported formats: PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPub, images, audio."
+    MSG_HELP_EXAMPLES="Examples:"
+else
+    MSG_USAGE="Uso: bash scripts/convert-docs.sh <archivo-o-carpeta>"
+    MSG_NOT_INSTALLED="markitdown no está instalado."
+    MSG_INSTALL_TIP="Instala con: pip install markitdown   (o: uv tool install markitdown)"
+    MSG_PYTHON_REQ="Requiere Python 3.10 o superior."
+    MSG_DOCS="Docs: https://github.com/microsoft/markitdown"
+    MSG_CONVERTING="Convirtiendo"
+    MSG_DONE="Listo"
+    MSG_NOT_FOUND="Archivo o carpeta no encontrado"
+    MSG_CONVERTED_TO="→"
+    MSG_NO_FILES="No se encontraron archivos convertibles en"
+    MSG_SUMMARY="Resumen"
+    MSG_FAIL="FALLO"
+    MSG_PROCESSING_DIR="Procesando carpeta"
+    MSG_HELP_INTRO="Convierte documentos (PDF, Word, Excel, HTML, etc.) a Markdown usando markitdown."
+    MSG_HELP_FORMATS="Formatos soportados: PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPub, imágenes, audio."
+    MSG_HELP_EXAMPLES="Ejemplos:"
+fi
+
+# ─── Colores ──────────────────────────────────────────────────────────────
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[1;33m'
+    CYAN='\033[0;36m'
+    BOLD='\033[1m'
+    NC='\033[0m'
+else
+    RED=''; GREEN=''; YELLOW=''; CYAN=''; BOLD=''; NC=''
+fi
+
+# ─── Help ─────────────────────────────────────────────────────────────────
+show_help() {
+    echo "$MSG_HELP_INTRO"
+    echo ""
+    echo "$MSG_USAGE"
+    echo ""
+    echo "$MSG_HELP_FORMATS"
+    echo ""
+    echo "$MSG_HELP_EXAMPLES"
+    echo "  bash scripts/convert-docs.sh brief.pdf"
+    echo "  bash scripts/convert-docs.sh ./docs/"
+    echo "  bash scripts/convert-docs.sh user-stories.docx"
+    echo ""
+    echo "$MSG_DOCS"
+}
+
+if [ $# -lt 1 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+    show_help
+    exit 0
+fi
+
+# ─── Verificar markitdown instalado ───────────────────────────────────────
+if ! command -v markitdown >/dev/null 2>&1; then
+    echo -e "${RED}❌ $MSG_NOT_INSTALLED${NC}"
+    echo ""
+    echo -e "${YELLOW}💡 $MSG_INSTALL_TIP${NC}"
+    echo -e "   $MSG_PYTHON_REQ"
+    echo ""
+    echo -e "${CYAN}📖 $MSG_DOCS${NC}"
+    exit 1
+fi
+
+INPUT="$1"
+if [ ! -e "$INPUT" ]; then
+    echo -e "${RED}❌ $MSG_NOT_FOUND: $INPUT${NC}"
+    exit 1
+fi
+
+# ─── Conversión ────────────────────────────────────────────────────────────
+CONVERTED_OK=0
+CONVERTED_FAIL=0
+
+convert_one() {
+    local file="$1"
+    local base="${file%.*}"
+    local out="${base}.md"
+
+    echo -ne "  ${CYAN}→${NC} $MSG_CONVERTING $(basename "$file") ... "
+    if markitdown "$file" > "$out" 2>/dev/null; then
+        echo -e "${GREEN}✅${NC} $MSG_CONVERTED_TO $(basename "$out")"
+        CONVERTED_OK=$((CONVERTED_OK + 1))
+    else
+        echo -e "${RED}❌ $MSG_FAIL${NC}"
+        # No dejar archivo .md basura si falló
+        rm -f "$out"
+        CONVERTED_FAIL=$((CONVERTED_FAIL + 1))
+    fi
+}
+
+if [ -f "$INPUT" ]; then
+    convert_one "$INPUT"
+elif [ -d "$INPUT" ]; then
+    echo -e "${BOLD}📁 $MSG_PROCESSING_DIR: $INPUT${NC}"
+    echo ""
+
+    # Extensiones que markitdown soporta
+    EXTENSIONS=(pdf docx xlsx pptx html htm csv json xml epub rtf odt ods odp txt)
+    FOUND_ANY=0
+
+    for ext in "${EXTENSIONS[@]}"; do
+        while IFS= read -r -d '' file; do
+            convert_one "$file"
+            FOUND_ANY=1
+        done < <(find "$INPUT" -maxdepth 3 -type f -iname "*.${ext}" -print0 2>/dev/null)
+    done
+
+    if [ $FOUND_ANY -eq 0 ]; then
+        echo -e "${YELLOW}⚠️  $MSG_NO_FILES $INPUT${NC}"
+        echo "   (pdf, docx, xlsx, pptx, html, csv, json, xml, epub, ...)"
+        exit 0
+    fi
+fi
+
+echo ""
+echo -e "${GREEN}✅ $MSG_DONE${NC} — $MSG_SUMMARY: ${BOLD}$CONVERTED_OK${NC} OK, ${BOLD}$CONVERTED_FAIL${NC} $MSG_FAIL"