@icarusmx/creta 1.5.15 → 1.5.17

package/bin/creta.js

@@ -10,7 +10,7 @@ import { PullRequestTutorial } from '../lib/pr-tutorial.js'
 import { VimSetupTutorial } from '../lib/vim-setup-tutorial.js'
 import { AWSGuideViewer } from '../lib/aws-guide-viewer.js'
 import { CommandHelpExecutor } from '../lib/executors/CommandHelpExecutor.js'
-import { readExercise, listExercises } from '../lib/readers/exercise-reader.js'
+import { readExercise, listExercises, syncBiblioteca } from '../lib/readers/exercise-reader.js'
 import { PapersExecutor } from '../lib/papers/PapersExecutor.js'
 import { ExercisesExecutor } from '../lib/executors/ExercisesExecutor.js'
 import { executeSintaxis } from '../lib/executors/sintaxis-executor.js'
@@ -193,6 +193,9 @@ if (command.startsWith('portafolio')) {
 } else if (command === 'exercises' || command === 'ejercicios') {
   // List all exercises
   await listExercises()
+} else if (command === 'biblioteca') {
+  // Sync exercises to ~/.creta/biblioteca
+  await syncBiblioteca()
 } else if (command === 'help' || command === 'ayuda') {
   // Show available commands
   showHelp()
@@ -708,6 +711,7 @@ function showHelp() {
   console.log("  creta code           - Sesión interactiva de programación con IA\n")
 
   console.log("🔧 Utilidades:")
+  console.log("  creta biblioteca     - Sincroniza ejercicios a ~/.creta/biblioteca/")
   console.log("  creta reset          - Reinicia tu progreso (elimina ~/.creta/user.json)")
   console.log("  creta privacy        - Explica qué datos guarda Creta y dónde\n")
 

package/lib/data/command-help/curl.js

@@ -1,80 +1,270 @@
 export const curl = {
   command: 'curl',
-  description: 'Realiza peticiones HTTP desde la terminal - tu herramienta para APIs',
+  description: 'Realiza peticiones HTTP desde la terminal - para APIs y descargar scripts',
   usage: 'curl [opciones] [URL]',
+
+  learningPath: {
+    intro: 'curl tiene dos usos principales: trabajar con APIs y descargar scripts',
+    progression: [
+      'Primero: Aprende cada flag individual (-L, -s, -f, -S)',
+      'Segundo: Combínalos para formar -fsSL',
+      'Tercero: Úsalo en instalaciones reales (curl -fsSL url | bash)',
+      'Cuarto: Aplícalo a APIs REST (-X, -H, -d)'
+    ],
+    goal: 'Dominar -fsSL te hace ver profesional. Lo verás en toda instalación de herramientas.'
+  },
+
   commonOptions: [
     {
-      flag: '-X',
-      description: 'Especifica el método HTTP (GET, POST, PUT, DELETE)'
+      flag: '-L',
+      description: 'Sigue redirects automáticamente',
+      why: 'Las URLs pueden redirigir. Sin -L, curl se detiene en la primera respuesta',
+      example: 'curl -L https://bit.ly/ejemplo',
+      level: 1
     },
     {
-      flag: '-H',
-      description: 'Agrega un header a la petición'
+      flag: '-s',
+      description: 'Modo silencioso - oculta la barra de progreso',
+      why: 'El progreso es ruido visual cuando haces piping o scripts',
+      example: 'curl -s https://api.ejemplo.com | jq',
+      level: 2
     },
     {
-      flag: '-d',
-      description: 'Envía datos en el body (JSON, form data, etc.)'
+      flag: '-f',
+      description: 'Falla visiblemente en errores HTTP (400+, 500+)',
+      why: 'Sin esto, curl devuelve el HTML de error como si fuera éxito',
+      example: 'curl -f https://api.ejemplo.com/404',
+      level: 3
     },
     {
-      flag: '-i',
-      description: 'Incluye los headers de respuesta en el output'
+      flag: '-S',
+      description: 'Muestra errores incluso en modo silencioso',
+      why: 'Para combinar con -s: silencioso pero con errores visibles',
+      example: 'curl -sS https://api.ejemplo.com',
+      level: 4
     },
     {
-      flag: '-L',
-      description: 'Sigue redirects automáticamente'
+      flag: '-fsSL',
+      description: 'EL COMBO DEFINITIVO - Siempre úsalo para instalar herramientas',
+      why: 'Combina todo: fail on error + silent + show errors + follow redirects',
+      example: 'curl -fsSL https://deno.land/install.sh | bash',
+      level: 5,
+      note: 'Este patrón aparece en TODAS las instalaciones profesionales'
     },
     {
-      flag: '-o',
-      description: 'Guarda el output en un archivo'
+      flag: '-X METHOD',
+      description: 'Especifica método HTTP: GET, POST, PUT, DELETE',
+      context: 'APIs REST',
+      example: 'curl -X POST https://api.ejemplo.com/users'
     },
     {
-      flag: '-s',
-      description: 'Modo silencioso (no muestra progreso)'
+      flag: '-H "Header: valor"',
+      description: 'Agrega headers HTTP a la petición',
+      context: 'Content-Type, Authorization, etc.',
+      example: 'curl -H "Content-Type: application/json"'
+    },
+    {
+      flag: '-d "data"',
+      description: 'Envía datos en el body (JSON, form data)',
+      context: 'POST/PUT requests',
+      example: 'curl -d \'{"nombre": "Juan"}\''
+    },
+    {
+      flag: '-i',
+      description: 'Incluye headers de respuesta en output',
+      context: 'Ver status codes: 200 OK, 404 Not Found, 500 Error',
+      example: 'curl -i https://api.ejemplo.com'
     },
     {
       flag: '-v',
-      description: 'Modo verbose (muestra toda la comunicación)'
+      description: 'Modo verbose - muestra request y response completos',
+      context: 'Debugging profundo',
+      example: 'curl -v https://api.ejemplo.com'
+    },
+    {
+      flag: '-o archivo',
+      description: 'Guarda output en archivo',
+      context: 'Descargar recursos',
+      example: 'curl -o data.json https://api.ejemplo.com/data'
     }
   ],
+
   examples: [
     {
-      command: 'curl https://api.github.com',
-      description: 'GET simple - obtiene datos de una API'
+      title: 'LA PROGRESIÓN: Construyendo hacia -fsSL',
+      commands: [
+        {
+          command: 'curl https://api.github.com',
+          step: 'Paso 1: GET básico',
+          output: 'Verás barra de progreso y datos',
+          problema: 'Demasiado ruido visual'
+        },
+        {
+          command: 'curl -L https://nodejs.org/install',
+          step: 'Paso 2: + sigue redirects',
+          output: 'Sigue automáticamente si la URL redirige',
+          mejora: 'Ahora funciona con URLs acortadas'
+        },
+        {
+          command: 'curl -sL https://nodejs.org/install',
+          step: 'Paso 3: + modo silencioso',
+          output: 'Sin barra de progreso, solo datos',
+          mejora: 'Output limpio, listo para piping'
+        },
+        {
+          command: 'curl -fsSL https://deno.land/install.sh',
+          step: 'Paso 4: + falla en errores + muestra errores',
+          output: 'El combo completo',
+          nivel: 'PROFESIONAL - Memoriza esto'
+        },
+        {
+          command: 'curl -fsSL https://deno.land/install.sh | bash',
+          step: 'Paso 5: + ejecuta con piping',
+          output: 'Descarga e instala en un comando',
+          uso: 'Así instalan los profesionales'
+        }
+      ]
     },
     {
-      command: 'curl -i https://api.github.com/users/octocat',
-      description: 'GET con headers de respuesta incluidos'
+      title: 'CASOS REALES: Instalaciones que verás constantemente',
+      commands: [
+        {
+          command: 'curl -fsSL https://get.docker.com | sh',
+          tool: 'Docker',
+          note: 'Containerización'
+        },
+        {
+          command: 'curl -fsSL https://deno.land/install.sh | sh',
+          tool: 'Deno',
+          note: 'Runtime de JavaScript/TypeScript'
+        },
+        {
+          command: 'curl -fsSL https://sh.rustup.rs | sh',
+          tool: 'Rust',
+          note: 'Lenguaje de sistemas'
+        },
+        {
+          command: 'curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash',
+          tool: 'Homebrew',
+          note: 'Package manager para macOS'
+        },
+        {
+          command: 'curl -fsSL https://get.pnpm.io/install.sh | sh',
+          tool: 'pnpm',
+          note: 'Package manager rápido'
+        }
+      ]
     },
     {
-      command: 'curl -X POST https://api.ejemplo.com/users -H "Content-Type: application/json" -d \'{"nombre": "Juan"}\'',
-      description: 'POST con JSON - envía datos a una API'
+      title: 'TRABAJANDO CON APIs REST',
+      commands: [
+        {
+          command: 'curl https://api.github.com/users/octocat',
+          use: 'GET simple - API pública',
+          response: 'JSON con datos del usuario'
+        },
+        {
+          command: 'curl -X POST https://httpbin.org/post -H "Content-Type: application/json" -d \'{"nombre": "Juan", "edad": 25}\'',
+          use: 'POST con JSON - enviar datos',
+          response: 'Echo del servidor con tus datos'
+        },
+        {
+          command: 'curl -H "Authorization: Bearer TOKEN" https://api.ejemplo.com/protected',
+          use: 'GET autenticado - API privada',
+          response: 'Recursos protegidos'
+        },
+        {
+          command: 'curl -X PUT https://api.ejemplo.com/users/123 -H "Content-Type: application/json" -d \'{"nombre": "Juan Actualizado"}\'',
+          use: 'PUT - actualizar recurso',
+          response: 'Recurso modificado'
+        },
+        {
+          command: 'curl -X DELETE https://api.ejemplo.com/users/123 -H "Authorization: Bearer TOKEN"',
+          use: 'DELETE - eliminar recurso',
+          response: 'Confirmación de eliminación'
+        }
+      ]
     },
     {
-      command: 'curl -X POST https://httpbin.org/post -d "nombre=Juan&edad=25"',
-      description: 'POST con form data - formato URL-encoded'
+      title: 'DEBUGGING: Cuando las cosas no funcionan',
+      commands: [
+        {
+          command: 'curl -i https://api.ejemplo.com',
+          purpose: 'Ver headers de respuesta',
+          verás: 'HTTP/1.1 200 OK, Content-Type, etc.'
+        },
+        {
+          command: 'curl -v https://api.ejemplo.com',
+          purpose: 'Ver comunicación completa',
+          verás: 'Request headers, response headers, handshake SSL, etc.'
+        },
+        {
+          command: 'curl -f https://api.ejemplo.com/404',
+          purpose: 'Forzar error visible en 404/500',
+          verás: 'curl: (22) The requested URL returned error: 404'
+        },
+        {
+          command: 'curl -w "\\nStatus: %{http_code}\\n" https://api.ejemplo.com',
+          purpose: 'Mostrar solo el status code',
+          verás: 'Status: 200'
+        }
+      ]
+    }
+  ],
+
+  relatedLesson: 'APIs y HTTP',
+
+  tips: [
+    'REGLA DE ORO: curl -fsSL url | bash es el patrón universal para instalaciones',
+    'Desglose de -fsSL: (f)ail on error + (s)ilent + (S)how errors + (L)ocation',
+    'Para APIs: curl -X POST -H "Content-Type: application/json" -d \'{"key":"val"}\'',
+    'Para ver status codes: curl -i (headers) o curl -v (todo)',
+    'Siempre usa -L con URLs acortadas o que pueden redirigir'
+  ],
+
+  commonMistakes: [
+    {
+      error: 'Olvidar -L cuando la URL redirige',
+      resultado: 'Verás HTML de redirect en vez del recurso',
+      solución: 'Siempre agrega -L por defecto'
     },
     {
-      command: 'curl -H "Authorization: Bearer tu_token_aqui" https://api.ejemplo.com/protected',
-      description: 'GET con autenticación - usa un token JWT'
+      error: 'No usar -f en scripts automatizados',
+      resultado: 'curl "tiene éxito" incluso con 404/500',
+      solución: 'Usa -f para que falle visiblemente'
     },
     {
-      command: 'curl -L https://github.com',
-      description: 'Sigue redirects automáticamente (importante para URLs acortadas)'
+      error: 'Usar -v en scripts de producción',
+      resultado: 'Logs llenos de ruido innecesario',
+      solución: 'Usa -i para ver solo headers o -s para silencio'
     },
     {
-      command: 'curl -o archivo.json https://api.ejemplo.com/data',
-      description: 'Descarga la respuesta y guárdala en un archivo'
+      error: 'Olvidar comillas en JSON',
+      resultado: 'curl -d {"key":"value"} falla (bash interpreta las llaves)',
+      solución: 'Siempre usa comillas simples: -d \'{"key":"value"}\''
     },
     {
-      command: 'curl -v https://api.ejemplo.com',
-      description: 'Modo verbose - ve toda la negociación HTTP (útil para debugging)'
+      error: 'No especificar Content-Type en POST',
+      resultado: 'El servidor no entiende el formato',
+      solución: 'Siempre agrega -H "Content-Type: application/json"'
     }
   ],
-  relatedLesson: 'APIs y HTTP',
-  tips: [
-    'Pro tip: usa -i siempre para ver los status codes (200, 404, 500) en la respuesta',
-    'Para APIs modernas siempre agrega el header: -H "Content-Type: application/json"',
-    'curl -L es esencial cuando trabajas con URLs acortadas o redirects',
-    'Combina -s (silencioso) con herramientas como jq para parsear JSON: curl -s url | jq'
+
+  proTips: [
+    {
+      tip: 'Combina curl con jq para parsear JSON',
+      command: 'curl -s https://api.github.com/users/octocat | jq .name',
+      output: '"The Octocat"'
+    },
+    {
+      tip: 'Usa alias para curl -fsSL',
+      command: 'alias curlsh="curl -fsSL"',
+      entonces: 'curlsh https://ejemplo.com/install.sh | bash'
+    },
+    {
+      tip: 'Guarda cookies para sesiones',
+      command: 'curl -c cookies.txt -d "user=juan" https://ejemplo.com/login',
+      luego: 'curl -b cookies.txt https://ejemplo.com/dashboard'
+    }
   ]
 }

package/lib/readers/exercise-reader.js

@@ -1,6 +1,7 @@
-import { readFileSync, readdirSync } from 'fs'
+import { readFileSync, readdirSync, existsSync, mkdirSync, copyFileSync, statSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
+import { homedir } from 'os'
 import chalk from 'chalk'
 
 const __filename = fileURLToPath(import.meta.url)
@@ -9,6 +10,78 @@ const __dirname = dirname(__filename)
 export class ExerciseReader {
   constructor() {
     this.exercisesDir = join(__dirname, '../exercises')
+    this.bibliotecaDir = join(homedir(), '.creta', 'biblioteca')
+  }
+
+  /**
+   * Ensure biblioteca directory exists and sync exercises
+   */
+  syncBiblioteca(silent = false) {
+    try {
+      // Create directory if needed
+      if (!existsSync(this.bibliotecaDir)) {
+        mkdirSync(this.bibliotecaDir, { recursive: true })
+        if (!silent) {
+          console.log(chalk.cyan('\n📚 Creando biblioteca en ~/.creta/biblioteca...'))
+        }
+      }
+
+      // Get all exercise files
+      const exercises = this.getAvailableExercises()
+      let copied = 0
+      let updated = 0
+      let skipped = 0
+
+      exercises.forEach(exercise => {
+        const sourcePath = join(this.exercisesDir, exercise.filename)
+        const destPath = join(this.bibliotecaDir, exercise.filename)
+
+        // Check if destination exists and is up to date
+        if (existsSync(destPath)) {
+          const sourceStats = statSync(sourcePath)
+          const destStats = statSync(destPath)
+
+          if (sourceStats.mtime > destStats.mtime) {
+            copyFileSync(sourcePath, destPath)
+            updated++
+          } else {
+            skipped++
+          }
+        } else {
+          copyFileSync(sourcePath, destPath)
+          copied++
+        }
+      })
+
+      if (!silent) {
+        console.log(chalk.green('\n✅ Biblioteca sincronizada'))
+        if (copied > 0) console.log(chalk.gray(`   ${copied} ejercicio${copied !== 1 ? 's' : ''} copiado${copied !== 1 ? 's' : ''}`))
+        if (updated > 0) console.log(chalk.gray(`   ${updated} ejercicio${updated !== 1 ? 's' : ''} actualizado${updated !== 1 ? 's' : ''}`))
+        if (skipped > 0) console.log(chalk.gray(`   ${skipped} ejercicio${skipped !== 1 ? 's' : ''} sin cambios`))
+        console.log(chalk.cyan(`\n💡 Abre ejercicios con: nvim ~/.creta/biblioteca/<archivo>.md`))
+        console.log(chalk.gray(`   Ejemplo: nvim ~/.creta/biblioteca/14-gh-fundamentals.md\n`))
+      }
+
+      return { copied, updated, skipped, total: exercises.length }
+    } catch (error) {
+      if (!silent) {
+        console.error(chalk.red('\n❌ Error sincronizando biblioteca:'), error.message)
+      }
+      return { copied: 0, updated: 0, skipped: 0, total: 0, error }
+    }
+  }
+
+  /**
+   * Check if biblioteca needs initialization (show tip on first read)
+   */
+  checkBiblioteca() {
+    if (!existsSync(this.bibliotecaDir)) {
+      return {
+        exists: false,
+        message: chalk.dim(`\n💡 Tip: Ejecuta ${chalk.cyan('creta biblioteca')} para copiar ejercicios a ~/.creta/biblioteca/\n   Así podrás abrirlos en nvim con fold markers.`)
+      }
+    }
+    return { exists: true, message: null }
   }
 
   /**
@@ -94,6 +167,13 @@ export class ExerciseReader {
       const content = readFileSync(filepath, 'utf-8')
 
       this.displayExercise(exercise, content)
+
+      // Show biblioteca tip on first read
+      const bibliotecaStatus = this.checkBiblioteca()
+      if (!bibliotecaStatus.exists && bibliotecaStatus.message) {
+        console.log(bibliotecaStatus.message)
+      }
+
       return true
     } catch (error) {
       console.error(chalk.red('❌ Error leyendo ejercicio:'), error.message)
@@ -195,3 +275,11 @@ export async function listExercises() {
   const reader = new ExerciseReader()
   reader.list()
 }
+
+/**
+ * Sync biblioteca CLI entry point
+ */
+export async function syncBiblioteca() {
+  const reader = new ExerciseReader()
+  reader.syncBiblioteca()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icarusmx/creta",
-  "version": "1.5.15",
+  "version": "1.5.17",
   "description": "Salgamos de este laberinto.",
   "type": "module",
   "bin": {