@icarusmx/creta 1.5.13 → 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()
@@ -681,6 +689,7 @@ function showHelp() {
   console.log("📖 Documentación de comandos:")
   console.log("  creta ls             - Documentación en español del comando ls")
   console.log("  creta grep           - Documentación en español del comando grep")
+  console.log("  creta lz             - Localiza recursos (alias de curl)")
   console.log("  creta cd             - Documentación en español del comando cd")
   console.log("  creta curl           - Documentación en español del comando curl")
   console.log("  creta git status     - Documentación en español de git status")
@@ -690,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")
@@ -1904,7 +1915,7 @@ async function startVimSetupTutorial() {
 // Helper function to detect command help requests
 function isCommandHelpRequest(args) {
   // List of supported commands for help
-  const basicCommands = ['ls', 'cd', 'mkdir', 'touch', 'wc', 'curl', 'grep']
+  const basicCommands = ['ls', 'cd', 'mkdir', 'touch', 'wc', 'curl', 'grep', 'lz']
   const gitCommands = ['git status', 'git add', 'git commit', 'git push', 'git log']
 
   const commandString = args.join(' ')

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

@@ -23,6 +23,10 @@ export const grep = {
       flag: '-c',
       description: 'Cuenta líneas que coinciden'
     },
+    {
+      flag: '-q',
+      description: 'Modo silencioso (no imprime nada, solo devuelve código de salida)'
+    },
     {
       flag: '-l',
       description: 'Solo muestra nombres de archivos con coincidencias'

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

@@ -6,6 +6,7 @@ export { touch } from './touch.js'
 export { wc } from './wc.js'
 export { curl } from './curl.js'
 export { grep } from './grep.js'
+export { lz } from './lz.js'
 
 // Git commands
 export { gitStatus } from './git-status.js'
@@ -27,6 +28,7 @@ export const commandMap = {
   'wc': 'wc',
   'curl': 'curl',
   'grep': 'grep',
+  'lz': 'lz',
 
   // Git
   'git status': 'gitStatus',

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

@@ -0,0 +1,67 @@
+export const lz = {
+  command: 'lz',
+  description: 'Localiza recursos web con manejo automático de API keys',
+  usage: 'lz [url]',
+  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: [
+    {
+      pattern: 'lz icarus.mx/api/endpoint',
+      description: 'Request GET con autenticación automática (si $key está definida)'
+    },
+    {
+      pattern: 'export key="sk_test_123"',
+      description: 'Define tu API key para la sesión actual'
+    },
+    {
+      pattern: 'unset key',
+      description: 'Elimina la API key de la sesión (seguridad)'
+    },
+    {
+      pattern: 'headers icarus.mx/api',
+      description: 'Ver headers de un endpoint (función helper)'
+    },
+    {
+      pattern: 'post icarus.mx/api \'{"name":"Memo"}\'',
+      description: 'POST request con JSON (función helper)'
+    }
+  ],
+  examples: [
+    {
+      command: 'lz icarus.mx',
+      description: 'Request normal (sin autenticación)'
+    },
+    {
+      command: 'export key="sk_test_4eC39HqLyjWDarjtT1zdp7dc" && lz icarus.mx/api/creta',
+      description: 'Request con API key (header automático)'
+    },
+    {
+      command: 'switch_key dev && lz icarus.mx/api/users',
+      description: 'Cambiar a key de desarrollo y hacer request'
+    },
+    {
+      command: 'lz icarus.mx/api/data | jq \'.results\'',
+      description: 'Request autenticado + parsear JSON con jq'
+    }
+  ],
+  relatedLesson: 'Shell Functions: API Querying Simplificado',
+  tips: [
+    '🔑 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

@@ -0,0 +1,279 @@
+# Shell Functions: API Querying Simplificado
+
+## Objetivo
+
+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.
+
+## ¿Por qué una Función y no un Alias?
+
+**Alias**: Atajo simple para un comando
+- `alias lz='curl'` → reemplaza lz con 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" - wrapper inteligente de curl
+
+## Paso 1: Identificar tu Shell
+
+En macOS Catalina+ se usa `zsh` por defecto:
+
+```bash
+echo $SHELL
+```
+
+Si ves `/bin/zsh` → usas zsh (archivo: `~/.zshrc`)
+Si ves `/bin/bash` → usas bash (archivo: `~/.bashrc`)
+
+## Paso 2: Abrir el Archivo de Configuración
+
+Para zsh (más común en Mac):
+
+```bash
+nvim ~/.zshrc
+```
+
+O si prefieres VS Code:
+
+```bash
+code ~/.zshrc
+```
+
+## Paso 3: Agregar la Función `lz`
+
+Al final del archivo, agrega esta función:
+
+```bash
+# 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`
+
+## Paso 4: Recargar la Configuración
+
+Tienes dos opciones:
+
+**Opción 1: Recargar el archivo**
+```bash
+source ~/.zshrc
+```
+
+**Opción 2: Cerrar y abrir una nueva terminal**
+
+## Paso 5: Probar la Función
+
+**Sin API key (request normal):**
+```bash
+lz icarus.mx
+```
+
+Deberías ver el HTML del sitio de Icarus.
+
+**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
+# 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
+# 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"
+
+# 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`
+
+**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 funciones básicas, aprende sobre:
+- **jq**: parsear JSON en la terminal
+- **Scripts de shell**: automatizar workflows completos
+- **Dotfiles**: versionar tu configuración con Git
+- **Environment managers**: direnv para keys por proyecto
+
+## Recursos
+
+- `man zsh` - Manual de zsh
+- `man curl` - Manual de curl
+- `printenv` - Ver todas tus variables de entorno
+- `unset key` - Eliminar variable temporal
+
+---
+
+**Pro tip**: Usa `unset key` cuando termines de trabajar con APIs sensibles. Las variables exportadas persisten en toda la sesión de la terminal.