Proyecto: desplegar el Team Builder

# Tier ok — el mínimo para estar en producción
#
# Un único job hace todo el trabajo: obtiene el código, instala dependencias,
# construye la app y la publica en GitHub Pages.
#
# La app está online y accesible en tu URL de Pages. Eso ya es un logro real.
#
# Límite de este tier: el job no ejecuta lint ni tests antes de construir.
# Si introduces un error de TypeScript, un test roto o una regla de ESLint violada,
# el workflow lo ignora y publica igualmente. Para que el código roto no llegue a
# producción hace falta separar CI y CD en jobs distintos, como hacen los tiers
# siguientes.

name: CI/CD

# Solo se ejecuta en push a main.
# Los pull requests no disparan este workflow: no hay verificación previa al merge.
on:
  push:
    branches:
      - main

# Permisos que GitHub Pages necesita para publicar desde un workflow.
# contents: read permite al job leer el código del repositorio.
# pages: write permite subir el artifact a GitHub Pages.
# id-token: write es necesario para que deploy-pages se autentique con el entorno.
permissions:
  contents: read
  pages: write
  id-token: write

# concurrency evita que dos deploys corran a la vez sobre el mismo entorno de Pages.
# cancel-in-progress: false deja que el deploy en curso termine antes de empezar otro:
# un deploy a medias puede dejar la app en un estado inconsistente.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Un solo job que construye y despliega sin verificación previa.
  build-and-deploy:
    runs-on: ubuntu-latest

    # environment registra este job como despliegue en el entorno github-pages.
    # GitHub muestra un historial de despliegues y protecciones de entorno aquí.
    environment:
      name: github-pages
      # steps.deployment.outputs.page_url lo devuelve actions/deploy-pages
      # con la URL final donde la app queda publicada
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Obtener el código
        uses: actions/checkout@v6

      - name: Instalar pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Configurar Node.js con caché de pnpm
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: 'pnpm'

      - name: Instalar dependencias
        run: pnpm install --frozen-lockfile

      # IMPORTANTE: vite.config.ts debe tener base: '/team-builder/' con el nombre
      # exacto de tu repositorio. Sin esa línea, Vite genera rutas absolutas
      # (/assets/index-xxxx.js) que el navegador resuelve contra la raíz del dominio,
      # no contra el subdirectorio de Pages, y la app carga en blanco con errores 404.
      - name: Construir la app
        run: pnpm build

      # configure-pages prepara el entorno de Pages y calcula la URL base.
      # Debe ejecutarse antes de subir el artifact.
      - name: Configurar GitHub Pages
        uses: actions/configure-pages@v5

      # upload-pages-artifact empaqueta el contenido de dist/ como artifact de Pages.
      # El dist/ ya contiene el manifest.json, el service worker y las meta
      # tags del index.html: el pipeline los arrastra del build, no los toca.
      - name: Subir dist/ como artifact de Pages
        uses: actions/upload-pages-artifact@v4
        with:
          path: dist/

      # deploy-pages publica el artifact en GitHub Pages y devuelve la URL final.
      # id: deployment permite referenciar su output en environment.url más arriba.
      - name: Desplegar en GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# Tier mejor — CI y CD separados: el código roto no llega a producción
#
# Supera al tier ok en dos aspectos clave:
#
# 1. Dos jobs separados: ci y deploy.
#    El job ci ejecuta lint, tests y build (con caché de pnpm para ir más rápido).
#    El job deploy tiene needs: ci, así que solo arranca si ci terminó en verde.
#    Si lint falla o un test revienta, deploy no se ejecuta y la app no se publica.
#
# 2. El workflow corre en dos eventos: push y pull_request.
#    En los pull requests, solo corre ci (deploy no arranca porque github.ref no es main).
#    Ese ci es el status check que configuras en branch protection (Settings > Branches >
#    Add branch protection rule > "Require status checks to pass before merging"):
#    cuando lo activas, GitHub bloquea el botón "Merge" hasta que ci pase en verde.
#    El resultado: ningún commit llega a main sin haber pasado lint y tests.
#
# Diferencia con el tier excelente: ci corre en una única versión de Node (24),
# no en una matrix. El deploy reutiliza el dist/ construido por ci vía artifact
# (evita construir dos veces), pero sin la URL expuesta en la interfaz de Actions.

name: CI/CD

# push a main dispara ci + deploy (si ci pasa).
# pull_request dispara solo ci, que actúa como status check del PR.
on:
  push:
    branches:
      - main
  pull_request:

# Permisos que GitHub Pages necesita para publicar.
permissions:
  contents: read
  pages: write
  id-token: write

# cancel-in-progress: false protege los deploys en curso.
# Un deploy de Pages a medias podría dejar la app en estado inconsistente,
# así que dejamos que termine antes de iniciar otro.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Job 1: verificación y construcción.
  # Corre en todos los push y en todos los pull requests.
  ci:
    runs-on: ubuntu-latest

    steps:
      - name: Obtener el código
        uses: actions/checkout@v6

      - name: Instalar pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      # cache: 'pnpm' le indica a setup-node que guarde node_modules en caché
      # usando el lockfile como clave. Si el lockfile no cambia entre runs,
      # pnpm install tarda segundos en vez de minutos.
      - name: Configurar Node.js con caché de pnpm
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: 'pnpm'

      - name: Instalar dependencias
        run: pnpm install --frozen-lockfile

      - name: Linting
        run: pnpm lint

      - name: Ejecutar tests
        run: pnpm test

      # IMPORTANTE: vite.config.ts debe tener base: '/team-builder/' con el nombre
      # exacto de tu repositorio en GitHub. Sin esa línea la app carga en blanco.
      - name: Construir la app
        run: pnpm build

      # Solo subimos el artifact si el job va a desembocar en un deploy.
      # En los pull requests este paso se salta: no necesitamos el artifact
      # porque deploy no va a correr. La condición usa github.ref para
      # detectar si estamos en main o en una rama de PR.
      - name: Subir dist/ como artifact de Pages
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-pages-artifact@v4
        with:
          path: dist/

  # Job 2: publicación en GitHub Pages.
  # Solo corre cuando ci pasa Y el push fue a main.
  # En pull requests, deploy no se ejecuta aunque ci pase: la condición
  # github.ref == 'refs/heads/main' la descarta.
  deploy:
    # needs: ci significa que este job espera a que ci termine.
    # Si ci falla, deploy se cancela automáticamente sin necesidad de condiciones
    # adicionales; la condición if añade el segundo requisito: que sea main.
    needs: ci
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest

    environment:
      name: github-pages

    steps:
      - name: Configurar GitHub Pages
        uses: actions/configure-pages@v5

      # deploy-pages descarga automáticamente el artifact subido por
      # upload-pages-artifact en el mismo workflow y lo publica.
      # No hace falta checkout ni build: el dist/ ya está verificado por ci.
      - name: Desplegar en GitHub Pages
        uses: actions/deploy-pages@v4

# Tier excelente — matrix, URL visible y secrets documentados
#
# Supera al tier mejor en tres aspectos:
#
# 1. Matrix de Node en ci: lint, tests y build corren en paralelo sobre Node 22 y
#    Node 24 en cada push y en cada pull request. Si una API de Node cambia de
#    comportamiento entre versiones lo detectas antes de que llegue a producción.
#    En la pestaña Actions aparecen dos jobs simultáneos, uno por versión, cada uno
#    con su propio log. Es el mismo status check que configuras en branch protection
#    para bloquear el merge de un PR hasta que ambas versiones pasen en verde.
#
# 2. La URL publicada aparece en la interfaz de GitHub Actions al terminar el deploy,
#    sin tener que ir a Settings > Pages para encontrarla. La produce el output
#    page_url de actions/deploy-pages, expuesto en environment.url.
#
# 3. Documentación de variables de entorno y secrets en el paso de build del deploy:
#    qué es público (VITE_), qué nunca puede ir al bundle y cómo proteger datos
#    sensibles con un backend intermedio.
#
# El job deploy reconstruye la app sobre el mismo commit que ci verificó.
# Un build de Vite es determinista: dado el mismo código y las mismas dependencias
# produce el mismo bundle. Lo que ci prueba es lo que deploy publica.
# El dist/ que sube upload-pages-artifact ya contiene el manifest.json,
# el service worker (de public/) y las meta tags del index.html (caps. 5 y 6):
# el pipeline los arrastra del build, no los toca ni los genera.
#
# Este es el ciclo completo: del commit al deploy.
# Un push en una rama abre un PR → ci verifica en Node 22 y 24 → branch protection
# bloquea el merge si falla → mergeas a main → deploy reconstruye y publica →
# la URL de Pages muestra tu Team Builder, instalable y offline.

name: CI/CD

# push a main dispara ci (matrix Node 22 y 24) + deploy (si ci pasa).
# pull_request dispara solo ci con la misma matrix: es el status check del PR.
on:
  push:
    branches:
      - main
  pull_request:

# Permisos que GitHub Pages necesita para publicar.
permissions:
  contents: read
  pages: write
  id-token: write

# cancel-in-progress: false protege los deploys en curso.
# Un deploy de Pages interrumpido puede dejar la app en estado inconsistente.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Job 1: verificación en matrix de Node 22 y 24.
  # Corre en todos los push a main y en todos los pull requests.
  # Es verificación pura: lint, tests y build. No sube ningún artifact.
  ci:
    runs-on: ubuntu-latest

    # strategy.matrix define una rejilla de combinaciones que GitHub ejecuta en paralelo.
    # Con dos versiones de Node se lanzan dos jobs simultáneos: uno con Node 22 y otro con Node 24.
    # Ambos deben pasar en verde para que branch protection permita el merge del PR.
    strategy:
      matrix:
        node-version: [22, 24]

    steps:
      - name: Obtener el código
        uses: actions/checkout@v6

      - name: Instalar pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      # ${{ matrix.node-version }} inyecta el valor de Node activo en este job.
      # En el job con Node 22 vale "22"; en el job con Node 24 vale "24".
      # cache: 'pnpm' guarda node_modules con el lockfile como clave.
      - name: Configurar Node.js ${{ matrix.node-version }} con caché de pnpm
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'pnpm'

      - name: Instalar dependencias
        run: pnpm install --frozen-lockfile

      - name: Linting
        run: pnpm lint

      - name: Ejecutar tests
        run: pnpm test

      - name: Construir la app
        run: pnpm build

  # Job 2: publica la app en GitHub Pages.
  # Solo corre cuando ci terminó en verde Y el push fue a main.
  # En pull requests, deploy no se ejecuta: la condición github.ref lo descarta.
  deploy:
    # needs: ci espera a que todos los jobs de la matrix de ci terminen.
    # Si cualquiera de los dos (Node 20 o Node 22) falla, deploy se cancela.
    needs: ci
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest

    # environment con url expone la dirección publicada en la interfaz de Actions.
    # Al terminar el job, GitHub muestra un enlace directo a la app desplegada
    # en el resumen del workflow, sin necesidad de ir a Settings > Pages.
    environment:
      name: github-pages
      # steps.deployment.outputs.page_url lo devuelve actions/deploy-pages
      # con la URL final donde la app queda publicada
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Obtener el código
        uses: actions/checkout@v6

      - name: Instalar pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      # Los jobs corren en máquinas limpias y separadas: deploy no hereda nada de ci.
      # Por eso reconstruye la app desde cero con los mismos pasos.
      # El build de Vite es determinista: el mismo código produce el mismo bundle.
      - name: Configurar Node.js con caché de pnpm
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: 'pnpm'

      - name: Instalar dependencias
        run: pnpm install --frozen-lockfile

      # IMPORTANTE: vite.config.ts debe tener base: '/team-builder/' con el nombre
      # exacto de tu repositorio en GitHub. Sin esa línea, Vite genera rutas absolutas
      # (/assets/index-xxxx.js) que el navegador resuelve contra la raíz del dominio,
      # no contra el subdirectorio de Pages, y la app carga en blanco con errores 404.
      #
      # -----------------------------------------------------------------------
      # VARIABLES DE ENTORNO Y SECRETS EN UN DEPLOY ESTÁTICO
      # -----------------------------------------------------------------------
      # Las variables VITE_ se incrustan en el bundle durante el build.
      # Son cadenas de texto dentro de un fichero .js que cualquiera puede leer:
      # la URL de una API pública, el nombre del proyecto, una clave de analytics
      # sin privilegios. Son adecuadas para configuración no sensible.
      #
      # NUNCA pongas en una variable VITE_ un secret de verdad:
      # una clave privada de API, un token de acceso, una contraseña de base de datos,
      # un secreto de firma de JWT. En un deploy estático no hay servidor donde
      # esconderlo: el secret termina en el bundle, en el navegador del usuario y,
      # por tanto, en manos de cualquiera que abra las DevTools.
      #
      # Si tu app necesita operar con datos sensibles, la arquitectura correcta es:
      # el cliente llama a un endpoint de tu propio backend, que sí tiene entorno
      # de servidor seguro (variables de entorno reales, no incrustadas en el bundle),
      # y ese backend es el único que usa el secret para llamar a la API externa.
      # El cliente nunca ve la clave.
      #
      # Para pasar una variable VITE_ en el workflow, declárala como secret en
      # Settings > Secrets and variables > Actions y úsala así en el paso de build:
      #   env:
      #     VITE_API_URL: ${{ secrets.VITE_API_URL }}
      # -----------------------------------------------------------------------
      - name: Construir la app
        run: pnpm build

      - name: Configurar GitHub Pages
        uses: actions/configure-pages@v5

      # upload-pages-artifact empaqueta el contenido de dist/ como artifact de Pages.
      # El dist/ ya contiene el manifest.json, el service worker y las meta
      # tags del index.html: el build los arrastra, el pipeline no los toca.
      - name: Subir dist/ como artifact de Pages
        uses: actions/upload-pages-artifact@v4
        with:
          path: dist/

      # deploy-pages publica el artifact en GitHub Pages y devuelve la URL final.
      # id: deployment permite referenciar su output page_url en environment.url.
      - name: Desplegar en GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4