openprompt-lang 0.10.1 → 1.0.0

package/bin/cli.js

@@ -2,33 +2,59 @@
 // @use(commander, kind, contract, limit)
 // @kind(util)
 // @contract(in: argv -> out: void, sideEffect: ejecuta CLI)
-// @limit(lines: 60)
-
-import { Command } from 'commander'
-import chalk from 'chalk'
-import { readFileSync } from 'fs'
-import { join, dirname } from 'path'
-import { fileURLToPath } from 'url'
-
-import { register as registerInit } from '../src/cli/commands-init.js'
-import { register as registerContext } from '../src/cli/commands-context.js'
-import { register as registerAi } from '../src/cli/commands-ai.js'
-import { register as registerLang } from '../src/cli/commands-lang.js'
-import { register as registerKnowledge } from '../src/cli/commands-knowledge.js'
-import { register as registerWork } from '../src/cli/commands-work.js'
-import { register as registerLearning } from '../src/cli/commands-learning.js'
-import { register as registerMisc } from '../src/cli/commands-misc.js'
+// @limit(lines: 90)
+
+import { Command } from "commander"
+import chalk from "chalk"
+import { readFileSync } from "fs"
+import { join, dirname } from "path"
+import { fileURLToPath } from "url"
+
+import { register as registerInit } from "../src/cli/commands-init.js"
+import { register as registerContext } from "../src/cli/commands-context.js"
+import { register as registerAi } from "../src/cli/commands-ai.js"
+import { register as registerLang } from "../src/cli/commands-lang.js"
+import { register as registerKnowledge } from "../src/cli/commands-knowledge.js"
+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 { 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'))
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"))
+
+// ──────────────────────────────────────────────
+// Si no hay argumentos o solo --help/-h, mostrar bienvenida OPL
+// ──────────────────────────────────────────────
+const args = process.argv.slice(2)
+const isHelpOnly = args.length === 1 && (args[0] === "--help" || args[0] === "-h")
+const hasNoArgs = args.length === 0
+
+if (hasNoArgs || isHelpOnly) {
+  const { showWelcome } = await import("../src/commands/opl-help.js")
+  await showWelcome()
+  process.exit(0)
+}
 
 const program = new Command()
 
+// Override: --help muestra la welcome screen, no la lista de Commander
+program.helpInformation = () => ""
+
 program
-  .name('openPrompt-Lang')
-  .description(chalk.cyan('Context Engine de anotaciones para desarrollo asistido por IA'))
+  .name("openPrompt-Lang")
+  .description(chalk.cyan("Context Engine de anotaciones para desarrollo asistido por IA"))
   .version(pkg.version)
 
+// Registrar comandos OPL (puerta de entrada: help, tutorial, index, read)
+registerOpl(program)
+
+// Registrar comandos existentes
 registerInit(program)
 registerContext(program)
 registerAi(program)
@@ -41,6 +67,12 @@ registerMisc(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/create.js

@@ -1,23 +1,23 @@
 #!/usr/bin/env node
 
-import { execSync } from 'child_process'
-import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync } from 'fs'
-import { join, dirname } from 'path'
-import { fileURLToPath } from 'url'
-import chalk from 'chalk'
+import { execSync } from "child_process"
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync } from "fs"
+import { join, dirname } from "path"
+import { fileURLToPath } from "url"
+import chalk from "chalk"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
-async function main () {
+async function main() {
   const args = process.argv.slice(2)
-  const projectName = args[0] || 'mi-app'
-  const depsIndex = args.indexOf('--deps')
-  const deps = depsIndex !== -1 ? args[depsIndex + 1]?.split(',') || [] : []
-  const deployIndex = args.indexOf('--deploy')
+  const projectName = args[0] || "mi-app"
+  const depsIndex = args.indexOf("--deps")
+  const deps = depsIndex !== -1 ? args[depsIndex + 1]?.split(",") || [] : []
+  const deployIndex = args.indexOf("--deploy")
   const deploy = deployIndex !== -1 ? args[deployIndex + 1] : null
-  const hasIonic = args.includes('--ionic')
-  const hasTauri = args.includes('--tauri')
-  const force = args.includes('--force')
+  const hasIonic = args.includes("--ionic")
+  const hasTauri = args.includes("--tauri")
+  const force = args.includes("--force")
 
   const projectDir = join(process.cwd(), projectName)
 
@@ -25,22 +25,22 @@ async function main () {
 
   // 1. Crear con Vite
   try {
-    console.log(chalk.blue('  [1/5] Creando base Vite + React + TS...'))
+    console.log(chalk.blue("  [1/5] Creando base Vite + React + TS..."))
     execSync(
-      `npx create-vite@latest ${projectName} --template react-ts ${force ? '--force' : ''}`,
+      `npx create-vite@latest ${projectName} --template react-ts ${force ? "--force" : ""}`,
       {
-        stdio: 'pipe',
-        cwd: process.cwd()
+        stdio: "pipe",
+        cwd: process.cwd(),
       }
     )
-    console.log(chalk.green('  ✅ Base Vite creada'))
+    console.log(chalk.green("  ✅ Base Vite creada"))
   } catch {
-    console.log(chalk.yellow('  ⚠️  Vite base ya existe o falló. Continuando...'))
+    console.log(chalk.yellow("  ⚠️  Vite base ya existe o falló. Continuando..."))
   }
 
   // 2. Limpiar boilerplate predecible
-  console.log(chalk.blue('  [2/5] Limpiando boilerplate innecesario...'))
-  const toDelete = ['src/App.css', 'src/assets', 'public/vite.svg']
+  console.log(chalk.blue("  [2/5] Limpiando boilerplate innecesario..."))
+  const toDelete = ["src/App.css", "src/assets", "public/vite.svg"]
   for (const file of toDelete) {
     const fullPath = join(projectDir, file)
     if (existsSync(fullPath)) {
@@ -54,34 +54,34 @@ async function main () {
 
 export default App
 `
-  writeFileSync(join(projectDir, 'src/App.tsx'), appContent, 'utf-8')
+  writeFileSync(join(projectDir, "src/App.tsx"), appContent, "utf-8")
 
   // 3. Instalar dependencias adicionales
   if (deps.length > 0) {
-    console.log(chalk.blue(`  [3/5] Instalando dependencias: ${deps.join(', ')}...`))
+    console.log(chalk.blue(`  [3/5] Instalando dependencias: ${deps.join(", ")}...`))
     try {
-      execSync(`npm install ${deps.join(' ')}`, { stdio: 'pipe', cwd: projectDir })
-      console.log(chalk.green('  ✅ Dependencias instaladas'))
+      execSync(`npm install ${deps.join(" ")}`, { stdio: "pipe", cwd: projectDir })
+      console.log(chalk.green("  ✅ Dependencias instaladas"))
     } catch {
       console.log(
-        chalk.yellow('  ⚠️  Error instalando dependencias. Continúa con npm install manual.')
+        chalk.yellow("  ⚠️  Error instalando dependencias. Continúa con npm install manual.")
       )
     }
   }
 
   // 4. Copiar scaffolds
-  console.log(chalk.blue('  [4/5] Copiando archivos de configuración...'))
-  const scaffoldsDir = join(__dirname, '..', 'scaffolds')
+  console.log(chalk.blue("  [4/5] Copiando archivos de configuración..."))
+  const scaffoldsDir = join(__dirname, "..", "scaffolds")
 
   const scaffoldFiles = [
-    ['tailwind.config.js', 'tailwind.config.js'],
-    ['prompt-lang.json', 'prompt-lang.json']
+    ["tailwind.config.js", "tailwind.config.js"],
+    ["prompt-lang.json", "prompt-lang.json"],
   ]
 
-  if (deploy === 'railway') scaffoldFiles.push(['railway.json', 'railway.json'])
-  if (deploy === 'netlify') scaffoldFiles.push(['netlify.toml', 'netlify.toml'])
-  if (hasIonic) scaffoldFiles.push(['capacitor.config.ts', 'capacitor.config.ts'])
-  if (hasTauri) scaffoldFiles.push(['tauri.conf.json', 'tauri.conf.json'])
+  if (deploy === "railway") scaffoldFiles.push(["railway.json", "railway.json"])
+  if (deploy === "netlify") scaffoldFiles.push(["netlify.toml", "netlify.toml"])
+  if (hasIonic) scaffoldFiles.push(["capacitor.config.ts", "capacitor.config.ts"])
+  if (hasTauri) scaffoldFiles.push(["tauri.conf.json", "tauri.conf.json"])
 
   for (const [src, dest] of scaffoldFiles) {
     const srcPath = join(scaffoldsDir, src)
@@ -93,43 +93,43 @@ export default App
   }
 
   // 5. Configurar package.json con scripts descriptivos
-  console.log(chalk.blue('  [5/5] Agregando scripts descriptivos...'))
-  const pkgPath = join(projectDir, 'package.json')
+  console.log(chalk.blue("  [5/5] Agregando scripts descriptivos..."))
+  const pkgPath = join(projectDir, "package.json")
   if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"))
     const descriptiveScripts = {
-      'dev:start': 'vite',
-      'dev:preview': 'vite preview',
-      'build:prod': 'vite build',
-      'build:analyze': 'vite build --analyze',
-      'lint:check': 'eslint src --ext .ts,.tsx',
-      'lint:fix': 'eslint src --ext .ts,.tsx --fix',
-      'type:check': 'tsc --noEmit',
-      'test:unit': 'vitest run',
-      'test:watch': 'vitest',
-      'test:coverage': 'vitest run --coverage',
-      'validate:all': 'npm run lint:check && npm run type:check && npm run test:unit'
+      "dev:start": "vite",
+      "dev:preview": "vite preview",
+      "build:prod": "vite build",
+      "build:analyze": "vite build --analyze",
+      "lint:check": "eslint src --ext .ts,.tsx",
+      "lint:fix": "eslint src --ext .ts,.tsx --fix",
+      "type:check": "tsc --noEmit",
+      "test:unit": "vitest run",
+      "test:watch": "vitest",
+      "test:coverage": "vitest run --coverage",
+      "validate:all": "npm run lint:check && npm run type:check && npm run test:unit",
     }
     pkg.scripts = { ...descriptiveScripts, ...pkg.scripts }
-    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)  }\n`, 'utf-8')
-    console.log(chalk.green('  ✅ Scripts descriptivos agregados'))
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8")
+    console.log(chalk.green("  ✅ Scripts descriptivos agregados"))
   }
 
   // Ionic plug
   if (hasIonic) {
-    console.log(chalk.blue('  🔌 Integrando Ionic...'))
+    console.log(chalk.blue("  🔌 Integrando Ionic..."))
     try {
-      execSync('npx cap init App com.app.app --web-dir=dist', { stdio: 'pipe', cwd: projectDir })
-      execSync('npx cap add android', { stdio: 'pipe', cwd: projectDir })
-      console.log(chalk.green('  ✅ Ionic/Capacitor configurado'))
+      execSync("npx cap init App com.app.app --web-dir=dist", { stdio: "pipe", cwd: projectDir })
+      execSync("npx cap add android", { stdio: "pipe", cwd: projectDir })
+      console.log(chalk.green("  ✅ Ionic/Capacitor configurado"))
     } catch {
-      console.log(chalk.yellow('  ⚠️  Error en setup Ionic. Configura manualmente.'))
+      console.log(chalk.yellow("  ⚠️  Error en setup Ionic. Configura manualmente."))
     }
   }
 
   console.log(chalk.cyan(`\n✅ ${projectName} listo!`))
   console.log(chalk.cyan(`   cd ${projectName}`))
-  console.log(chalk.cyan('   npm run dev:start\n'))
+  console.log(chalk.cyan("   npm run dev:start\n"))
 }
 
 main().catch(console.error)

package/bin/lint.js

@@ -1,23 +1,23 @@
 #!/usr/bin/env node
 
-import { readFileSync, existsSync } from 'fs'
-import { join } from 'path'
-import { lintFile } from '../src/utils/annotations.js'
-import chalk from 'chalk'
+import { readFileSync, existsSync } from "fs"
+import { join } from "path"
+import { lintFile } from "../src/utils/annotations.js"
+import chalk from "chalk"
 
-const targetFile = join(process.cwd(), process.argv[2] || '')
+const targetFile = join(process.cwd(), process.argv[2] || "")
 
 if (!targetFile || !existsSync(targetFile)) {
-  console.log(chalk.red('❌ Archivo no encontrado'))
-  console.log('Uso: node bin/lint.js <archivo>')
+  console.log(chalk.red("❌ Archivo no encontrado"))
+  console.log("Uso: node bin/lint.js <archivo>")
   process.exit(1)
 }
 
-const content = readFileSync(targetFile, 'utf-8')
+const content = readFileSync(targetFile, "utf-8")
 const { annotations, errors, warnings } = lintFile(content)
 
 if (annotations.length === 0) {
-  console.log(chalk.cyan('📭 Sin anotaciones PromptLang en este archivo'))
+  console.log(chalk.cyan("📭 Sin anotaciones PromptLang en este archivo"))
   process.exit(0)
 }
 
@@ -25,9 +25,9 @@ console.log(chalk.cyan(`\n🔍 Anotaciones encontradas: ${annotations.length}\n`
 
 for (const ann of annotations) {
   const argsStr = ann.args.length
-    ? ann.args.map((a) => (a.key ? `${a.key}: ${a.value}` : a.value)).join(', ')
-    : ''
-  console.log(`  @${ann.name}${argsStr ? `(${argsStr})` : ''}`)
+    ? ann.args.map((a) => (a.key ? `${a.key}: ${a.value}` : a.value)).join(", ")
+    : ""
+  console.log(`  @${ann.name}${argsStr ? `(${argsStr})` : ""}`)
 }
 
 if (errors.length > 0) {
@@ -45,5 +45,5 @@ if (warnings.length > 0) {
 }
 
 if (errors.length === 0 && warnings.length === 0) {
-  console.log(chalk.green('\n✅ Todas las anotaciones válidas\n'))
+  console.log(chalk.green("\n✅ Todas las anotaciones válidas\n"))
 }

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_CONTEXT.md

@@ -3,7 +3,7 @@
 ## 1. Resumen corto
 - Proyecto: openPrompt-Lang — context engine de anotaciones y templates para desarrollo asistido por IA
 - Objetivo: IA local especializada en desarrollo asistido con contexto reducido y pasos pequeños.
-- Versión: 0.8.0 (CLI), módulos de lenguaje v1.0.0–1.1.0
+- Versión: 0.10.1 (CLI), módulos de lenguaje v1.0.0–1.1.0
 
 ## 2. Stack técnico
 - Frontend: React 19 + TypeScript + Vite 7 + Tailwind v4
@@ -30,18 +30,36 @@ controller, service, route, middleware, model, repository, util, type, prisma, s
 Controller, Service, Repository, DTOs, Entity, GlobalExceptionHandler, FeignClient, KafkaConfig
 
 ## 4. Base de conocimiento
-- **10 dominios**: payments, mobile-pwa, systems, qa, frontend, backend, accessibility, algorithms, fundamentals, architecture
+- **13 dominios**: payments, mobile-pwa, systems, qa, frontend, backend, accessibility, algorithms, fundamentals, architecture, typescript, saas, restaurant
 - **13 playbooks**: flow-integration, capacitor-setup, rust-ownership, scrum-workflow, frontend-react, backend-nodejs, accessibility-wcag, algorithms-patterns, fundamentals-programs, spa-auth-flow, api-rest-design, db-schema-design, microservice-architecture
-- **33 fuentes** de conocimiento (libros/docs procesados)
+- **35 fuentes** de conocimiento (libros/docs + 2 proyectos reales extraídos)
+- **10 sistemas de conocimiento**: react-fullstack-app, sistema-pagos-chile, microservicios-spring, app-movil-offline, sistema-restaurant-pos, api-rest-robusta, accesibilidad-wcag-chile, typescript-avanzado, microservicios-multi-lenguaje, saas-pos-chileno
 
-## 5. Comandos clave
+## 5. Comandos OPL
 ```bash
-npx openPrompt-Lang validate          # Validar anotaciones
-npx openPrompt-Lang lang list         # Listar módulos
-npx openPrompt-Lang lang index react  # Ver templates de un módulo
-npx openPrompt-Lang teach <id>        # Aprender de un template
-npx openPrompt-Lang knowledge list     # Listar conocimiento
-npx openPrompt-Lang knowledge search   # Buscar en conocimiento
+# Navegación de conocimiento
+opl index [path]                    # Navegar por niveles
+opl read <dominio>/<id>             # Leer contenido (--chapter n --full)
+opl search <query>                  # Búsqueda híbrida (+ detecta sistema)
+opl system [name]                   # Explorar sistemas de conocimiento
+opl graph [concept]                 # Grafo de relaciones
+
+# Evaluación de proyectos
+opl assess [path]                   # PRA score 0-100
+opl assess --verbose                # 7 dimensiones × 28 criterios
+opl assess --save                   # Guardar reporte JSON
+
+# Configuración y sesiones
+opl init --knowledge                # Biblioteca personal ~/.opl/knowledge/
+opl session doc/close/diff          # Gestión de sesiones
+opl doc flow/framework              # Documentación (Mermaid, FRAMEWORK.md)
+opl upgrade                         # Migrar configuración
+
+# Templates y validación
+npx openPrompt-Lang validate        # Validar anotaciones
+npx openPrompt-Lang lang list       # Listar módulos
+npx openPrompt-Lang teach <id>      # Aprender de un template
+npx openPrompt-Lang qa-gen          # Generar tests de regresión
 ```
 
 ## 6. Referencia canónica