@icarusmx/creta 1.5.16 → 1.5.17

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/package.json

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