openprompt-lang 0.11.0 → 1.1.0

package/bin/cli.js

@@ -19,6 +19,13 @@ 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"
+
+// Global error handler for uncaught exceptions
+handleUncaughtErrors()
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"))
@@ -58,10 +65,18 @@ registerKnowledge(program)
 registerWork(program)
 registerLearning(program)
 registerMisc(program)
+registerWorkflow(program)
+registerTeach(program)
 
 try {
   await program.parseAsync(process.argv)
 } catch (err) {
-  console.error(chalk.red(`✘ Error: ${err.message}`))
-  process.exitCode = 1
+  if (err.exitCode !== undefined) {
+    console.error(`\n${err.userMessage}\n`)
+    process.exitCode = err.exitCode
+  } else {
+    console.error(chalk.red(`\n✘ Error inesperado: ${err.message}\n`))
+    if (process.env.DEBUG) console.error(chalk.gray(err.stack))
+    process.exitCode = EXIT_CODES.GENERIC
+  }
 }

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// @use(kind, contract, limit)
+// @kind(util)
+// @contract(in: argv -> out: exitCode, sideEffect: delega a cli.js con los mismos argumentos)
+// @limit(lines: 30)
+
+// Shortcut: 'opl' → 'openPrompt-Lang'
+// 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"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+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" },
+  })
+  process.exitCode = result?.status ?? 0
+} catch (err) {
+  process.exitCode = err.status ?? 1
+}

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

@@ -6,6 +6,7 @@
 
 ---
 
+
 ## 1. Anotaciones Disponibles
 
 | Tag | Categoría | Descripción |
@@ -24,7 +25,7 @@
 | `@pattern()` | Arquitectura | Patrón de diseño (ver sección 5) |
 | `@test()` | Calidad | Metadata de tests: `@test(coverage: 80)` |
 | `@learn-error` | Calidad | Error aprendido: `@learn-error id=ID fix='...'` |
-| `@scar` | Calidad | Cicatriz de Guerra — error pasado evitable: `@scar(id: string, symptom: string, cause: string, fix: string, severity?: blocker|critical|warning|info, detect?: regex)` |
+| `@scar` | Calidad | Cicatriz de Guerra |
 | `@goodPractice()` | Documentación | Buena práctica |
 | `@badPractice()` | Documentación | Anti-patrón |
 | `@teachMe` | Documentación | Archivo es template de enseñanza |
@@ -95,21 +96,21 @@ Comandos disponibles desde `bin/cli.js` o `npm run opl` o `node bin/cli.js`:
 opl                              # Pantalla de bienvenida "puerta de entrada"
 opl help                         # Misma pantalla de bienvenida
 opl tutorial                     # Recorrido guiado interactivo (7 min)
-opl index [path]                 # Navegar conocimiento por niveles (general → dominio → documento → sistemas)
+opl index [path]                 # Navegar conocimiento por niveles
 opl read <dominio>/<id>          # Leer contenido específico (--chapter n --full)
-opl search <query>               # Búsqueda híbrida (tags + fulltext + semántica + detecta sistema)
-opl system [name]                # Explorar sistemas de conocimiento (capas, patrones, errores)
-opl graph [concept]              # Grafo de relaciones entre conceptos y documentos
-opl assess [path]                # Evaluar Production Readiness Assessment (PRA 0-100)
-opl assess --verbose             # Mostrar 7 dimensiones × 28 criterios detallados
-opl assess --save                # Guardar reporte JSON en el proyecto
-opl init --knowledge             # Configurar biblioteca personal ~/.opl/knowledge/
-opl session doc/close/diff       # Gestión de sesiones con documentación obligatoria
-opl doc flow/framework           # Generar documentación (Mermaid, FRAMEWORK.md)
-opl upgrade                      # Migrar configuración a versión actual
-opl contract list                # Listar contratos abstractos (IR)
+opl search <query>               # Búsqueda híbrida
+opl system [name]                # Explorar sistemas de conocimiento
+opl graph [concept]              # Grafo de relaciones
+opl assess [path]                # Evaluar PRA 0-100
+opl assess --verbose             # 7 dimensiones × 28 criterios
+opl assess --save                # Guardar reporte JSON
+opl init --knowledge             # Configurar biblioteca personal
+opl session doc/close/diff       # Gestión de sesiones
+opl doc flow/framework           # Generar documentación
+opl upgrade                      # Migrar configuración
+opl contract list                # Listar contratos abstractos
 opl contract show <id>           # Mostrar detalle de contrato
-opl contract search <query>      # Buscar contratos por nombre/tags
+opl contract search <query>      # Buscar contratos
 ```
 
 ## 8. Production Readiness Assessment (PRA)
@@ -212,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?` |
@@ -243,8 +247,8 @@ 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
-- **SIEMPRE** documentar errores en proyectos reales en `ERRORES-Y-HALLAZGOS.md` (sin modificar código)
-- **PRA zero-tolerance**: F5 (transacciones atómicas), S2 (deny-by-default), S4 (no hardcoded secrets)
+- **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
 - Preferir Named Exports sobre Default Exports
@@ -255,7 +259,7 @@ npx openPrompt-Lang mcp
 
 La IA dispone de **36 fuentes de conocimiento** organizadas en 13 dominios (incluyendo 2 proyectos reales extraídos).
 
-El conocimiento se agrupa en **sistemas** — conjuntos de fuentes que se necesitan juntas para construir algo real (app fullstack, pasarela de pagos, microservicios, POS, etc.).
+El conocimiento se agrupa en **sistemas** — conjuntos de fuentes que se necesitan juntas para construir algo real.
 Explorar: `opl system list` para ver los 10 sistemas disponibles.
 
 ### Dominios
@@ -337,8 +341,6 @@ Explorar: `opl system list` para ver los 10 sistemas disponibles.
 
 ### Sistemas de Conocimiento
 
-Sistemas agrupados por contexto de construcción (capas, patrones, errores comunes):
-
 | Sistema | Capas | Fuentes |
 |---------|-------|---------|
 | react-fullstack-app | frontend, backend, auth, db, deploy | 7+ |
@@ -352,8 +354,6 @@ Sistemas agrupados por contexto de construcción (capas, patrones, errores comun
 | microservicios-multi-lenguaje | gateway, java, node, python, monitor | 7+ |
 | saas-pos-chileno | saas, multitenant, pos, billing, compliance | 7+ |
 
-Explorar: `opl system [nombre]` — ver capas, patrones y errores documentados.
-
 ### Contratos Abstractos
 
 IR de componentes que separa **Contrato (esencia)** de **Sintaxis (framework)**:
@@ -372,7 +372,7 @@ Los contratos se almacenan en `knowledge-repo/abstract-contracts/` con schema en
 
 ### Cicatrices de Guerra (@scar)
 
-Anotación para **conocimiento negativo** — registrar lo que salió mal para que no se repita:
+Anotación para **conocimiento negativo**:
 
 ```typescript
 // @scar(
@@ -387,8 +387,6 @@ Anotación para **conocimiento negativo** — registrar lo que salió mal para q
 
 Campos: `id` (req), `symptom` (req), `cause` (req), `fix` (req), `detect` (opcional, regex), `severity` (opcional).
 
-Integración PRA: @scar con severity=blocker penaliza el score de calidad. @scar no resueltos reducen F3.
-
 ### Pipeline Auto-curativo
 
 El paso [4/5] de validate ejecuta un loop de auto-corrección:
@@ -438,55 +436,9 @@ knowledge_concept → { bookId, conceptSlug? }
 ## 14. Stack del Proyecto
 
 - **Lenguaje:** node
-- **Stack:** node, javascript, esm, commander
+- **Stack base:** node, javascript, esm, commander
 - **Extensiones:** vitest, eslint, inquirer, chalk, pdf-parse
 - **Perfil:** senior
-
-## 15. Flujo de Trabajo Recomendado
-
-### Para desarrollo con MCP (ahorra tiempo)
-
-```
-analyze_project → context_unified → knowledge_search/recall → work_context_plan → work_context_start → implementar → validate → work_context_close
-```
-
-1. **analyze_project** — Auditoría inicial del proyecto (30s, ahorra ~15min)
-2. **context_unified** — Búsqueda cruzada en 7 fuentes (10s, ahorra ~20min)
-3. **knowledge_search** o **recall** — Buscar antes de crear (10s, ahorra ~30min)
-4. **work_context_plan** — Planificar antes de implementar (1min, ahorra ~1hr)
-5. **work_context_start** — Iniciar sesión con tracking
-6. **implementar** — Escribir código siguiendo anotaciones
-7. **validate** — Verificar anotaciones antes de commit
-8. **work_context_close** — Cerrar sesión y registrar métricas
-
-### Para evaluación de producción (PRA)
-
-```
-opl assess --verbose  →  opl assess --save  →  revisar PRA-ASSESSMENT.json
-```
-
-1. **opl assess --verbose** — Ver 7 dimensiones × 28 criterios
-2. **opl assess --save** — Guardar reporte JSON en el proyecto
-3. **Revisar zero-tolerance** — F5, S2, S4 deben estar en verde
-4. **Priorizar mejoras** — Empezar por dimensiones con menor score
-
-### Para QA completo (workflow integrado)
-
-```
-opl assess --save && npx openPrompt-Lang validate && recall "errores"
-```
-
-### Para validación de anotaciones
-
-```
-validate → lint_file → qa-gen → validate
-```
-
-1. **validate** — Verificar anotaciones antes de cambios
-2. **lint_file** — Lint detallado del archivo modificado
-3. **qa-gen** — Generar tests desde errores aprendidos
-4. **validate** — Validación final antes de commit
-
----
-
-*Generado automáticamente por openPrompt-Lang v0.10.1 — 2026-05-21*
+- **Modo oscuro:** por defecto
+- **Testing:** Vitest
+- **Linting:** ESLint + Prettier

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`.