openprompt-lang 1.0.0 → 1.1.0

package/bin/cli.js

@@ -19,6 +19,8 @@ import { register as registerWork } from "../src/cli/commands-work.js"
 import { register as registerLearning } from "../src/cli/commands-learning.js"
 import { register as registerOpl } from "../src/cli/commands-opl.js"
 import { register as registerMisc } from "../src/cli/commands-misc.js"
+import { register as registerWorkflow } from "../src/cli/commands-workflow.js"
+import { register as registerTeach } from "../src/cli/commands-teach.js"
 
 import { handleUncaughtErrors, EXIT_CODES } from "../src/utils/errors.js"
 
@@ -63,12 +65,14 @@ registerKnowledge(program)
 registerWork(program)
 registerLearning(program)
 registerMisc(program)
+registerWorkflow(program)
+registerTeach(program)
 
 try {
   await program.parseAsync(process.argv)
 } catch (err) {
   if (err.exitCode !== undefined) {
-    console.error('\n' + err.userMessage + '\n')
+    console.error(`\n${err.userMessage}\n`)
     process.exitCode = err.exitCode
   } else {
     console.error(chalk.red(`\n✘ Error inesperado: ${err.message}\n`))

package/bin/mcp-plan.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// @use(kind, contract, limit)
+// @kind(util)
+// @contract(in: argv -> out: void, sideEffect: inicia servidor MCP modo plan)
+// @limit(lines: 20)
+
+import { startPlanServer } from "../src/mcp-plan-server.js"
+
+// MCP Plan Server — modo planificación
+// opencode lo ejecuta como segundo MCP para el wizard de stack/folder
+await startPlanServer()

package/bin/opl.js

@@ -8,18 +8,18 @@
 // Este archivo permite usar 'opl' como comando corto en vez de 'openPrompt-Lang'
 // Ej: opl validate, opl assess, opl search react
 
-import { fileURLToPath } from 'url'
-import { dirname, join } from 'path'
-import { execFileSync } from 'child_process'
+import { fileURLToPath } from "url"
+import { dirname, join } from "path"
+import { execFileSync } from "child_process"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const cliPath = join(__dirname, 'cli.js')
+const cliPath = join(__dirname, "cli.js")
 
 try {
   const result = execFileSync(process.execPath, [cliPath, ...process.argv.slice(2)], {
     cwd: process.cwd(),
-    stdio: 'inherit',
-    env: { ...process.env, OPL_ALIAS: '1' }
+    stdio: "inherit",
+    env: { ...process.env, OPL_ALIAS: "1" },
   })
   process.exitCode = result?.status ?? 0
 } catch (err) {

package/docs/AI-MANUAL.md

@@ -119,11 +119,17 @@ npx openPrompt-Lang suggest "ecommerce para vender ropa con dashboard admin"
 
 #### `validate` — Pipeline de validación
 ```bash
-npx openPrompt-Lang validate                          # Validar anotaciones
+npx openPrompt-Lang validate                          # Modo amigable (default)
 npx openPrompt-Lang validate --fix                    # Auto-corregir errores
+npx openPrompt-Lang validate --strict                 # Modo estricto
 ```
+
 Valida: estructura del proyecto, prompt-lang.json, AGENTS.md, anotaciones @kind/@contract/@limit en archivos.
 
+**Modo amigable (default):** `@limit(lines)` pendientes se muestran como *deuda documentada* (`📋` gris). No bloquean el pipeline. Solo errores reales (anotaciones inválidas, estructura faltante) causan fallo.
+
+**Modo estricto (`--strict`):** Toda advertencia incluyendo `@limit` se promueve a error. Útil para CI o cuando se quiere zero-debt.
+
 #### `qa-gen` — Generar tests desde errores aprendidos
 ```bash
 npx openPrompt-Lang qa-gen                           # Escanea + genera tests

package/docs/COMMANDS.md

@@ -51,11 +51,23 @@ npx openPrompt-Lang context [--output contexto.md] [--scope auth] [--no-ai]
 Ejecuta el pipeline de validación y verifica anotaciones PromptLang.
 
 ```bash
-npx openPrompt-Lang validate [--fix]
+npx openPrompt-Lang validate          # Modo amigable (default)
+npx openPrompt-Lang validate --fix    # Auto-corregir estructura
+npx openPrompt-Lang validate --strict # Modo estricto
 ```
 
+**Modo amigable (default):**
+- Los límites `@limit(lines)` por ajustar se muestran como **deuda documentada** (`📋` en gris)
+- Solo los errores reales (anotaciones inválidas, estructura faltante) elevan el exit code a fallo
+- La deuda se contabiliza pero no bloquea el pipeline
+
+**Modo estricto (`--strict`):**
+- Toda advertencia incluyendo `@limit` se promueve a error (`❌`)
+- Equivalente al comportamiento anterior de OPL
+
 **Opciones:**
 - `--fix` — Auto-corregir estructura del proyecto (crea src/, docs/, prompt-lang.json, AGENTS.md si faltan)
+- `--strict` — Promover deuda documentada a errores
 
 ---
 

package/docs/FRAMEWORK.md

@@ -213,6 +213,9 @@ npx openPrompt-Lang mcp
 | `search_templates` | Buscar templates por keyword | `query` (req), `lang?` |
 | `generate_tests` | Generar tests desde @learn-error | `sourceDir?`, `lang?`, `output?` |
 | `teach_template` | Lección + código de template | `templateId` (req), `lang?`, `showCode?` |
+| `analyze_blast_radius` | Análisis de impacto de cambios | `filePath` (req), `code` (req) |
+| `ast_patch_mutate` | Aplicar parche seguro al AST | `filePath` (req), `edits` (req) |
+| `execute_sandbox` | Validar cambios en aislamiento | `command` (req) |
 | `analyze_project` | Auditoría del proyecto | `dir?` |
 | `init_project` | Inicializar proyecto nuevo | `name?`, `dir?`, `stack?` |
 | `component_list` | Listar componentes disponibles | `lang?` |
@@ -244,6 +247,7 @@ npx openPrompt-Lang mcp
 - **SIEMPRE** revisar @scar vinculados en contratos abstractos antes de implementar
 - **SIEMPRE** declarar `@use()` al inicio de archivos anotados
 - **SIEMPRE** ejecutar `npx openPrompt-Lang validate` antes de cada commit
+- **TRIDENTE TÁCTICO**: Toda mutación de código debe seguir el ciclo `analyze_blast_radius` → `ast_patch_mutate` → `execute_sandbox`. NUNCA mutar a ciegas.
 - **PRA zero-tolerance**: F5, S2, S4
 - **Sistemas de conocimiento**: usar `opl system` antes de implementar features complejas
 - Preferir `export function Name() {}` sobre arrow functions para componentes

package/docs/MCP_AUTONOMY_PLAN.md

@@ -0,0 +1,78 @@
+# Plan de Autonomía MCP: De Generador Ciego a Copiloto de Ingeniería
+
+Este documento establece la arquitectura y el proceso de implementación para dotar al servidor MCP de openPrompt-Lang de herramientas de ejecución, validación estructural y mutación determinista.
+
+El objetivo central es eliminar la dependencia de validación manual, permitiendo a la IA ejecutar pruebas, medir impacto y corregir errores en milisegundos de forma autónoma, utilizando una **arquitectura basada en esquemas (JSON Schema)** y **adaptadores por dominio**.
+
+---
+
+## 1. Herramientas y Prioridad de Implementación
+
+La integración se realizará en capas, para asegurar que el sistema se mantiene modular y el núcleo agnóstico al lenguaje (Web, Unity, Backend).
+
+| Prioridad | Herramienta | Objetivo | Adaptador Web/Backend | Adaptador Unity |
+| :---: | :--- | :--- | :--- | :--- |
+| **1** | `execute_sandbox` | Ejecución aislada y captura de errores estructurada | CLI Node/Java, Docker | Unity Test CLI (Batch Mode) |
+| **2** | `analyze_blast_radius` | Análisis de impacto antes de mutar | Análisis de imports/AST | Rastreador de GUIDs/Prefabs |
+| **3** | `ast_patch_mutate` | Cambios quirúrgicos precisos sin reemplazar todo el archivo | `ts-morph`, Babel | Roslyn (C#) |
+| **4** | `inspect_component_render` | Traducción visual a jerarquía semántica (Accesibilidad) | DOM Testing Library | Parser de YAML/Prefabs |
+
+---
+
+## 2. Arquitectura de `execute_sandbox`
+
+Es la pieza central. Define un contrato estricto de entrada y salida, asegurando que el LLM reciba señales matemáticas y limpias (`exit_code`, `failed_tests`) en lugar de strings sueltos.
+
+### 2.1 Niveles de Seguridad (Dual-Tier)
+- **`local-fast`**: Ejecuta `child_process` directo en el host. Uso exclusivo para linters, análisis estático y comandos sin mutación o red. Provee feedback ultrarrápido (sin cold-start).
+- **`docker-ephemeral`**: Levanta contenedores desechables con volúmenes montados temporalmente. Uso para correr tests de integración, código generado (untrusted) y tareas que requieran manipulación de estado. Destrucción garantizada (`cleanup-always`).
+
+### 2.2 Esquema de Entrada (Input)
+```json
+{
+  "mode": "local-fast | docker-ephemeral",
+  "domain": "node | java | python | unity | generic",
+  "command": { "kind": "test | lint | build | run", "value": "npm test" },
+  "constraints": {
+    "timeoutMs": 120000,
+    "network": false,
+    "allowWrite": true
+  }
+}
+```
+
+### 2.3 Esquema de Salida (Output)
+La salida utiliza un `oneOf` con el discriminante `resultType` para evitar inferencias por parte de la IA.
+
+- **`success`**: Todo correcto, devuelve tiempos y telemetría.
+- **`test-failure`**: La infraestructura funcionó, pero la lógica falló. Devuelve aserciones fallidas, `stackTraceExtract` limpio de ruido de framework.
+- **`infra-failure`**: Falló Docker o el proceso.
+
+---
+
+## 3. Plan de Implementación (Fase B / Subfase Ejecución)
+
+### Paso 1: Definición Formal de Contratos
+- Crear `schemas/execute_sandbox.json`.
+- Integrar la validación mediante `AJV` en `core/engine/validator.js`. El contrato vive fuera de la lógica operativa.
+
+### Paso 2: Creación del Adaptador Base
+- Implementar `src/core/engine/sandbox.js`.
+- Configurar el enrutador MCP (`src/mcp-refactor/router.js`) para exponer la tool `execute_sandbox`.
+- Implementar la lógica para `local-fast` (usando `spawn` o `exec` con timeouts estrictos).
+
+### Paso 3: Integración de Docker Ephemeral
+- Configurar orquestación de Docker desde Node.js (`docker run --rm ...`).
+- Inyectar restricciones de red y volúmenes según el JSON de entrada.
+
+### Paso 4: Pruebas Unitarias y Telemetría
+- Validar captura de picos de memoria (`peakMemoryUsedMb`) y tiempos (`durationMs`).
+- Cerrar la integración verificando que no queden procesos zombies tras fallos.
+
+---
+
+## 4. Filosofía de Desarrollo
+
+- **Aislación:** Los esquemas deben ser la única fuente de verdad. El router no adivina intenciones.
+- **Transparencia:** Si un comando falla, la IA debe saber si falló el entorno (Docker no inicia) o el código (falla un Assert).
+- **Extensibilidad:** Para dar soporte a Unity en el futuro, no modificaremos `execute_sandbox`, simplemente crearemos el adaptador que lea el `domain: unity`.

package/docs/OPL_RESUMEN_GENERAL.md

@@ -0,0 +1,312 @@
+# openPrompt-Lang (OPL) — Resumen General
+
+> **Versión:** 1.0.0 · **Tipo:** Context Engine para Desarrollo Asistido por IA
+> **Propósito:** Hacer que la IA entienda tu código sin necesidad de explicárselo cada vez.
+
+---
+
+## ¿Qué es openPrompt-Lang?
+
+Es un **motor de contexto** para desarrollo de software asistido por IA. Su función es simple: le dices a la IA qué es cada archivo, qué hace, qué reglas sigue y qué errores ha tenido antes — y la IA lo recuerda automáticamente en futuras sesiones.
+
+Sin OPL, cada vez que trabajas con IA tienes que explicarle el contexto desde cero:
+- "Esto es un hook" → "Estas son sus props" → "Cuidado que aquí hay un bug conocido"
+
+Con OPL, esa información está **incrustada en el código mismo** mediante anotaciones, y la IA la lee automáticamente.
+
+---
+
+## ¿Qué problema resuelve?
+
+| Problema | Solución OPL |
+|----------|-------------|
+| La IA no sabe qué tipo de archivo está viendo | `@kind(component)` → lo clasifica |
+| La IA repite errores que ya corregiste | `@learn-error` + `recall` → lo recuerda |
+| No sabes si un patrón ya existe en el proyecto | `context_unified` + `search_templates` → lo encuentra |
+| Arrancar un proyecto nuevo es lento | `init` + `scaffold` → genera estructura en segundos |
+| Documentación desactualizada | `opl doc` → la genera automáticamente |
+| No sabes si tu código está listo para producción | `opl assess` → te da un score 0-100 |
+
+---
+
+## Arquitectura en 4 Capas (vista de caja negra)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│   ENTRADA (tú escribes)                                      │
+│   - Código con @anotaciones                                  │
+│   - Comandos CLI (validate, teach, search, etc.)             │
+│   - PDFs / documentación para ingestión                      │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    openPrompt-Lang ENGINE                     │
+│                                                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │
+│  │ CAPA 1   │  │ CAPA 2   │  │ CAPA 3   │  │ CAPA 4      │  │
+│  │Annotations│  │Knowledge │  │ Learning │  │Work Context │  │
+│  │Validación │  │Libros/   │  │Memoria   │  │Sesiones/    │  │
+│  │Linting    │  │Playbooks │  │semántica │  │métricas     │  │
+│  │Parseo     │  │Sistemas  │  │Recall    │  │Planes/tasks │  │
+│  └──────────┘  └──────────┘  └──────────┘  └─────────────┘  │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐    │
+│  │ MCP Server (Model Context Protocol)                   │    │
+│  │ Expone ~26 herramientas a IDEs (opencode, Cursor...)  │    │
+│  └──────────────────────────────────────────────────────┘    │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│   SALIDA (beneficios que obtienes)                           │
+│   - IA que entiende tu código sin explicación previa         │
+│   - Validación automática antes de commit                    │
+│   - Tests de regresión generados desde errores documentados  │
+│   - Score de production readiness (PRA)                      │
+│   - Templates reutilizables con buenas prácticas             │
+│   - Memoria del proyecto que persiste entre sesiones         │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Capacidades principales
+
+### 1. Anotaciones en código fuente
+
+Pones comentarios especiales en tu código y la IA los interpreta:
+
+```typescript
+// @use(kind, contract, limit)
+// @kind(component)
+// @props({ name: string, age?: number })
+// @limit(lines: 120)
+export function Greeting({ name, age }: Props) {
+  return <h1>Hola, {name}</h1>;
+}
+```
+
+Hay ~18 anotaciones disponibles: `@kind`, `@contract`, `@props`, `@limit`, `@deps`, `@compose`, `@pattern`, `@platform`, `@scope`, `@state`, `@forbidden`, `@test`, `@learn-error`, `@scar`, `@goodPractice`, `@badPractice`, `@teachMe`, `@meta`.
+
+**Validación:** `npx openprompt-lang validate` chequea que todas las anotaciones estén correctas antes de commit.
+
+### 2. Base de conocimiento (36 libros/pdfs)
+
+OPL ya incluye 36 fuentes procesadas en 13 dominios:
+
+| Dominio | Ejemplos |
+|---------|----------|
+| frontend | React, TypeScript, CSS, Vite |
+| backend | Node.js, Express |
+| payments | Stripe, Flow, Webpay (Chile) |
+| mobile-pwa | Capacitor, PWA |
+| accessibility | WCAG, ARIA |
+| algorithms | Algoritmos, estructuras de datos |
+| fundamentals | Git, SQL, programación |
+| architecture | Microservicios, REST, DB |
+| systems | Rust, ownership |
+| qa | Scrum, testing |
+
+Puedes **ingerir tus propios PDFs** con `opl knowledge ingest archivo.pdf` y se integran automáticamente.
+
+### 3. Memoria semántica (Learning)
+
+OPL aprende de tu proyecto con el tiempo:
+- Registra conceptos que usas (`modal`, `auth`, `checkout`)
+- Documenta errores para no repetirlos (`@learn-error`)
+- Recuerda decisiones arquitectónicas
+- Almacena vocabulario personal
+
+Comando clave: `opl recall "consulta"` — busca en toda la memoria del proyecto.
+
+### 4. Plantillas de código (Templates)
+
+OPL incluye **64 templates** listos para usar en 5 lenguajes:
+
+| Lenguaje | Templates | Ejemplos |
+|----------|-----------|----------|
+| React + TypeScript | 23 | button-shadcn, hook-useAuth, modal-dialog, datatable |
+| Vue 3 + Nuxt | 12 | composables, UI components |
+| Node.js + Express | 12 | controllers, services, middleware |
+| Spring Boot (Java) | 8 | Controllers, Services, Repositories |
+| OpenPrompt Core | 3 | Utilidades base |
+
+### 5. Generación de tests (QA)
+
+Cuando encuentras un bug, lo documentas con `@learn-error` y OPL genera **tests de regresión automáticos** (Vitest) para que ese bug no vuelva a ocurrir.
+
+```bash
+npx openprompt-lang qa-gen --lang react --source src/
+```
+
+### 6. Production Readiness Assessment (PRA)
+
+Evalúa tu proyecto en 7 dimensiones (28 criterios) y te da un score 0-100:
+
+| Rango | Significado |
+|-------|-------------|
+| 0-20 | 💀 Pre-Alfa |
+| 21-40 | 🔴 Alfa |
+| 41-60 | 🟡 Beta |
+| 61-80 | 🟢 RC |
+| 81-95 | 🔵 Prod-Ready |
+| 96-100 | 🟣 Hardened |
+
+```bash
+opl assess . --verbose
+```
+
+### 7. Sesiones de trabajo
+
+OPL rastrea sesiones completas: qué hiciste, cuánto duró, qué archivos cambiaste, qué errores corregiste. Al cerrar la sesión genera reportes automáticos.
+
+### 8. Sistema de tickets
+
+Gestión de bugs integrada (bugs del proyecto + bugs del framework OPL), vinculables con `@learn-error` para trazabilidad.
+
+### 9. MCP Server
+
+Expone 26 herramientas como servidor MCP para que IDEs como opencode, Cursor y VS Code puedan usar OPL directamente desde la interfaz de la IA.
+
+---
+
+## Cómo se usa — Comandos principales
+
+### Comandos esenciales (uso diario)
+
+```bash
+# Validar anotaciones antes de commit
+npx openprompt-lang validate
+
+# Ver salud del sistema
+npx openprompt-lang doctor
+
+# Buscar en la memoria del proyecto
+opl recall "algo que ya hicimos antes"
+
+# Iniciar sesión de trabajo
+npx openprompt-lang work-context start "Implementando login"
+```
+
+### Aprendizaje y consulta
+
+```bash
+# Buscar en los 36 libros
+opl search "autenticación react"
+
+# Leer un capítulo específico
+opl read frontend/react-aprendiz-maestro --chapter 5
+
+# Explorar sistemas de conocimiento
+opl system react-fullstack-app
+
+# Aprender un template
+npx openprompt-lang teach button-shadcn --lang react --code
+```
+
+### Ingesta de conocimiento propio
+
+```bash
+# Ingerir un PDF
+npx openprompt-lang knowledge ingest manual-api.pdf
+
+# Integrarlo a la memoria semántica
+npx openprompt-lang knowledge to-learning --pdf ID
+```
+
+### QA y validación
+
+```bash
+# Generar tests desde errores documentados
+npx openprompt-lang qa-gen --lang react
+
+# Evaluar readiness de producción
+opl assess . --verbose --save
+```
+
+### Gestión de errores
+
+```bash
+# Crear ticket
+npx openprompt-lang ticket create --title "Modal sin aria" --severity high
+
+# Cerrar y documentar fix
+npx openprompt-lang ticket close BUG-001 --fix "Agregado role=dialog"
+```
+
+### Inicialización de proyectos
+
+```bash
+# Proyecto nuevo
+npx openprompt-lang init --stack react,typescript,vite,tailwind --name mi-app
+
+# Proyecto existente
+npx openprompt-lang init --existing
+
+# Configuración interactiva
+npx openprompt-lang wizard
+```
+
+---
+
+## Flujo de trabajo típico
+
+```
+1. LEER
+   ├── doctor          → ¿está todo sano?
+   ├── recall          → ¿qué aprendí antes?
+   └── context_unified → ¿qué conocimiento aplica?
+
+2. PLANIFICAR
+   ├── work-context start "feature"
+   └── work-context plan new "nombre"
+
+3. IMPLEMENTAR
+   ├── teach template-id → aprender patrón existente
+   ├── ai-gen --description "..." → generar con IA
+   └── código + @annotations
+
+4. VALIDAR
+   ├── validate  → anotaciones correctas
+   ├── lint-file → debug detallado
+   └── qa-gen    → tests de regresión
+
+5. CERRAR
+   ├── ticket close BUG-XXX
+   ├── work-context learn
+   └── work-context close → métricas
+```
+
+---
+
+## Integraciones
+
+| Herramienta | Cómo se integra |
+|-------------|----------------|
+| **opencode** | MCP Server + skill dedicado |
+| **Cursor** | MCP Server |
+| **VS Code** | MCP Server + extensión dedicada |
+| **Git** | Hook pre-commit con validate automático |
+| **ESLint** | Pipeline auto-curativo (lint → fix → retry) |
+| **Ollama** | AI Provider local para generación |
+| **OpenAI / Anthropic** | AI Providers cloud |
+
+---
+
+## En resumen
+
+OPL es una **capa de metadata** entre tu código y la IA que:
+
+1. **Estructura** tu código con anotaciones semánticas
+2. **Alimenta** a la IA con contexto y conocimiento previo
+3. **Memoriza** errores y aprendizajes para no repetirlos
+4. **Valida** que todo esté correcto antes de commit
+5. **Evalúa** si tu proyecto está listo para producción
+6. **Automatiza** generación de tests, documentación y plantillas
+
+Todo desde la terminal o desde tu IDE. Sin bases de datos externas, sin servicios cloud obligatorios — funciona 100% offline.
+
+---
+
+*Documento generado desde el análisis del proyecto openPrompt-Lang v1.0.0*