@icarusmx/creta 1.5.14 → 1.5.15

package/lib/exercises/14-gh-fundamentals.md

@@ -0,0 +1,976 @@
+# GitHub CLI Fundamentals - De Instalación a Upstream
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 LazyVim Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold under cursor)
+
+This document uses fold markers `{{{` and `}}}` for organized reading.
+
+}}}
+
+## 🎯 ¿Qué es GitHub CLI? {{{
+
+**GitHub CLI (`gh`)** es la herramienta oficial de GitHub para trabajar con repos, issues, PRs y más desde la terminal.
+
+**¿Por qué usar `gh` en vez de solo `git`?**
+- `git` maneja control de versiones local y sync con remotes
+- `gh` maneja la **plataforma GitHub**: repos, issues, PRs, workflows, releases
+- Juntos son un equipo completo
+
+**Flujo típico:**
+```bash
+# gh crea el repo en GitHub
+gh repo create my-project --public
+
+# git maneja commits y sync
+git add .
+git commit -m "first commit"
+git push
+```
+
+}}}
+
+## 🍺 Instalación con Homebrew {{{
+
+### macOS/Linux {{{
+
+```bash
+# Instalar GitHub CLI
+brew install gh
+```
+
+**Verificar instalación:**
+```bash
+gh --version
+# Output: gh version 2.40.0 (o superior)
+```
+
+}}}
+
+### ¿Qué se instaló? {{{
+
+Homebrew instaló:
+- **Binario `gh`**: El ejecutable principal
+- **Man pages**: Documentación (`man gh`)
+- **Shell completions**: Autocompletado para tu shell
+
+**Ubicación del binario:**
+```bash
+which gh
+# Output: /opt/homebrew/bin/gh (Apple Silicon)
+#     or: /usr/local/bin/gh (Intel)
+```
+
+}}}
+
+### Windows (Opcional) {{{
+
+Si usas Windows, instala con:
+```powershell
+# Con winget
+winget install --id GitHub.cli
+
+# O con scoop
+scoop install gh
+```
+
+}}}
+
+}}}
+
+## 🔐 Autenticación con GitHub {{{
+
+### Login Interactivo {{{
+
+```bash
+gh auth login
+```
+
+**El CLI te preguntará:**
+
+**1. ¿Qué cuenta?**
+```
+? What account do you want to log into?
+> GitHub.com
+  GitHub Enterprise Server
+```
+**→ Selecciona:** `GitHub.com`
+
+**2. ¿Protocolo preferido?**
+```
+? What is your preferred protocol for Git operations?
+  HTTPS
+> SSH
+```
+**→ Selecciona:** `SSH` (recomendado - más seguro)
+
+**3. ¿Subir tu SSH key?**
+```
+? Upload your SSH public key to your GitHub account?
+> /Users/guillermo/.ssh/id_ed25519.pub
+  Skip
+```
+**→ Selecciona:** Tu key existente (o genera una si no tienes)
+
+**4. ¿Cómo autenticarte?**
+```
+? How would you like to authenticate GitHub CLI?
+> Login with a web browser
+  Paste an authentication token
+```
+**→ Selecciona:** `Login with a web browser`
+
+**5. Copia el código y presiona Enter**
+```
+! First copy your one-time code: XXXX-XXXX
+Press Enter to open github.com in your browser...
+```
+
+**6. Autoriza en el browser**
+- Se abre automáticamente
+- Pega el código
+- Click "Authorize GitHub CLI"
+
+**¡Listo!** ✅
+```
+✓ Authentication complete.
+✓ Logged in as guillermo
+```
+
+}}}
+
+### Verificar Autenticación {{{
+
+```bash
+# Ver tu usuario actual
+gh auth status
+
+# Output:
+# github.com
+#   ✓ Logged in to github.com as guillermo (~/.config/gh/hosts.yml)
+#   ✓ Git operations for github.com configured to use ssh protocol.
+#   ✓ Token: gho_************************************
+```
+
+**Archivos de configuración:**
+- `~/.config/gh/hosts.yml`: Credenciales
+- `~/.gitconfig`: Se actualizó para usar SSH
+
+}}}
+
+### Troubleshooting Login {{{
+
+**Problema: "Could not determine default authenticated user"**
+```bash
+# Solución: Re-autenticar
+gh auth logout
+gh auth login
+```
+
+**Problema: SSH key no encontrada**
+```bash
+# Generar nueva SSH key
+ssh-keygen -t ed25519 -C "tu@email.com"
+
+# Agregar a ssh-agent
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+
+# Reintentar login
+gh auth login
+```
+
+**Problema: Token expiró**
+```bash
+# Refrescar token
+gh auth refresh
+```
+
+}}}
+
+}}}
+
+## 📦 Crear un Nuevo Repositorio {{{
+
+### Crear Repo Vacío (GitHub primero) {{{
+
+**Escenario:** Empezar un proyecto nuevo completamente desde cero.
+
+```bash
+# Crear repo público en GitHub
+gh repo create my-awesome-project --public
+
+# Output:
+# ✓ Created repository guillermo/my-awesome-project on GitHub
+# ? Clone the new repository locally? Yes
+# Cloning into 'my-awesome-project'...
+```
+
+**Flags disponibles:**
+- `--public`: Repo público (visible para todos)
+- `--private`: Repo privado (solo tú y colaboradores)
+- `--description "..."`: Descripción del proyecto
+- `--gitignore node`: Agregar .gitignore para Node.js
+- `--license mit`: Agregar licencia MIT
+
+**Ejemplo completo:**
+```bash
+gh repo create creta-v2 \
+  --public \
+  --description "CLI companion for LATAM developers" \
+  --gitignore node \
+  --license mit
+```
+
+}}}
+
+### Crear Repo con Clone Automático {{{
+
+```bash
+# Crear y clonar en un solo comando
+gh repo create portfolio-site --public --clone
+
+# El CLI:
+# 1. Crea el repo en GitHub
+# 2. Lo clona localmente
+# 3. Ya estás dentro del directorio
+```
+
+**Ahora puedes empezar a trabajar:**
+```bash
+cd portfolio-site
+echo "# My Portfolio" > README.md
+git add .
+git commit -m "initial commit"
+git push
+```
+
+}}}
+
+### Crear Repo desde Directorio Existente {{{
+
+**Escenario:** Ya tienes código local y quieres subirlo a GitHub.
+
+```bash
+# En tu proyecto existente
+cd ~/projects/my-local-app
+
+# Inicializar git si no lo has hecho
+git init
+
+# Crear commit inicial
+git add .
+git commit -m "initial commit"
+
+# Crear repo en GitHub y conectarlo
+gh repo create my-local-app --source=. --public --push
+
+# El CLI:
+# 1. Crea el repo en GitHub
+# 2. Agrega el remote "origin"
+# 3. Hace push automático
+```
+
+**Flags importantes:**
+- `--source=.`: Usa el directorio actual
+- `--push`: Push automático después de crear
+- `--remote <name>`: Nombre del remote (default: origin)
+
+}}}
+
+### Crear Repo Interactivo {{{
+
+Si prefieres que el CLI te pregunte cada opción:
+
+```bash
+gh repo create
+```
+
+**El CLI preguntará:**
+1. ¿Nombre del repo?
+2. ¿Descripción?
+3. ¿Visibilidad (public/private)?
+4. ¿Agregar .gitignore?
+5. ¿Agregar licencia?
+6. ¿Clonar localmente?
+
+**Ideal para:** Cuando no estás seguro de las opciones.
+
+}}}
+
+}}}
+
+## 🔗 Trabajar con Remotes {{{
+
+### Ver Remotes Configurados {{{
+
+```bash
+# Ver remotes
+git remote -v
+
+# Output:
+# origin  git@github.com:guillermo/creta.git (fetch)
+# origin  git@github.com:guillermo/creta.git (push)
+```
+
+**Partes de la URL SSH:**
+- `git@github.com`: Servidor y protocolo
+- `guillermo`: Tu username
+- `creta.git`: Nombre del repo
+
+}}}
+
+### Agregar Remote Manualmente {{{
+
+**Escenario:** Creaste el repo en GitHub desde el browser, no con `gh`.
+
+```bash
+# Crear repo local
+git init
+git add .
+git commit -m "initial commit"
+
+# Agregar remote
+git remote add origin git@github.com:guillermo/my-project.git
+
+# Verificar
+git remote -v
+
+# Push inicial
+git push -u origin main
+```
+
+**Anatomía del comando:**
+- `git remote add`: Agregar nuevo remote
+- `origin`: Nombre del remote (convención)
+- URL: Dónde está el repo en GitHub
+
+}}}
+
+### Cambiar URL del Remote {{{
+
+**Escenario:** Necesitas cambiar de HTTPS a SSH (o viceversa).
+
+```bash
+# Ver URL actual
+git remote get-url origin
+# https://github.com/guillermo/creta.git
+
+# Cambiar a SSH
+git remote set-url origin git@github.com:guillermo/creta.git
+
+# Verificar
+git remote get-url origin
+# git@github.com:guillermo/creta.git
+```
+
+**¿Por qué preferir SSH?**
+- No pide password en cada push
+- Más seguro
+- Mejor para automatización
+
+}}}
+
+### Múltiples Remotes {{{
+
+**Escenario:** Fork de un proyecto + tu copia personal.
+
+```bash
+# Remote por defecto (tu fork)
+git remote add origin git@github.com:guillermo/awesome-project.git
+
+# Remote del proyecto original (upstream)
+git remote add upstream git@github.com:original-author/awesome-project.git
+
+# Ver todos
+git remote -v
+# origin    git@github.com:guillermo/awesome-project.git (fetch)
+# origin    git@github.com:guillermo/awesome-project.git (push)
+# upstream  git@github.com:original-author/awesome-project.git (fetch)
+# upstream  git@github.com:original-author/awesome-project.git (push)
+```
+
+**Uso típico:**
+```bash
+# Pull cambios del proyecto original
+git fetch upstream
+git merge upstream/main
+
+# Push tus cambios a tu fork
+git push origin feature-branch
+```
+
+}}}
+
+}}}
+
+## ⬆️ Configurar Upstream (Tracking Branch) {{{
+
+### ¿Qué es Upstream? {{{
+
+**Upstream** (también llamado "tracking branch") es la relación entre tu rama local y la rama remota.
+
+**Sin upstream:**
+```bash
+git push
+# fatal: The current branch main has no upstream branch.
+```
+
+**Con upstream:**
+```bash
+git push
+# ✓ Todo funciona automáticamente
+```
+
+**Beneficios:**
+- `git pull` sin argumentos (sabe de dónde jalar)
+- `git push` sin argumentos (sabe a dónde empujar)
+- `git status` muestra si estás adelante/atrás
+
+}}}
+
+### Set Upstream en Primer Push {{{
+
+**Opción 1: Flag `-u` (más común)**
+```bash
+# Hacer push Y establecer upstream
+git push -u origin main
+
+# Output:
+# Enumerating objects: 3, done.
+# ...
+# Branch 'main' set up to track remote branch 'main' from 'origin'.
+```
+
+**Ahora puedes usar:**
+```bash
+git push    # En vez de: git push origin main
+git pull    # En vez de: git pull origin main
+```
+
+}}}
+
+### Set Upstream sin Push {{{
+
+**Opción 2: Comando explícito**
+```bash
+# Establecer upstream sin hacer push
+git branch --set-upstream-to=origin/main main
+
+# O la versión corta:
+git branch -u origin/main main
+```
+
+**Uso típico:**
+- Cuando la rama ya existe remotamente
+- Después de `git clone`
+- Para reconectar una rama
+
+}}}
+
+### Ver Upstream Configurado {{{
+
+```bash
+# Ver tracking info de todas las ramas
+git branch -vv
+
+# Output:
+# * main    4093951 [origin/main] add new strategic route
+#   dev     1348508 [origin/dev: behind 2] add os fundamentals
+#   feature ddbd498 add refactor.txt file
+```
+
+**Interpretación:**
+- `[origin/main]`: main trackea origin/main
+- `[origin/dev: behind 2]`: dev está 2 commits atrás de origin/dev
+- Sin `[]`: feature no tiene upstream
+
+}}}
+
+### Workflow con Upstream {{{
+
+**Crear feature branch con upstream desde el inicio:**
+
+```bash
+# Crear branch local
+git checkout -b feature/new-lesson
+
+# Hacer algunos commits
+git add .
+git commit -m "add new lesson"
+
+# Push con upstream
+git push -u origin feature/new-lesson
+
+# Output:
+# Branch 'feature/new-lesson' set up to track remote branch 'feature/new-lesson' from 'origin'.
+
+# Ahora todos los push/pull son simples
+git push  # ✅ Funciona automáticamente
+```
+
+}}}
+
+### Cambiar Upstream de una Rama {{{
+
+**Escenario:** Quieres que tu rama local trackee una rama remota diferente.
+
+```bash
+# Rama actual trackea origin/dev
+git branch -vv
+# * feature [origin/dev] WIP
+
+# Cambiar a origin/main
+git branch -u origin/main
+
+# Verificar
+git branch -vv
+# * feature [origin/main: ahead 3] WIP
+```
+
+**Uso típico:** Re-basar feature branches.
+
+}}}
+
+}}}
+
+## 🔄 Workflow Completo: De Cero a Deploy {{{
+
+### Nuevo Proyecto desde Scratch {{{
+
+```bash
+# 1. Crear repo en GitHub
+gh repo create my-app --public --gitignore node --license mit
+
+# 2. Clone automático (el CLI pregunta)
+# → Selecciona "Yes" cuando pregunte si clonar
+
+# 3. Ya estás en el directorio
+cd my-app
+
+# 4. Crear código
+echo "console.log('Hello Icarus')" > index.js
+
+# 5. Commit
+git add .
+git commit -m "add hello world"
+
+# 6. Push (upstream ya configurado por gh clone)
+git push
+
+# 7. Abrir repo en browser
+gh repo view --web
+```
+
+**¡Todo conectado automáticamente!** ✅
+
+}}}
+
+### Proyecto Existente → GitHub {{{
+
+```bash
+# 1. Inicializar git
+cd ~/projects/existing-app
+git init
+git add .
+git commit -m "initial commit"
+
+# 2. Crear repo y push en un comando
+gh repo create existing-app --source=. --public --push
+
+# 3. Verificar que todo se subió
+gh repo view --web
+```
+
+**El CLI se encarga de:**
+- ✅ Crear repo en GitHub
+- ✅ Agregar remote origin
+- ✅ Configurar upstream
+- ✅ Push automático
+
+}}}
+
+### Fork y Contribuir a Proyecto Existente {{{
+
+```bash
+# 1. Fork del proyecto original
+gh repo fork original-author/cool-project --clone
+
+# 2. Ya estás en el directorio
+cd cool-project
+
+# 3. Ver remotes configurados
+git remote -v
+# origin    git@github.com:guillermo/cool-project.git (tu fork)
+# upstream  git@github.com:original-author/cool-project.git (original)
+
+# 4. Crear feature branch
+git checkout -b feature/add-spanish-docs
+
+# 5. Hacer cambios
+echo "# Documentación en Español" > README.es.md
+git add .
+git commit -m "add Spanish documentation"
+
+# 6. Push a TU fork
+git push -u origin feature/add-spanish-docs
+
+# 7. Crear Pull Request
+gh pr create --title "Add Spanish docs" --body "Docs for LATAM community"
+
+# 8. Actualizar desde upstream (mantenerse al día)
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+```
+
+**Ventajas del workflow con `gh`:**
+- Fork automático con remotes configurados
+- PRs desde la terminal
+- Seguimiento de issues y reviews sin browser
+
+}}}
+
+}}}
+
+## 🛠️ Comandos Útiles de gh {{{
+
+### Ver Info del Repo {{{
+
+```bash
+# Ver repo actual en browser
+gh repo view --web
+
+# Ver info del repo en terminal
+gh repo view
+
+# Ver repos de un usuario
+gh repo list guillermo
+
+# Ver repos de una org
+gh repo list icarusmx
+```
+
+}}}
+
+### Clonar Repos {{{
+
+```bash
+# Clone rápido (solo necesitas owner/repo)
+gh repo clone guillermo/creta
+
+# Equivalente a:
+git clone git@github.com:guillermo/creta.git
+```
+
+}}}
+
+### Trabajar con Issues {{{
+
+```bash
+# Crear issue
+gh issue create --title "Bug in lesson 7" --body "Steps to reproduce..."
+
+# Ver issues
+gh issue list
+
+# Ver issue específico
+gh issue view 42
+
+# Cerrar issue
+gh issue close 42
+```
+
+}}}
+
+### Trabajar con PRs {{{
+
+```bash
+# Crear PR
+gh pr create --title "Fix typo" --body "Fixed Spanish typo in README"
+
+# Ver PRs
+gh pr list
+
+# Ver PR específico
+gh pr view 123
+
+# Checkout a PR localmente (para probarla)
+gh pr checkout 123
+
+# Merge PR
+gh pr merge 123
+
+# Cerrar PR sin merge
+gh pr close 123
+```
+
+}}}
+
+### Releases {{{
+
+```bash
+# Crear release
+gh release create v1.5.0 --title "Phase 2 Launch" --notes "Command reference system"
+
+# Ver releases
+gh release list
+
+# Download assets de un release
+gh release download v1.5.0
+```
+
+}}}
+
+}}}
+
+## 🧪 Ejercicio Práctico {{{
+
+**Objetivo:** Crear un proyecto completo desde cero usando todo lo aprendido.
+
+### Paso a Paso {{{
+
+```bash
+# 1. Crear proyecto
+mkdir test-gh-workflow
+cd test-gh-workflow
+
+# 2. Setup inicial
+echo "# Test GH Workflow" > README.md
+echo "console.log('Testing gh')" > index.js
+echo "node_modules/" > .gitignore
+
+# 3. Git init
+git init
+git add .
+git commit -m "initial commit"
+
+# 4. Crear repo en GitHub y push
+gh repo create test-gh-workflow --source=. --public --push
+
+# 5. Crear feature branch
+git checkout -b feature/add-docs
+
+# 6. Agregar más contenido
+echo "## How to Use" >> README.md
+git add .
+git commit -m "add usage docs"
+
+# 7. Push con upstream
+git push -u origin feature/add-docs
+
+# 8. Crear PR
+gh pr create --title "Add documentation" --body "Basic usage docs"
+
+# 9. Ver el PR en browser
+gh pr view --web
+
+# 10. Merge desde terminal
+gh pr merge --squash
+
+# 11. Volver a main y pull
+git checkout main
+git pull
+
+# 12. Ver el repo final
+gh repo view --web
+```
+
+}}}
+
+### Verificación {{{
+
+**Checklist:** ✅ Deberías tener:
+- [ ] Repo en GitHub
+- [ ] Main branch con README e index.js
+- [ ] PR mergeado en history
+- [ ] Remote origin configurado
+- [ ] Upstream configurado para main
+- [ ] Todo visible en GitHub.com
+
+**Limpieza (opcional):**
+```bash
+# Eliminar repo de prueba
+gh repo delete test-gh-workflow --yes
+
+# Eliminar directorio local
+cd ..
+rm -rf test-gh-workflow
+```
+
+}}}
+
+}}}
+
+## 🎓 Resumen: Git vs gh {{{
+
+### git: Control de Versiones {{{
+
+**Comandos que usas con `git`:**
+- `git init` - Inicializar repo
+- `git add` - Stage cambios
+- `git commit` - Crear commits
+- `git push` - Subir commits a remote
+- `git pull` - Descargar cambios de remote
+- `git branch` - Manejar ramas
+- `git merge` - Combinar ramas
+- `git remote` - Manejar remotes
+
+**Filosofía:** Local-first, luego sync con remotes.
+
+}}}
+
+### gh: Plataforma GitHub {{{
+
+**Comandos que usas con `gh`:**
+- `gh repo create` - Crear repos en GitHub
+- `gh repo fork` - Fork repos
+- `gh pr create` - Crear Pull Requests
+- `gh issue create` - Crear Issues
+- `gh release create` - Crear Releases
+- `gh auth login` - Autenticación
+
+**Filosofía:** Automatizar workflows de GitHub desde terminal.
+
+}}}
+
+### Trabajan Juntos {{{
+
+**Ejemplo combinado:**
+```bash
+# gh crea el repo en GitHub
+gh repo create my-project --public
+
+# git maneja el código
+git add .
+git commit -m "first feature"
+
+# git empuja a GitHub
+git push
+
+# gh crea el PR
+gh pr create --title "Add feature"
+
+# gh mergea el PR
+gh pr merge
+
+# git actualiza tu local
+git pull
+```
+
+**Pro tip:** Conoce cuándo usar cada uno. `git` para código, `gh` para plataforma.
+
+}}}
+
+}}}
+
+## 📚 Quick Reference {{{
+
+```bash
+# === INSTALACIÓN ===
+brew install gh
+
+# === AUTENTICACIÓN ===
+gh auth login                    # Login interactivo
+gh auth status                   # Ver estado
+gh auth logout                   # Logout
+
+# === REPOS ===
+gh repo create <name> --public   # Crear repo público
+gh repo create --source=. --push # Crear desde directorio actual
+gh repo clone <owner>/<repo>     # Clonar repo
+gh repo view --web               # Ver en browser
+gh repo fork <owner>/<repo>      # Fork con remotes configurados
+
+# === REMOTES ===
+git remote -v                    # Ver remotes
+git remote add origin <url>      # Agregar remote
+git remote set-url origin <url>  # Cambiar URL
+
+# === UPSTREAM ===
+git push -u origin main          # Push + set upstream
+git branch -u origin/main        # Set upstream sin push
+git branch -vv                   # Ver tracking info
+
+# === WORKFLOW ===
+gh pr create                     # Crear PR
+gh pr list                       # Ver PRs
+gh pr merge                      # Merge PR
+gh issue create                  # Crear issue
+gh release create <tag>          # Crear release
+```
+
+}}}
+
+## 💡 Mejores Prácticas {{{
+
+### Do's ✅ {{{
+
+1. **Usa SSH para repos** (más seguro, no pide password)
+2. **Siempre usa `-u` en primer push** (configura upstream)
+3. **Nombra remotes descriptivos** (origin, upstream, fork-name)
+4. **Verifica authentication** antes de trabajar (`gh auth status`)
+5. **Usa `gh` para crear repos** (configura todo automáticamente)
+6. **Crea PRs desde la terminal** (faster workflow)
+7. **Mantén upstream sincronizado** en forks
+
+}}}
+
+### Don'ts ❌ {{{
+
+1. **No uses HTTPS si ya tienes SSH key** (menos eficiente)
+2. **No olvides `-u` en primer push** (o tendrás que hacerlo después)
+3. **No nombres remotes al azar** (usa convenciones: origin, upstream)
+4. **No mezcles accounts** (verifica `gh auth status`)
+5. **No hagas push a upstream** en forks (push a origin, PR a upstream)
+6. **No ignores los mensajes de tracking** (son útiles)
+
+}}}
+
+### Pro Tips 🚀 {{{
+
+**Aliases útiles:**
+```bash
+# Agregar a ~/.gitconfig
+[alias]
+  pushup = push -u origin HEAD
+  track = branch -u origin/main
+  remotes = remote -v
+```
+
+**Ahora puedes:**
+```bash
+git pushup    # Push con upstream automático
+git track     # Set tracking rápido
+git remotes   # Ver remotes (más corto)
+```
+
+**Workflow aliases para `gh`:**
+```bash
+# Agregar a ~/.zshrc o ~/.bashrc
+alias ghc='gh repo create'
+alias ghv='gh repo view --web'
+alias prc='gh pr create'
+alias prm='gh pr merge --squash'
+```
+
+}}}
+
+}}}
+
+## 🔗 Recursos Adicionales {{{
+
+- **Docs oficiales:** `gh help` o https://cli.github.com
+- **Man pages:** `man gh`, `man git-remote`
+- **SSH setup:** https://docs.github.com/en/authentication/connecting-to-github-with-ssh
+- **Git book:** https://git-scm.com/book/en/v2
+- **Icarus exercises:** `creta sintaxis` para más lecciones
+
+}}}
+
+---
+
+**Remember:** `gh` no reemplaza a `git`, lo complementa. Domina ambos para workflows eficientes. 🚀