@icarusmx/creta 1.5.14 → 1.5.15

package/bin/creta.js

@@ -10,6 +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 { PapersExecutor } from '../lib/papers/PapersExecutor.js'
 import { ExercisesExecutor } from '../lib/executors/ExercisesExecutor.js'
 import { executeSintaxis } from '../lib/executors/sintaxis-executor.js'
@@ -185,6 +186,13 @@ if (command.startsWith('portafolio')) {
 } else if (command === 'privacy' || command === 'privacidad') {
   // Show privacy information
   showPrivacyInfo()
+} else if (command === 'read' || command === 'leer') {
+  // Read exercise/lesson
+  const query = args.slice(1).join(' ')
+  await readExercise(query)
+} else if (command === 'exercises' || command === 'ejercicios') {
+  // List all exercises
+  await listExercises()
 } else if (command === 'help' || command === 'ayuda') {
   // Show available commands
   showHelp()
@@ -691,7 +699,9 @@ function showHelp() {
   console.log("  creta                - Menú principal interactivo")
   console.log("  creta sintaxis       - Aprende comandos de terminal y Git")
   console.log("  creta enunciados     - Explora los 7 enunciados fundamentales de OOP")
-  console.log("  creta papers         - Recrea papers clásicos de Computer Science\n")
+  console.log("  creta papers         - Recrea papers clásicos de Computer Science")
+  console.log("  creta exercises      - Lista todos los ejercicios disponibles")
+  console.log("  creta read <nombre>  - Lee un ejercicio específico (ej: creta read 14)\n")
 
   console.log("🛠️  Proyectos:")
   console.log("  creta portafolio     - Crea tu portafolio personal")

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

@@ -1,57 +1,67 @@
 export const lz = {
   command: 'lz',
-  description: 'Localiza un recurso en la web (alias didáctico de curl)',
+  description: 'Localiza recursos web con manejo automático de API keys',
   usage: 'lz [url]',
-  commonOptions: [
+  setup: [
+    '1. Agrega la función lz a tu ~/.zshrc (ver lección Shell Functions)',
+    '2. Crea ~/.api_keys con permisos 600 para guardar tus keys',
+    '3. Exporta tu API key: export key="tu_api_key"',
+    '4. Usa lz normalmente - incluye la key automáticamente'
+  ],
+  commonPatterns: [
     {
-      flag: '-O',
-      description: 'Guarda el archivo con su nombre original'
+      pattern: 'lz icarus.mx/api/endpoint',
+      description: 'Request GET con autenticación automática (si $key está definida)'
     },
     {
-      flag: '-o archivo',
-      description: 'Guarda el contenido en el archivo especificado'
+      pattern: 'export key="sk_test_123"',
+      description: 'Define tu API key para la sesión actual'
     },
     {
-      flag: '-L',
-      description: 'Sigue redirecciones automáticamente'
+      pattern: 'unset key',
+      description: 'Elimina la API key de la sesión (seguridad)'
     },
     {
-      flag: '-I',
-      description: 'Solo muestra los headers (encabezados)'
+      pattern: 'headers icarus.mx/api',
+      description: 'Ver headers de un endpoint (función helper)'
     },
     {
-      flag: '-s',
-      description: 'Modo silencioso (no muestra progreso)'
+      pattern: 'post icarus.mx/api \'{"name":"Memo"}\'',
+      description: 'POST request con JSON (función helper)'
     }
   ],
   examples: [
     {
-      command: 'lz icarus.mx/README.md',
-      description: 'Localiza y muestra el contenido del README'
-    },
-    {
-      command: 'lz -O icarus.mx/logo.png',
-      description: 'Descarga logo.png con su nombre original'
+      command: 'lz icarus.mx',
+      description: 'Request normal (sin autenticación)'
     },
     {
-      command: 'lz -o mi-archivo.json api.ejemplo.com/data',
-      description: 'Guarda la respuesta en mi-archivo.json'
+      command: 'export key="sk_test_4eC39HqLyjWDarjtT1zdp7dc" && lz icarus.mx/api/creta',
+      description: 'Request con API key (header automático)'
     },
     {
-      command: 'lz -I icarus.mx',
-      description: 'Muestra solo los headers del sitio'
+      command: 'switch_key dev && lz icarus.mx/api/users',
+      description: 'Cambiar a key de desarrollo y hacer request'
     },
     {
-      command: 'lz -sL api.ejemplo.com | grep "version"',
-      description: 'Busca "version" en la respuesta (silencioso + sigue redirects)'
+      command: 'lz icarus.mx/api/data | jq \'.results\'',
+      description: 'Request autenticado + parsear JSON con jq'
     }
   ],
-  relatedLesson: 'Curl y pipes',
+  relatedLesson: 'Shell Functions: API Querying Simplificado',
   tips: [
-    '🧠 lz = "localiza recurso" - Alias en español para curl',
-    'curl significa "Client URL" - Cliente para Localizar Recursos Universales',
-    'Lo "universal" viene del protocolo HTTP (HyperText Transfer Protocol)',
-    'En la terminal real usa curl, pero lz te ayuda a pensar en español',
-    'Pro tip: lz es perfecto para probar APIs rápidamente'
+    '🔑 lz detecta automáticamente si $key está definida y agrega el header',
+    '⚡ Combina lz con jq para parsear JSON: lz api.com | jq',
+    '🔒 Usa chmod 600 ~/.api_keys para proteger tus keys',
+    '🔄 switch_key te permite cambiar entre dev/prod fácilmente',
+    '🧹 Siempre usa unset key cuando termines con APIs sensibles',
+    '📖 lz = "localiza recurso" - wrapper inteligente de curl'
+  ],
+  securityNotes: [
+    '❌ NUNCA pongas API keys directamente en ~/.zshrc',
+    '✅ Usa ~/.api_keys con permisos 600 (solo tú puedes leer)',
+    '✅ Agrega ~/.api_keys a tu .gitignore',
+    '✅ Usa unset key después de trabajar con APIs sensibles',
+    '✅ Considera usar direnv para keys por proyecto'
   ]
 }

package/lib/exercises/13-shell-aliases.md

@@ -1,21 +1,38 @@
-# Shell Aliases: Personaliza tu Terminal
+# Shell Functions: API Querying Simplificado
 
 ## Objetivo
 
-Aprende a crear alias de shell para hacer comandos más intuitivos y personalizados. Crearemos el alias `lz` (localiza recurso) para `curl`.
+Aprende a crear funciones de shell para hacer peticiones a APIs más fáciles. Crearemos `lz` (localiza recurso) - una función que maneja API keys automáticamente.
 
-## ¿Qué es un Alias?
+## ¿Por qué una Función y no un Alias?
 
-Un alias es un atajo personalizado para un comando. Por ejemplo:
-- En vez de escribir `curl https://icarus.mx`
-- Escribes `lz https://icarus.mx`
+**Alias**: Atajo simple para un comando
+- `alias lz='curl'` → reemplaza lz con curl
 
-## Por qué `lz` para curl
+**Función**: Lógica programable con argumentos
+- Puede verificar variables (`$key`)
+- Puede construir requests dinámicamente
+- Puede manejar errores
+
+## El Problema que Resuelve `lz`
+
+Sin `lz`:
+```bash
+curl -H "Authorization: Bearer tu_api_key_super_larga_aqui" https://icarus.mx/api/creta
+```
+
+Con `lz`:
+```bash
+export key="tu_api_key_super_larga_aqui"
+lz icarus.mx/api/creta
+```
+
+## Por qué `lz`
 
 **curl** = Client URL (Cliente de URL)
 - **Cliente**: localiza recursos para ti
 - **Universal**: usa HTTP (HyperText Transfer Protocol)
-- **lz**: "localiza recurso" - alias en español
+- **lz**: "localiza recurso" - wrapper inteligente de curl
 
 ## Paso 1: Identificar tu Shell
 
@@ -42,15 +59,36 @@ O si prefieres VS Code:
 code ~/.zshrc
 ```
 
-## Paso 3: Agregar el Alias
+## Paso 3: Agregar la Función `lz`
 
-Al final del archivo, agrega:
+Al final del archivo, agrega esta función:
 
 ```bash
-# Alias personalizados
-alias lz='curl'
+# Función lz - API querying con API key automático
+lz() {
+  local url="$1"
+
+  # Si la URL no tiene protocolo, agregar https://
+  if [[ ! "$url" =~ ^https?:// ]]; then
+    url="https://$url"
+  fi
+
+  # Si hay API key exportada, incluirla en el header
+  if [ -n "$key" ]; then
+    curl -H "Authorization: Bearer $key" "$url"
+  else
+    curl "$url"
+  fi
+}
 ```
 
+**¿Qué hace esta función?**
+1. Toma la URL como argumento (`$1`)
+2. Agrega `https://` si no tiene protocolo
+3. Verifica si existe la variable `$key`
+4. Si existe, incluye el header de autorización
+5. Si no, hace un curl normal
+
 Guarda el archivo:
 - En nvim: presiona `ESC`, luego escribe `:wq` y `ENTER`
 - En VS Code: `Cmd + S`
@@ -66,48 +104,132 @@ source ~/.zshrc
 
 **Opción 2: Cerrar y abrir una nueva terminal**
 
-## Paso 5: Probar el Alias
+## Paso 5: Probar la Función
 
+**Sin API key (request normal):**
 ```bash
 lz icarus.mx
 ```
 
 Deberías ver el HTML del sitio de Icarus.
 
-## Alias Útiles para Agregar
+**Con API key (request autenticado):**
+```bash
+# Exportar tu API key (poético, ¿no?)
+export key="es un secreto"
+
+# Hacer request con autenticación automática
+lz icarus.mx/api/creta/testeo
+
+# La función automáticamente incluye:
+# -H "Authorization: Bearer es un secreto"
+
+# El API responde:
+# "que a tu mirada y la mía la separa el abismo"
+```
+
+**Ventajas:**
+- No tener que escribir headers largos cada vez
+- Cambiar de API key con un solo `export`
+- Código más limpio y legible
+
+## Paso 6: Guardar el API Key de Forma Segura
+
+**❌ Nunca hagas esto:**
+```bash
+# NO pongas tu key directo en ~/.zshrc
+export key="sk_live_SUPER_SECRETA"  # ¡MAL!
+```
+
+**✅ Mejor práctica:**
+```bash
+# En ~/.zshrc agrega:
+if [ -f ~/.api_keys ]; then
+  source ~/.api_keys
+fi
+```
+
+```bash
+# Crea ~/.api_keys con permisos restrictivos
+touch ~/.api_keys
+chmod 600 ~/.api_keys
+
+# Edita ~/.api_keys y agrega:
+export key="tu_api_key_aqui"
+```
+
+Ahora tu key está separada y con permisos seguros (solo tú puedes leerla).
+
+## Funciones Adicionales Útiles
 
 Mientras estás editando `~/.zshrc`, considera agregar:
 
 ```bash
-# Alias para comandos comunes
-alias ls='ls -G'                    # ls con colores en Mac
-alias ll='ls -lah'                  # ls largo con todo
-alias ..='cd ..'                    # sube un nivel
-alias ...='cd ../..'                # sube dos niveles
-alias gs='git status'               # git status rápido
-alias ga='git add'                  # git add rápido
-alias gc='git commit -m'            # git commit con mensaje
-alias gp='git push'                 # git push rápido
-alias lz='curl'                     # localiza recurso (nuestro nuevo alias)
-
-# Alias para navegación rápida
-alias proyectos='cd ~/proyectos'
-alias icarus='cd ~/icarus'
+# Función para cambiar entre diferentes API keys
+switch_key() {
+  case "$1" in
+    dev)
+      export key="sk_test_desarrollo"
+      echo "✅ API key: desarrollo"
+      ;;
+    prod)
+      export key="sk_live_produccion"
+      echo "✅ API key: producción"
+      ;;
+    *)
+      echo "Uso: switch_key [dev|prod]"
+      ;;
+  esac
+}
+
+# Ver headers de una API
+headers() {
+  lz "$1" -I
+}
+
+# POST request con lz
+post() {
+  local url="$1"
+  local data="$2"
+
+  if [ -n "$key" ]; then
+    curl -X POST -H "Authorization: Bearer $key" \
+         -H "Content-Type: application/json" \
+         -d "$data" "https://$url"
+  else
+    curl -X POST -H "Content-Type: application/json" \
+         -d "$data" "https://$url"
+  fi
+}
 ```
 
 ## Verificar que Funciona
 
 ```bash
-# Probar lz
-lz -I icarus.mx
+# Request normal
+lz icarus.mx
+
+# Request con autenticación poética
+export key="es un secreto"
+lz icarus.mx/api/creta/testeo
+# Responde: "que a tu mirada y la mía la separa el abismo"
 
-# Debería mostrar los headers del sitio
+# Ver headers
+headers icarus.mx
+
+# POST con data
+post icarus.mx/api/users '{"name":"Guillermo"}'
+
+# Cambiar entre keys
+switch_key dev
+switch_key prod
 ```
 
 ## Troubleshooting
 
 **Problema: "command not found: lz"**
 - Solución: Verifica que ejecutaste `source ~/.zshrc`
+- Verifica que la función está correctamente definida (sin errores de sintaxis)
 
 **Problema: "No such file or directory: ~/.zshrc"**
 - Solución: Crea el archivo primero: `touch ~/.zshrc`
@@ -115,20 +237,43 @@ lz -I icarus.mx
 **Problema: Sigo usando bash en vez de zsh**
 - Solución: Edita `~/.bashrc` en vez de `~/.zshrc`
 
+**Problema: La API responde 401 Unauthorized**
+- Verifica que exportaste la key: `echo $key`
+- Verifica que la key es válida
+- Prueba el request completo con curl para debug
+
+**Problema: ~/.api_keys no se carga**
+- Verifica que agregaste el `source` en ~/.zshrc
+- Recarga la configuración: `source ~/.zshrc`
+
+## Seguridad: ¿Por qué `chmod 600`?
+
+```bash
+chmod 600 ~/.api_keys
+```
+
+Permisos en formato numérico:
+- **6** (rw-): El dueño puede leer y escribir
+- **0** (---): El grupo no tiene permisos
+- **0** (---): Otros no tienen permisos
+
+Resultado: Solo TÚ puedes leer tus API keys.
+
 ## Siguiente Nivel
 
-Una vez que domines los alias básicos, aprende sobre:
-- **Funciones de shell**: alias con argumentos complejos
+Una vez que domines funciones básicas, aprende sobre:
+- **jq**: parsear JSON en la terminal
+- **Scripts de shell**: automatizar workflows completos
 - **Dotfiles**: versionar tu configuración con Git
-- **Oh My Zsh**: framework para mejorar tu terminal
+- **Environment managers**: direnv para keys por proyecto
 
 ## Recursos
 
 - `man zsh` - Manual de zsh
-- `man bash` - Manual de bash
-- `alias` - Ver todos tus alias actuales
-- `unalias lz` - Eliminar un alias temporal
+- `man curl` - Manual de curl
+- `printenv` - Ver todas tus variables de entorno
+- `unset key` - Eliminar variable temporal
 
 ---
 
-**Pro tip**: Los alias se cargan cada vez que abres una terminal nueva. Si quieres un alias temporal (solo para la sesión actual), simplemente escribe `alias lz='curl'` directo en la terminal sin agregarlo al archivo.
+**Pro tip**: Usa `unset key` cuando termines de trabajar con APIs sensibles. Las variables exportadas persisten en toda la sesión de la terminal.