openprompt-lang 1.2.6 → 1.3.0

package/src/cli/commands-workflow.js

@@ -1,22 +1,30 @@
 // @use(commander, kind, contract, limit)
 // @kind(util)
 // @contract(in: program -> out: void, sideEffect: registra comandos workflow)
-// @limit(lines: 120)
+// @limit(lines: 200)
 
 /**
  * Registra los comandos de workflow OPL.
  *
  * Comandos:
- *   opl workflow discovery   → E.1 — Wizard de descubrimiento
- *   opl workflow specification → E.2 — Generación de documentos
- *   opl workflow delivery    → E.3 — Desarrollo por tickets
- *   opl workflow close       → E.4 — Cierre de sesión
+ *   opl workflow discovery      → E.1 — Wizard de descubrimiento
+ *   opl workflow specification  → E.2 — Generación de documentos
+ *   opl workflow delivery       → E.3 — Desarrollo por tickets
+ *   opl workflow close          → E.4 — Cierre de sesión
+ *   opl workflow select         → E.5 — Selector inteligente de workflow
+ *   opl epic                    → E.6 — Gestión de épicas
+ *   opl sprint                  → E.7 — Gestión de sprints
  */
 
 export function register(program) {
+  // ──────────────────────────────────────────────
+  // opl workflow — Gestión de proyectos
+  // ──────────────────────────────────────────────
   const workflow = program
     .command("workflow")
-    .description("Gestionar workflows de proyecto: discovery, specification, delivery, close")
+    .description(
+      "Gestionar workflows de proyecto: discovery, specification, delivery, close, select"
+    )
 
   workflow
     .command("discovery")
@@ -71,4 +79,115 @@ export function register(program) {
         reportDir: options.reports,
       })
     })
+
+  // ─── E.5 — Selector inteligente de workflow ─────────────────────────────
+  workflow
+    .command("select [description]")
+    .description("Seleccionar workflow óptimo según descripción de la tarea")
+    .option("--list", "Listar workflows disponibles")
+    .option("--strict", "Modo estricto: muestra gates requeridos")
+    .option("--json", "Salida en JSON")
+    .option("--status", "Mostrar reporte de estado del proyecto")
+    .action(async (description, options) => {
+      const { workflowSelect } = await import("../commands/workflow/select.js")
+      await workflowSelect(description, options)
+    })
+
+  // ──────────────────────────────────────────────
+  // opl epic — Gestión de épicas
+  // ──────────────────────────────────────────────
+  const epic = program
+    .command("epic")
+    .description("Gestionar épicas: agrupar tickets en features grandes")
+
+  epic
+    .command("create")
+    .description("Crear una nueva épica con tickets automáticos")
+    .option("--title <title>", "Título de la épica")
+    .option("--desc <desc>", "Descripción detallada (genera tickets automáticamente)")
+    .option("--domain <domain>", "Dominio asociado")
+    .option("--no-auto-tickets", "No generar tickets automáticamente")
+    .action(async (options) => {
+      const { epicCreate } = await import("../commands/workflow/epic-cli.js")
+      await epicCreate(options)
+    })
+
+  epic
+    .command("list")
+    .description("Listar todas las épicas")
+    .option("--status <status>", "Filtrar por estado: planning, active, done, cancelled")
+    .option("--domain <domain>", "Filtrar por dominio")
+    .action(async (options) => {
+      const { epicList } = await import("../commands/workflow/epic-cli.js")
+      await epicList(options)
+    })
+
+  epic
+    .command("show <epicId>")
+    .description("Mostrar detalle de una épica")
+    .action(async (epicId) => {
+      const { epicShow } = await import("../commands/workflow/epic-cli.js")
+      await epicShow(epicId)
+    })
+
+  epic
+    .command("close <epicId>")
+    .description("Cerrar una épica")
+    .option("--status <status>", "Estado final (default: done)", "done")
+    .action(async (epicId, options) => {
+      const { epicClose } = await import("../commands/workflow/epic-cli.js")
+      await epicClose(epicId, options)
+    })
+
+  epic
+    .command("status")
+    .description("Mostrar reporte de estado del proyecto basado en épicas y sprints")
+    .action(async () => {
+      const { epicStatus } = await import("../commands/workflow/epic-cli.js")
+      await epicStatus()
+    })
+
+  // ──────────────────────────────────────────────
+  // opl sprint — Gestión de sprints
+  // ──────────────────────────────────────────────
+  const sprint = program
+    .command("sprint")
+    .description("Gestionar sprints: planificar iteraciones de desarrollo")
+
+  sprint
+    .command("create <name>")
+    .description("Crear un nuevo sprint")
+    .requiredOption("--goal <goal>", "Objetivo del sprint")
+    .option("--duration <days>", "Duración en días (default: 14)")
+    .option("--start-date <date>", "Fecha de inicio (default: hoy)")
+    .action(async (name, options) => {
+      const { sprintCreate } = await import("../commands/workflow/sprint-cli.js")
+      await sprintCreate(name, options)
+    })
+
+  sprint
+    .command("list")
+    .description("Listar sprints")
+    .option("--status <status>", "Filtrar por estado: planning, active, completed")
+    .action(async (options) => {
+      const { sprintList } = await import("../commands/workflow/sprint-cli.js")
+      await sprintList(options)
+    })
+
+  sprint
+    .command("plan <sprintId>")
+    .description("Planificar sprint automáticamente desde épicas activas")
+    .option("--capacity <n>", "Capacidad en tickets (default: 10)")
+    .action(async (sprintId, options) => {
+      const { sprintPlan } = await import("../commands/workflow/sprint-cli.js")
+      await sprintPlan(sprintId, options)
+    })
+
+  sprint
+    .command("close <sprintId>")
+    .description("Cerrar un sprint")
+    .action(async (sprintId) => {
+      const { sprintClose } = await import("../commands/workflow/sprint-cli.js")
+      await sprintClose(sprintId)
+    })
 }

package/src/commands/init-core.js

@@ -14,8 +14,13 @@ export async function init(options) {
   const interactive = options.interactive !== false && !!process.stdin.isTTY
   const dryRun = options.dryRun || false
 
+  // Stack y extensiones (se actualizan si selectFullStack se ejecuta)
+  const finalStack = options.stack ? options.stack.split(",").map((s) => s.trim()) : []
+  const finalExtensions = []
+
   const cwd = process.cwd()
-  const isInitialized = existsSync(join(cwd, "prompt-lang.json")) || existsSync(join(cwd, ".openprompt"))
+  const isInitialized =
+    existsSync(join(cwd, "prompt-lang.json")) || existsSync(join(cwd, ".openprompt"))
 
   if (interactive && !options.existing && !options.name && !options.preset && !options.stack) {
     console.log(chalk.cyan("\n🧙 openPrompt-Lang — Inicialización\n"))
@@ -23,7 +28,10 @@ export async function init(options) {
     const choices = []
 
     if (isInitialized) {
-      choices.push({ name: chalk.yellow(" Actualizar/Reconstruir la integración (Rebuild)"), value: "rebuild" })
+      choices.push({
+        name: chalk.yellow(" Actualizar/Reconstruir la integración (Rebuild)"),
+        value: "rebuild",
+      })
       choices.push(new inquirer.Separator())
     }
 
@@ -41,7 +49,9 @@ export async function init(options) {
       {
         type: "list",
         name: "projectType",
-        message: isInitialized ? "Este proyecto ya tiene OPL. ¿Qué deseas hacer?" : "¿Qué tipo de proyecto?",
+        message: isInitialized
+          ? "Este proyecto ya tiene OPL. ¿Qué deseas hacer?"
+          : "¿Qué tipo de proyecto?",
         choices,
       },
     ])
@@ -134,22 +144,188 @@ export async function init(options) {
   // ── Verificar OpenCode ──
   await checkAndInstallOpencode(interactive)
 
+  // ── Generar ONBOARDING_WORKFLOW.md ──
+  if (!dryRun) {
+    try {
+      const onboardingPath = join(finalBaseDir, "docs", "ONBOARDING_WORKFLOW.md")
+      const onboardingContent = generateOnboardingMd(finalName, finalStack, finalExtensions)
+      if (!existsSync(join(finalBaseDir, "docs"))) {
+        mkdirSync(join(finalBaseDir, "docs"), { recursive: true })
+      }
+      writeFileSync(onboardingPath, onboardingContent, "utf-8")
+      console.log(chalk.green(`  ✅ docs/ONBOARDING_WORKFLOW.md — Guía para tu IA`))
+    } catch {
+      // No crítico si falla
+    }
+  }
+
   // ── Handoff a la IA ──
   console.log(chalk.cyan("\n✨ OPL Init: Estructura base lista."))
   console.log(chalk.yellow("OPL delega ahora la inicialización estratégica a tu Agente IA."))
-  console.log(chalk.white("Copia y pega el siguiente prompt en tu chat con la IA (ej. Cline, Cursor, OpenCode, etc.):\n"))
-  
-  console.log(chalk.bgGray.white(`
+  console.log(
+    chalk.white(
+      "Copia y pega el siguiente prompt en tu chat con la IA (ej. Cline, Cursor, OpenCode, etc.):\n"
+    )
+  )
+
+  const stackStr = finalStack ? finalStack.join(", ") : "por definir"
+  const extStr = finalExtensions?.length ? `\nExtensiones: ${finalExtensions.join(", ")}` : ""
+
+  console.log(
+    chalk.bgGray.white(`
 "Asume el rol de Arquitecto Principal OPL. Acabo de ejecutar opl init para un proyecto NUEVO llamado '${finalName}'.
+Stack base: ${stackStr}${extStr}
 
 Tu proceso obligatorio es:
 1. Ejecuta 'analyze_project' para inspeccionar el directorio base.
-2. Hazme preguntas para entender el contexto del proyecto (dominio, stack preferido, funcionalidades clave).
-3. Decide el stack óptimo con base en mis respuestas.
-4. Usa 'init_project' y 'scaffold_project' para configurar el proyecto.
-5. Genera los archivos canónicos: AGENTS.md, prompt-lang.json, .openprompt/FRAMEWORK.md.
-6. Confirma explícitamente que el proyecto quedó estabilizado e indícame el siguiente paso operativo."
-`))
+2. Lee el archivo 'docs/ONBOARDING_WORKFLOW.md' (recién generado).
+3. Hazme preguntas para entender el contexto del proyecto (dominio, stack preferido, funcionalidades clave).
+4. Decide el stack óptimo con base en mis respuestas.
+5. Usa 'init_project' y 'scaffold_project' para configurar el proyecto.
+6. Genera los archivos canónicos: AGENTS.md, prompt-lang.json, .openprompt/FRAMEWORK.md.
+7. Confirma explícitamente que el proyecto quedó estabilizado e indícame el siguiente paso operativo."
+`)
+  )
 
   return finalBaseDir
 }
+
+/**
+ * Genera el contenido de ONBOARDING_WORKFLOW.md para un proyecto nuevo.
+ *
+ * @param {string} projectName
+ * @param {string[]} stack
+ * @param {string[]} extensions
+ * @returns {string}
+ */
+function generateOnboardingMd(projectName, stack, extensions) {
+  const stackSection = stack?.length
+    ? stack.map((s) => `  - ${s}`).join("\n")
+    : "  - Por definir durante la inicialización"
+
+  const extSection = extensions?.length
+    ? extensions.map((e) => `  - ${e}`).join("\n")
+    : "  - (ninguna por ahora)"
+
+  return `# ONBOARDING WORKFLOW — ${projectName}
+
+Generado automáticamente por \`opl init\`.
+
+## 🎯 Propósito
+
+Este documento le indica a la IA qué pasos seguir al ser invocada en este proyecto por primera vez. Reduce la fricción de onboarding y asegura que la IA entienda el stack, la estructura y el workflow del proyecto.
+
+## 📋 Stack Detectado
+
+${stackSection}
+
+## 🔌 Extensiones
+
+${extSection}
+
+## 🏗️ Estructura del Proyecto
+
+\`\`\`
+.
+├── AGENTS.md                  → Contexto para IA (stack, convenciones, reglas)
+├── prompt-lang.json           → Configuración OPL
+├── docs/
+│   ├── AI_CONTEXT.md          → Contexto extendido
+│   ├── FRAMEWORK.md           → Referencia canónica del framework
+│   ├── ONBOARDING_WORKFLOW.md → Este archivo
+│   └── ...
+├── .openprompt/
+│   └── FRAMEWORK.md           → Manual completo de OPL
+├── .opencode/
+│   └── work-context/          → Sesiones, planes, logs
+└── src/
+    └── ...
+\`\`\`
+
+## 🔄 Workflow Obligatorio para la IA (v1.3.0)
+
+Siempre que se te pida trabajar en este proyecto, SIGUE ESTE FLUJO ESTRICTAMENTE.
+No hay excepciones. Los gates bloquean herramientas si se omiten pasos.
+
+### ⚠️ REGLAS INQUEBRANTABLES
+
+1. **workflow select primero**: Sin workflow seleccionado no hay implementación
+2. **ticket create antes de código**: Sin ticket abierto no se escribe código
+3. **docs_updated antes de cerrar**: Sin documentación no se cierra sesión
+
+### Flujo Completo (8 pasos, siempre en este orden)
+
+\`\`\`
+PASO 1 → workflow_select
+  "opl workflow select <descripción de la tarea>"
+  La IA describe qué necesita hacer, el sistema selecciona el workflow óptimo
+  (feature, bugfix, refactor, docs, research, etc.)
+
+PASO 2 → create_ticket
+  "opl ticket create --title ... --severity ..."
+  TODO cambio requiere ticket ANTES de tocar código
+
+PASO 3 → check_gates
+  Verificar: workflow_selected ✓, ticket_created ✓, plan_approved ✓
+
+PASO 4 → work_context_plan
+  Planificar implementación con búsqueda de conocimiento
+
+PASO 5 → implement
+  Anotaciones OPL primero (@kind → @contract → @limit → @deps)
+  Luego implementar lógica
+
+PASO 6 → validate
+  "opl validate" — verificar anotaciones antes de cerrar
+
+PASO 7 → docs_updated
+  Actualizar documentación. OBLIGATORIO antes de cerrar sesión.
+
+PASO 8 → work_context_close
+  Cerrar sesión y generar reporte con aprendizajes
+\`\`\`
+
+### Para features grandes: Épicas y Sprints
+
+\`\`\`
+# Crear épica (agrupa tickets automáticamente desde la descripción)
+opl epic create --title "Sistema de Reportes" --desc "Dashboard + exportación PDF + filtros"
+
+# Crear sprint con objetivo y duración
+opl sprint create "Sprint 1" --goal "Implementar core del sistema"
+
+# Planificar sprint automáticamente desde épicas activas
+opl sprint plan SPRINT-001 --capacity 10
+
+# Ver estado del proyecto
+opl epic status
+\`\`\`
+
+## ⚙️ Comandos Rápidos
+
+| Comando | Descripción |
+|---------|-------------|
+| \`opl workflow select <desc>\` | 🥇 Seleccionar workflow óptimo (USAR SIEMPRE PRIMERO) |
+| \`opl ticket create --title "..."\` | 🥇 Crear ticket (USAR SIEMPRE ANTES DE CÓDIGO) |
+| \`opl epic create --title "..." --desc "..."\` | Crear épica con tickets automáticos |
+| \`opl epic list\` | Listar épicas con progreso |
+| \`opl sprint create <name> --goal "..."\` | Crear sprint |
+| \`opl sprint plan <id> --capacity N\` | Planificar sprint automáticamente |
+| \`opl index\` | Navegar conocimiento |
+| \`opl search <q>\` | Buscar en conocimiento (--mode vector para semántica) |
+| \`opl read <d>/<id>\` | Leer documento |
+| \`opl system <name>\` | Explorar sistemas |
+| \`opl assess\` | Production Readiness Assessment |
+| \`opl embeddings status\` | Estado del índice vectorial |
+| \`opl knowledge ingest <file>\` | Ingestar PDF |
+| \`opl webscrape <url>\` | Extraer contenido web e indexar |
+
+## 📚 Documentación Vinculada
+
+- \`docs/AI_CONTEXT.md\` → Stack técnico y módulos
+- \`docs/FRAMEWORK.md\` → Especificación del framework
+- \`docs/EMBEDDINGS.md\` → Sistema de embeddings vectoriales
+- \`AGENTS.md\` → Contexto completo para IA
+- \`.openprompt/FRAMEWORK.md\` → Manual canónico de OPL
+`
+}

package/src/commands/init-existing.js

@@ -138,15 +138,20 @@ export async function initExisting(options = {}) {
   const interactive = options.interactive !== false && !!process.stdin.isTTY
   if (!rebuild) {
     console.log(chalk.cyan(`\n🔧 Inicializando OPL en proyecto existente: ${projectName}\n`))
-    
+
     // ── Verificar OpenCode ──
     await checkAndInstallOpencode(interactive)
 
     console.log(chalk.cyan("✨ OPL Init: Entorno detectado."))
     console.log(chalk.yellow("OPL delega ahora la inicialización estratégica a tu Agente IA."))
-    console.log(chalk.white("Copia y pega el siguiente prompt en tu chat con la IA (ej. Cline, Cursor, OpenCode, etc.):\n"))
-    
-    console.log(chalk.bgGray.white(`
+    console.log(
+      chalk.white(
+        "Copia y pega el siguiente prompt en tu chat con la IA (ej. Cline, Cursor, OpenCode, etc.):\n"
+      )
+    )
+
+    console.log(
+      chalk.bgGray.white(`
 "Asume el rol de Arquitecto Principal OPL. Acabo de ejecutar opl init para un proyecto EXISTENTE llamado '${projectName}'.
 
 Tu proceso obligatorio es:
@@ -155,7 +160,8 @@ Tu proceso obligatorio es:
 3. Genera la estructura que falte (docs/, work-context, AGENTS.md, prompt-lang.json, .openprompt/FRAMEWORK.md).
 4. Organiza un backlog inicial de refactorización con la deuda detectada.
 5. Confirma explícitamente que el proyecto quedó estabilizado e indícame el siguiente paso operativo."
-`))
+`)
+    )
     return cwd
   }
 
@@ -431,7 +437,8 @@ Tu proceso obligatorio es:
         {
           type: "confirm",
           name: "updateKnowledge",
-          message: "¿Deseas descargar/actualizar la biblioteca de conocimientos (Entorno Académico)?",
+          message:
+            "¿Deseas descargar/actualizar la biblioteca de conocimientos (Entorno Académico)?",
           default: false,
         },
       ])

package/src/commands/init-helpers.js

@@ -535,35 +535,41 @@ export async function selectFullStack(options) {
 }
 
 export async function checkAndInstallOpencode(interactive) {
-  if (!interactive) return;
+  if (!interactive) return
 
-  let isInstalled = false;
+  let isInstalled = false
   try {
-    execSync("opencode --version", { stdio: "ignore" });
-    isInstalled = true;
+    execSync("opencode --version", { stdio: "ignore" })
+    isInstalled = true
   } catch (e) {
-    isInstalled = false;
+    isInstalled = false
   }
 
   if (!isInstalled) {
-    console.log(chalk.yellow("\n⚠️  No se detectó 'opencode' instalado globalmente."));
-    console.log(chalk.gray("OpenCode es el agente CLI recomendado para aprovechar la integración MCP de OPL."));
+    console.log(chalk.yellow("\n⚠️  No se detectó 'opencode' instalado globalmente."))
+    console.log(
+      chalk.gray("OpenCode es el agente CLI recomendado para aprovechar la integración MCP de OPL.")
+    )
     const { install } = await inquirer.prompt([
       {
         type: "confirm",
         name: "install",
         message: "¿Deseas instalar opencode globalmente ahora? (npm install -g opencode)",
-        default: true
-      }
-    ]);
+        default: true,
+      },
+    ])
 
     if (install) {
-      console.log(chalk.cyan("⏳ Instalando opencode..."));
+      console.log(chalk.cyan("⏳ Instalando opencode..."))
       try {
-        execSync("npm install -g opencode", { stdio: "inherit" });
-        console.log(chalk.green("✅ opencode instalado exitosamente.\n"));
+        execSync("npm install -g opencode", { stdio: "inherit" })
+        console.log(chalk.green("✅ opencode instalado exitosamente.\n"))
       } catch (e) {
-        console.log(chalk.red("❌ Error instalando opencode. Puedes instalarlo manualmente con: npm install -g opencode\n"));
+        console.log(
+          chalk.red(
+            "❌ Error instalando opencode. Puedes instalarlo manualmente con: npm install -g opencode\n"
+          )
+        )
       }
     }
   }

package/src/commands/knowledge-ops.js

@@ -287,9 +287,61 @@ export async function ingest(filePath, options = {}) {
   rebuildIndex()
 
   console.log(chalk.cyan(`\n✅ PDF procesado: ${shortName}\n`))
+
+  // ── Auto-embedding hook (TICKET-007) ─────────────────────
+  if (options.embed !== false) {
+    await autoEmbedPdf(pdfId, entry, chapters)
+  }
 }
 
 export async function rebuild(_options = {}) {
   const count = rebuildIndex()
   console.log(chalk.cyan(`\n✅ Índice reconstruido: ${count.length} PDFs\n`))
 }
+
+/**
+ * Auto-embedding hook: después de ingestar un PDF, indexa sus embeddings.
+ *
+ * @param {string} pdfId - ID del PDF procesado
+ * @param {Object} entry - Metadatos del PDF
+ * @param {Array} chapters - Capítulos detectados
+ */
+async function autoEmbedPdf(pdfId, entry, chapters) {
+  try {
+    const { indexDocument } = await import("../embeddings/index-pipeline.js")
+
+    // Construir documento en formato OPL
+    const doc = {
+      id: pdfId,
+      title: entry.title || pdfId,
+      chapters: chapters.map((ch, i) => ({
+        index: ch.index ?? i,
+        title: ch.title || "",
+        content: ch.content || "",
+      })),
+    }
+
+    if (doc.chapters.length === 0) {
+      console.log(chalk.gray("  ⏭️   Sin capítulos para indexar (embedding omitido)."))
+      return
+    }
+
+    console.log(chalk.blue("  🧠 Indexando embeddings..."))
+
+    const result = await indexDocument(doc, { strategy: "section" })
+
+    if (result.success) {
+      console.log(
+        chalk.green(`  ✅ Embeddings: ${result.indexedChunks} chunks · ${result.durationMs}ms`)
+      )
+    } else {
+      console.log(
+        chalk.yellow(
+          `  ⚠️  Embedding parcial: ${result.indexedChunks}/${result.totalChunks} chunks`
+        )
+      )
+    }
+  } catch (error) {
+    console.log(chalk.gray(`  ⏭️   Embedding no disponible (${error.message})`))
+  }
+}