Hoy quiero celebrar algo que todavía me cuesta un poco creer: hemos llegado a los 100.000 suscriptores en YouTube 🥹

Y digo “hemos” porque esto no ha sido algo que haya pasado de la noche a la mañana, ni algo que haya hecho sola.

Empecé este camino un 25 de julio de 2023. Desde entonces, prácticamente todos los miércoles —salvo un par de semanas en todo este tiempo— he publicado un nuevo vídeo sobre temas que me apasionan: desarrollo, tecnología, GitHub, inteligencia artificial, contenedores, productividad… y todo aquello que creo que puede ayudar a otros developers a aprender, mejorar o simplemente atreverse a probar algo nuevo.

Y no te voy a engañar: empecé con muchísimos miedos:

• Miedo a no hacerlo bien.
• Miedo a que me criticaran.
• Miedo a no saber explicarme.
• Miedo a que las transiciones no fueran perfectas.
• Miedo a que la portada no estuviera a la altura.
• Miedo a no tenerlo todo bajo control.

En resumen: miedo a no hacerlo perfecto.

Pero después de casi tres años, si algo he aprendido es esto:

Hazlo. Aunque no sea perfecto. Aunque no tengas el 100%. Aunque te dé vergüenza. Aunque pienses que todavía no estás listx.

Porque muchas veces lo único que realmente nos limita en esta vida somos nosotros mismos.

Mirando atrás, me emociona pensar en todos esos vídeos grabados a ratos, muchas veces cansada, muchas veces dudando, muchas veces pensando si merecía la pena seguir. Vídeos que he grabado incluso estando enferma, parando 20 veces para toser, para recuperar la voz o simplemente porque no me encontraba bien, pero aun así intentando cumplir con ese miércoles que ya se había convertido en una promesa conmigo misma y con la gente que estaba al otro lado.

Y hoy, al ver ese número, siento que cada miércoles, cada intento, cada error, cada parada y cada aprendizaje han tenido sentido.

Pero este logro no es solo mío.

Quiero dar las gracias, de corazón, a Kiko de Angel Gimeno , mi pareja, porque ha estado ahí desde el minuto uno.

Por apoyarme incluso cuando yo no tenía claro hacia dónde iba todo esto. Por ocuparse de mil cosas, de nuestra pequeña, para que yo pudiera grabar. Por aguantar mis 20.000 vueltas a una idea, a un guion, a un vídeo o a una portada. Por animarme, y consolarme, cuando me sentía superada. Por darme espacio para crear, probar, equivocarme y seguir.

Cuando tienes una familia, trabajo, responsabilidades y la vida va siempre a mil, encontrar tiempo para construir algo propio es mucho más difícil de lo que parece. Y sentir que tienes a alguien al lado que te apoya, que te ayuda y que cree en ti incluso cuando tú dudas, lo cambia todo.

Sin él, muchas veces no habría encontrado ni el tiempo ni la motivación para continuar.

Así que estos 100.000 suscriptores son tan tuyos como míos.

Kiko, te quiero muchísimo. Gracias por todo.

Gracias también a cada persona que ha visto un vídeo, ha dejado un comentario, ha compartido contenido, me ha escrito para decirme que algo le ayudó o simplemente ha estado ahí miércoles tras miércoles.

De verdad: gracias.

Y si tú estás pensando en empezar algo, pero estás esperando a tenerlo perfecto, a sentirte preparada o a que llegue el momento ideal… ojalá esto te sirva como recordatorio:

Empieza. Hazlo con miedo. Hazlo imperfecto. Pero hazlo.

Porque a veces, lo que empieza con vergüenza, dudas y una cámara encendida en una habitación cualquiera, acaba convirtiéndose en algo mucho más grande de lo que imaginabas.

Gracias, developers ❤️

La entrada 100.000 gracias, developers ❤️ se publicó primero en return(GiS);.

¡Ah! y también lo he creado para Windows, ¡ver más abajo!

Si quieres saber más sobre el CLI de este asistente aquí te dejo un vídeo de mi canal de YouTube donde repaso sus características principales:

Como puedes ver, en la parte inferior estoy mostrando varias métricas que me dicen: si estoy conectada por cable o no, cómo va la CPU, la memoria RAM, espacio en disco y por último el tiempo en mi zona y lo que estoy escuchando en Spotify 😃.

En tu caso podría ser esto o cualquier otra cosa que consideres útil. Lo importante en este punto es que sepas qué es lo que espera GitHub Copilot CLI. como prepararlo todo.

¿Cómo funciona el statusline de Copilot CLI?

GitHub Copilot CLI tiene una funcionalidad experimental que permite ejecutar un script externo y mostrar su salida como statusline. En cada render tick, o lo que es lo mismo cada vez que refresca el terminal:

1. Ejecuta tu script como un subproceso
2. Le envía un JSON payload por stdin (con info de la sesión, modelo, tokens…)
3. Renderiza lo que tu script imprima por stdout

Esto nos da total libertad para mostrar lo que queramos: el tiempo, música, métricas del sistema… ¡lo que se te ocurra! Lo que si que es importante en este punto es que si no tienes activadas las funcionalidades experimentales debes entrar en una sesión y escribir:

/experimental on

El script: ~/.copilot/statusline.sh

Como al final el script se me ha quedado un poco largo… no mucho… solo 295 líneas ¡pero con muchos comentarios! lo he dejado en este gist. Así que lo único que tienes que hacer es copiarlo o descargarlo y con él crea el archivo ~/.copilot/statusline.sh con el contenido y darle permisos de ejecución (chmod +x):

chmod +x ~/.copilot/statusline.sh

Si te interesa saber cómo se ha conseguido cada métrica puedes seguir por aquí abajo 👇🏻 sino puedes saltar al final para ver cómo es el pegamento entre GitHub Copilot CLI y este nuevo archivo.

¿Cómo se monta cada métrica?

Cada sección del statusline recoge una información diferentes de mi máquina:

🔌 / 🔋 Batería

Detecta si estás en un Mac de sobremesa (muestra «🔌 AC») o en un portátil (muestra el porcentaje con icono de carga ⚡ si está enchufado)

# ── Batería ──────────────────────────────────────────────
# Usa pmset para leer el estado de energía.
# En un Mac de sobremesa (sin batería) muestra "🔌 AC".
# En un portátil muestra el porcentaje + icono de carga.
get_battery() {
  local raw
  raw=$(pmset -g batt 2>/dev/null) || { safe; return; }

  local pct
  pct=$(echo "$raw" | grep -oE '[0-9]+%' | head -1 | tr -d '%')

  # Mac de sobremesa o sin información de batería
  if [[ -z "$pct" ]]; then
    if echo "$raw" | grep -qi "AC Power"; then
      echo "🔌 AC"
    else
      safe
    fi
    return
  fi

  # Icono según nivel de batería
  local icon state_icon
  if (( pct >= 50 )); then icon="🔋"
  elif (( pct >= 20 )); then icon="🪫"
  else icon="🪫"
  fi

  # ⚡ si está cargando o conectado a corriente
  if echo "$raw" | grep -qi "charging\|AC Power"; then
    state_icon="⚡"
  else
    state_icon=""
  fi

  echo "${icon} ${pct}%${state_icon:+ ${state_icon}}"
}

⚙️ CPU

Porcentaje de uso con indicador de color — 🟢 normal, 🟡 medio, 🔴 alto

# ── Uso de CPU ───────────────────────────────────────────
# `top` en macOS da una primera muestra poco fiable: suele representar
# el uso acumulado desde que arrancó el sistema. Por eso pedimos dos
# muestras (`-l 2`) y nos quedamos con la segunda, que refleja mejor el
# uso actual de CPU.
#
# Tomamos el porcentaje idle y calculamos: uso = 100 - idle.
# Así evitamos depender del formato exacto de user/sys.
#
# Color: 🟢 menos de 50% │ 🟡 50-79% │ 🔴 80% o más
get_cpu() {
  local cpu_line
  cpu_line=$(top -l 2 -n 0 2>/dev/null | grep "CPU usage" | tail -1) || { safe; return; }

  # Extraer el % idle (siempre es el último valor antes de "idle")
  local idle total
  idle=$(echo "$cpu_line" | awk '{for(i=1;i<=NF;i++) if($i=="idle") print $(i-1)}' | tr -d '%')
  [[ -z "$idle" ]] && { safe; return; }

  total=$(awk "BEGIN { t=100-${idle}; if(t<0) t=0; if(t>100) t=100; printf \"%.0f\", t }")

  local icon
  if (( total >= 80 )); then icon="🔴"
  elif (( total >= 50 )); then icon="🟡"
  else icon="🟢"
  fi

  # Ancho fijo (3 caracteres) en el porcentaje: "  9%", " 19%", "100%".
  # Mantiene constante el número de dígitos para que al pasar de "100%"
  # a "19%" no queden dígitos residuales del render anterior.
  printf '⚙️  %3d%% %s' "$total" "$icon"
}

🧠 RAM

Memoria RAM en uso

# ── RAM ──────────────────────────────────────────────────
# vm_stat devuelve páginas de memoria (no bytes directamente).
# Multiplicamos por el tamaño de página (4096 bytes en macOS)
# y sumamos: activa + wired + comprimida = RAM "en uso real".
get_ram() {
  local total_bytes vm page_size stats active wired compressed
  total_bytes=$(sysctl -n hw.memsize 2>/dev/null) || { safe; return; }
  vm=$(vm_stat 2>/dev/null) || { safe; return; }

  page_size=$(echo "$vm" | awk '/page size of/ { for (i=1; i<=NF; i++) if ($i == "of") { print $(i+1); exit } }')
  [[ -z "$page_size" ]] && { safe; return; }

  stats=$(echo "$vm" | awk '
    /Pages active/ { gsub(/\./, "", $NF); active=$NF }
    /Pages wired/ { gsub(/\./, "", $NF); wired=$NF }
    /Pages occupied by compressor/ { gsub(/\./, "", $NF); compressed=$NF }
    END {
      if (active == "") exit 1
      printf "%d %d %d\n", active, wired, compressed
    }
  ') || { safe; return; }

  read -r active wired compressed <<< "$stats"
  [[ -z "$active" ]] && { safe; return; }
  wired=${wired:-0}
  compressed=${compressed:-0}

  # Convertir páginas a GB: (páginas * tamaño_página) / 1024^3
  local used_gb total_gb
  used_gb=$(awk "BEGIN { printf \"%.1f\", (${active} + ${wired} + ${compressed}) * ${page_size} / 1073741824 }")
  total_gb=$(awk "BEGIN { printf \"%.0f\", ${total_bytes} / 1073741824 }")

  echo "🧠  ${used_gb}/${total_gb}GB"
}

💽 Disco

Espacio libre en el disco principal

# ── Disco ────────────────────────────────────────────────
# Espacio libre en el disco principal (/)
get_disk() {
  local avail
  avail=$(df -h / 2>/dev/null | awk 'NR==2 { print $4 }') || { safe; return; }
  [[ -z "$avail" ]] && { safe; return; }

  echo "💽 ${avail} free"
}

☀️ El tiempo meteorológico

Según tu IP el servicio de wttr.in detecta tu ubicación y te devuelve el resultado el cual puedes modelar.

# ── Tiempo meteorológico ─────────────────────────────────
# Usa wttr.in para obtener la temperatura de tu ciudad.
# No necesita API keys ni instalar nada — se auto-detecta por IP.
# Se cachea 10 minutos porque el tiempo no cambia tan rápido
# y la petición HTTP es más lenta que leer sensores locales.
get_weather() {
  # Comprobar si hay cache válido del tiempo
  if cache_is_fresh "$WEATHER_CACHE_FILE" "$WEATHER_CACHE_TTL"; then
    cat "$WEATHER_CACHE_FILE"
    return
  fi

  # Consultar wttr.in en una sola petición (más rápido)
  # %c = emoji del tiempo (wttr.in lo elige según condición + día/noche)
  # %t = temperatura, %l = localización
  local raw
  raw=$(curl -s --max-time 3 "wttr.in/?format=%c|%t|%l" 2>/dev/null)
  [[ -z "$raw" ]] && { echo "🌡️ —"; return; }

  local icon temp city
  icon=$(echo "$raw" | cut -d'|' -f1 | tr -d ' ')
  temp=$(echo "$raw" | cut -d'|' -f2)
  city=$(echo "$raw" | cut -d'|' -f3 | sed 's/,.*//' | awk '{print toupper(substr($0,1,1)) tolower(substr($0,2))}')

  [[ -z "$temp" ]] && { echo "🌡️ —"; return; }

  local result="${icon} ${temp} ${city}"

  # Guardar en cache del tiempo
  mkdir -p "$(dirname "$WEATHER_CACHE_FILE")"
  echo "$result" > "$WEATHER_CACHE_FILE"
  echo "$result"
}

🎵 Qué estoy escuchando en Spotify

Usando AppleScript te olvidas de tener que usar la API de Spotify.

# ── Spotify ──────────────────────────────────────────────
# Definida al principio del script porque se usa en dos sitios:
# 1) En el path cacheado (para mostrar la canción actual en vivo)
# 2) En el path fresco (cuando se recalculan todas las métricas)
# Usa AppleScript (osascript) para consultar Spotify — no necesita
# API keys ni tokens, funciona nativamente en macOS.
get_spotify() {
  # Primero comprobamos si Spotify está corriendo, para no lanzarlo
  # accidentalmente (osascript abriría la app si no hacemos esta comprobación)
  local running
  running=$(osascript -e 'tell application "System Events" to (name of processes) contains "Spotify"' 2>/dev/null)
  [[ "$running" != "true" ]] && return 1

  local info state track artist rest
  info=$(osascript <<'APPLESCRIPT' 2>/dev/null
tell application "Spotify"
  set playbackState to player state as string
  if playbackState is not "playing" and playbackState is not "paused" then return ""
  return playbackState & linefeed & (name of current track) & linefeed & (artist of current track)
end tell
APPLESCRIPT
  ) || return 1

  [[ -z "$info" ]] && return 1
  state=${info%%$'\n'*}
  rest=${info#*$'\n'}
  track=${rest%%$'\n'*}
  artist=${rest#*$'\n'}
  [[ "$state" != "playing" && "$state" != "paused" ]] && return 1
  [[ -z "$track" ]] && return 1

  # Truncar nombres largos para que el statusline quepa en pantalla
  (( ${#track} > 25 )) && track="${track:0:22}..."
  (( ${#artist} > 20 )) && artist="${artist:0:17}..."

  # 🎵 si está sonando, ⏸️ si está en pausa
  local icon="🎵"
  [[ "$state" == "paused" ]] && icon="⏸️"

  echo "${icon} ${track} – ${artist}"
}

add_live_spotify() {
  local line="$1" spotify
  spotify=$(get_spotify 2>/dev/null)
  [[ -n "$spotify" ]] && line="${line} │ ${spotify}"
  echo "$line"
}

El truco del cache

Copilot CLI ejecuta el script en cada render tick. Si cada ejecución tardara 10-15 segundos la experiencia sería horrible. Por eso el script implementa un sistema de cache:

• Guarda el resultado en ~/.copilot/.system-statusline.cache
• Si el cache tiene menos de 30 segundos, devuelve el valor cacheado en lugar de recalcular
• El TTL es configurable con la variable de entorno SYSTEM_CACHE_TTL

Configurar GitHub Copilot CLI

Con el script ya en su sitio lo último que te queda por hacer es editar tu archivo ~/.copilot/settings.json y añade la configuración del statusline. Desde aquí también puedes habilitar el modo experimental:

{
  "experimental": true,
  "statusLine": {
    "type": "command",
    "command": "~/.copilot/statusline.sh",
    "padding": 1
  },
  "footer": {
    "showCustom": true
  }


}

Después, reinicia Copilot CLI con /restart o abre una nueva sesión. ¡Y listo! Verás las métricas de tu sistema, el tiempo y tu música directamente en la barra inferior.

Lo mismo pero para Windows

Si tu sistema operativo es Windows, te dejo también este gist donde puedes ver la versión compatible para PowerShell. Y así es como se ve:

¡Nos vemos 👋🏻!

La entrada Cómo crear un status line personalizado para GitHub Copilot CLI se publicó primero en return(GiS);.

La semana pasada te compartí en mi canal de YouTube cómo puedes usar Visual Studio Code conectándote de forma remota desde la web o incluso desde otro Visual Studio Code.

Esto es súper útil cuando estás trabajando con diferentes entornos y no quieres estar cambiando constantemente de ventana, o simplemente cuando necesitas acceder a esa máquina y no tienes la físicamente delante.

Te dejo por aquí el vídeo por si quieres verlo 👇🏻

Pero hoy quería enseñarte otra posibilidad bastante interesante: cómo crear un túnel usando la CLI de Visual Studio Code sin necesidad de tener Visual Studio Code instalado en la máquina destino 🤯

La idea es poder acceder desde el navegador, u otra máquina con VS Code instalado, a un entorno remoto donde estás haciendo algún desarrollo, pero esa máquina no tiene interfaz gráfica o no tiene expuesto directamente el puerto de la aplicación.

Esto me ha pasado recientemente con una máquina Ubuntu donde estaba haciendo pruebas con GitHub Copilot CLI —pero eso da para otro vídeo/artículo 😅— y necesitaba revisar de forma sencilla el contenido del proyecto. Además, quería acceder a uno de los puertos donde la aplicación estaba escuchando para ver el resultado en el navegador, pero ese puerto no estaba abierto públicamente en la máquina, y tampoco quería exponerlo de forma insegura.

Así que en este artículo te muestro cómo instalar solamente la CLI de Visual Studio Code y abrir un túnel para acceder a tu máquina de forma remota a través de Visual Studio Code.

Requisitos

Para seguir este ejemplo necesitas:

• Una máquina Linux con curl y tar
• Una cuenta de GitHub para autenticar el túnel

Instalación de la CLI de Visual Studio Code

Lo primero que vamos a hacer es descargar la CLI de Visual Studio Code en la máquina remota.

mkdir -p ~/.local/bin

TMP_DIR=$(mktemp -d)

# Descarga de la CLI de Visual Studio Code
# Algunas distribuciones pueden requerir el paquete "alpine"

curl -fsSL "https://code.visualstudio.com/sha/download?build=stable&os=cli-linux-x64" \
  -o "$TMP_DIR/vscode-cli.tar.gz" || \
curl -fsSL "https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64" \
  -o "$TMP_DIR/vscode-cli.tar.gz"

tar -xzf "$TMP_DIR/vscode-cli.tar.gz" -C "$TMP_DIR"

install -m 755 "$(find "$TMP_DIR" -maxdepth 3 -type f -name code | head -n 1)" \
  "$HOME/.local/bin/code"

~/.local/bin/code --version

Con esto ya deberías tener disponible el comando code en tu máquina destino 🎉

Crear y autenticar el túnel

Una vez instalada la CLI, podemos crear el túnel con el siguiente comando:

~/.local/bin/code tunnel \
  --accept-server-license-terms \
  --telemetry-level off \
  --name returngis-web

Al ejecutarlo, Visual Studio Code te mostrará un device code, para hacer la autenticación, y la URL a la que debes acceder para asociar el nuevo túnel a tu cuenta de GitHub.

Verificar el estado del túnel

Cuando el túnel esté creado, puedes comprobar su estado ejecutando:

~/.local/bin/code tunnel status

Si todo ha ido bien, ya podrás acceder a tu máquina remota desde el navegador, o un VS Code, usando una URL como esta: https://vscode.dev/tunnel/returngis-web

En este caso, returngis-web es el nombre que le hemos dado al túnel con el parámetro --name.

¿Y por qué mola esto?

Lo interesante de este enfoque no es solamente que puedas abrir un túnel para acceder al desarrollo que estás ejecutando en una máquina remota.

Lo potente es que, además, tienes un Visual Studio Code completo en el navegador conectado a esa máquina.

Desde ahí puedes revisar el código, abrir terminales, inspeccionar archivos y trabajar sobre ese entorno sin tener que exponer puertos públicamente ni instalar una interfaz gráfica en la máquina destino.

Para escenarios donde estás probando cosas en servidores Linux, máquinas temporales, entornos cloud o incluso laboratorios con herramientas como GitHub Copilot CLI, esto puede ahorrarte tiempo.

¡Nos vemos 👋🏻!

La entrada VS Code Tunnels sin instalar VS Code: accede a tu máquina remota desde el navegador se publicó primero en return(GiS);.

Cuando trabajas con GitHub Copilot en modo agente, el agente puede leer y escribir archivos, ejecutar comandos y tomar decisiones de forma autónoma.

Y eso está genial… hasta que te haces la pregunta incómoda:

👉 ¿Qué pasa con la calidad del código que genera?
👉 ¿Y con el formato?

Aquí es donde entran en juego los Agent hooks.

Estos no son más que «pequeños scripts» que se ejecutan automáticamente en momentos clave del ciclo de vida del agente, sin que tengas que pedírselo.
En este artículo te comparto dos que estoy usando muchísimo en proyectos JavaScript/TypeScript… y que ya se han vuelto imprescindibles en mi flujo de trabajo.

Si quieres verlos en acción, aquí tienes el vídeo completo 👇🏻

¿Qué son los agent hooks?

Los hooks son scripts que se ejecutan en distintos momentos del ciclo de vida de una sesión de agente.

Aunque hay varios eventos disponibles, los que más estoy utilizando son:

• preToolUse → justo antes de que el agente use una herramienta (por ejemplo, antes de modificar un archivo)
• postToolUse → justo después de que la use

Se configuran en un archivo .github/hooks/hooks.json dentro del repositorio:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": ".github/hooks/scripts/lint.sh"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": ".github/hooks/scripts/format.sh"
      }
    ]
  }
}

El nombre del JSON puede ser diferente a hooks.json y dentro de este cada evento es un array por lo que podrías tener más de un script asociado a ese momento.

Hook de lint (preToolUse)

El hook lint.sh se ejecuta antes de que el agente escriba o modifique un archivo. En este ejemplo, su función es pasar ESLint sobre el archivo en cuestión y, si hay errores, bloquear la operación devolviendo una decisión de deny.

Los hooks reciben un JSON por stdin con información sobre la herramienta que se va a usar y sus parámetros. El script extrae el nombre de la herramienta y la ruta del archivo, y solo actúa en herramientas de escritura (replace_string_in_file, create_file, etc.):

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# 🔍 LINT — Verifica la calidad del código antes de escribir
# 📌 Se ejecuta en: preToolUse (antes de que el agente
#    escriba o modifique un archivo)
# 🛠️ Herramienta: ESLint
# ─────────────────────────────────────────────────────────────

# ── Helpers para responder al hook ──────────────────────────

allow() {
  jq -n --arg reason "$1" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "allow",
      permissionDecisionReason: $reason
    }
  }'
  exit 0
}

deny() {
  jq -n --arg reason "$1" --arg context "$2" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: $reason,
      additionalContext: $context
    }
  }'
  exit 1
}

# ── Lógica principal ────────────────────────────────────────

INPUT=$(cat)

TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
FILE=$(echo "$INPUT" | jq -r '.tool_input.filePath // empty')

# Solo lint en herramientas que escriben archivos
[[ "$TOOL_NAME" =~ ^(replace_string_in_file|multi_replace_string_in_file|create_file|run_in_terminal|run_task)$ ]] \
  || allow "⏭️ Read-only tool, no lint needed"

# Necesitamos una ruta de archivo
[ -z "$FILE" ] && allow "⏭️ No filePath in input"

# Solo lint en archivos JS/TS/Astro
EXT="${FILE##*.}"
[[ "$EXT" =~ ^(js|jsx|ts|tsx|astro)$ ]] || allow "⏭️ No es un archivo JS/TS/Astro"

# El archivo debe existir
[ ! -f "$FILE" ] && deny "⚠️ File not found: $FILE" ""

# Verificar que eslint está disponible
command -v npx &> /dev/null || allow "⚠️ npx no disponible — saltando lint"

# Ejecutar ESLint
if LINT_OUTPUT=$(npx eslint "$FILE" 2>&1); then
  allow "✅ Linting passed for $FILE"
else
  deny "❌ Linting failed for $FILE" "$LINT_OUTPUT"
fi

Cuando el hook devuelve deny, el agente recibe el motivo y el contexto adicional (la salida de ESLint), lo que le permite corregir el código antes de volver a intentar la escritura.

Hook de formato (postToolUse)

El hook format.sh se ejecuta después de cada escritura. Llama a Prettier sobre el archivo modificado para garantizar que el formato sea siempre consistente, independientemente de lo que haya generado el agente:

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# ✨ FORMAT — Formatea el código automáticamente después de
#    cada cambio
# 📌 Se ejecuta en: postToolUse (después de que el agente
#    escribe o modifica un archivo)
# 🛠️ Herramienta: Prettier
# ─────────────────────────────────────────────────────────────

INPUT=$(cat)

TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')

# Solo formatear después de herramientas que escriben archivos
if ! [[ "$TOOL_NAME" =~ ^(replace_string_in_file|multi_replace_string_in_file|create_file|run_in_terminal|run_task)$ ]]; then
  echo "[format.sh] ⏭️  Skipped (read-only tool): $TOOL_NAME"
  exit 0
fi

# Extraer rutas de archivo según el tipo de herramienta
if [[ "$TOOL_NAME" == "multi_replace_string_in_file" ]]; then
  FILES=$(echo "$INPUT" | jq -r '.tool_input.replacements[].filePath // empty' | sort -u)
else
  FILES=$(echo "$INPUT" | jq -r '.tool_input.filePath // empty')
fi

if [ -z "$FILES" ]; then
  echo "[format.sh] ⚠️  No filePath found in input"
  exit 0
fi

# Formatear cada archivo
while IFS= read -r FILE; do
  [ -z "$FILE" ] && continue

  # Solo formatear archivos del proyecto web
  EXT="${FILE##*.}"
  if ! [[ "$EXT" =~ ^(js|jsx|ts|tsx|astro|css|html|json|md)$ ]]; then
    echo "[format.sh] ⏭️  No es un archivo formateable: $FILE"
    continue
  fi

  # Verificar que prettier está disponible
  if ! command -v npx &>/dev/null; then
    echo "[format.sh] ⚠️  npx no disponible — saltando format"
    exit 0
  fi

  # El archivo debe existir
  if [ ! -f "$FILE" ]; then
    echo "[format.sh] ⚠️  File not found: $FILE"
    continue
  fi

  # Ejecutar Prettier
  echo "[format.sh] 📝 Formatting: $FILE"

  BEFORE=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE" 2>/dev/null)
  FORMAT_OUTPUT=$(npx prettier --write "$FILE" 2>&1)
  EXIT_CODE=$?
  AFTER=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE" 2>/dev/null)

  if [ $EXIT_CODE -ne 0 ]; then
    echo "[format.sh] ❌ Formatter error: $FORMAT_OUTPUT"
  elif [ "$BEFORE" = "$AFTER" ]; then
    echo "[format.sh] ✅ No changes needed"
  else
    echo "[format.sh] ✨ File formatted successfully"
  fi
done <<< "$FILES"

Como puedes ver en este caso lo primero que revisa es cuál es la tool que se ha ejecutado con el objetivo de solo lanzar prettier cuando tiene sentido, es decir cuando hay nuevo código que debe ser formateado.

Resultado en la práctica

Con estos dos hooks activos, el flujo de trabajo con el agente queda así:

1. Le pido al agente hacer una implementación
2. El agente decide modificar un archivo
3. preToolUse → ESLint analiza los cambios; si hay errores, el agente los corrige antes de escribir
4. El agente escribe el archivo
5. postToolUse → Prettier formatea el resultado automáticamente

Todo esto ocurre de forma transparente, sin interrumpir el flujo del agente ni requerir intervención manual. Aunque en el vídeo te muestro otros ejemplos donde si puedes interactuar con el hook a través del chat.

Una limitación importante

Los hooks solo se disparan cuando el agente usa una herramienta. Si tú editas un archivo directamente desde VS Code o la terminal, los hooks no se ejecutan. Para ese caso, lo mejor es configurar Prettier como formateador por defecto en VS Code con editor.formatOnSave: true.

Conclusión

Los agent hooks son una herramienta sencilla pero muy potente para mantener la calidad del código cuando trabajas con GitHub Copilot en modo agente. Con unas pocas líneas de bash puedes garantizar que todo lo que el agente toque cumpla con tus estándares de calidad, de forma automática y sin fricción. Pero hay muchos otros casos de uso que puedes ver de forma rápida en esta tabla de aquí.

¡Nos vemos 👋🏻!

La entrada Control de calidad en Agentic DevOps: automatiza linting y formateo con hooks se publicó primero en return(GiS);.

Últimamente, además, estoy haciendo bastante uso de GitHub Pages para side projects o demos en las que simplemente necesito servir contenido estático sin complicarme demasiado. Y es que ya te conté en otro artículo que incluso puedes tener repositorios privados que desplieguen en GitHub Pages y que ese contenido sea público… algo que, sinceramente, me está resultando extremadamente útil en mi día a día.

Pero claro… aquí viene la parte que no deberíamos pasar por alto 👀

Porque aunque sea “solo estático”, seguimos exponiendo una aplicación web al mundo. Y eso implica que la seguridad sigue siendo importante.

En este artículo te voy a contar qué puedes (y qué no puedes) hacer para mejorar la seguridad de un sitio alojado en GitHub Pages, centrándome en una de las herramientas más potentes que tenemos a nuestro alcance: Content Security Policy (CSP).

¿Qué es GitHub Pages y cuáles son sus limitaciones?

GitHub Pages es un servicio de hosting estático que sirve archivos HTML, CSS y JavaScript directamente desde un repositorio de GitHub. No hay servidor backend, no hay base de datos, no hay procesamiento del lado del servidor. Solo archivos estáticos.

Esto tiene muchas ventajas (rapidez, simplicidad, coste cero), pero también una limitación importante para la seguridad: no puedes configurar headers HTTP personalizados. Y los headers HTTP son el mecanismo principal para aplicar políticas de seguridad en la web.

Dicho esto, GitHub Pages sí aplica algunas protecciones por defecto:

• HTTPS forzado con Strict-Transport-Security
• Certificados TLS gestionados automáticamente
• Infraestructura de CDN global

Pero hay muchas cosas que no puedes controlar: X-Frame-Options, Permissions-Policy, o el propio Content-Security-Policy como header. Para eso tenemos un plan B.

¿Qué es Content Security Policy (CSP)?

CSP es un estándar de seguridad web que permite definir qué recursos puede cargar tu página. Funciona como una lista blanca: solo se ejecutan scripts, se cargan estilos, fuentes o se hacen peticiones de red a los orígenes que tú autorices explícitamente.

La forma habitual de aplicar CSP es mediante un header HTTP:

Content-Security-Policy: default-src 'self'; script-src 'self';

Pero como en GitHub Pages no podemos configurar headers, usamos la alternativa: una etiqueta <meta> en el <head> del HTML:

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' 'unsafe-inline';"
/>

El navegador lee esta etiqueta y aplica las mismas restricciones que si viniera como header. No importa si tu hosting es GitHub Pages o cualquier otro. Es el navegador quien lo interpreta.

¿De qué te protege CSP?

El principal ataque que mitiga CSP es Cross-Site Scripting (XSS). Si un atacante consigue inyectar un <script src="https://malicious.com/steal.js"> en tu página, el navegador lo bloqueará porque malicious.com no está en tu lista de orígenes permitidos.

Además, CSP ayuda contra:

• Exfiltración de datos: un script malicioso no puede enviar datos a servidores no autorizados si connect-src está restringido.
• Inyección de estilos: con style-src puedes evitar que se carguen CSS externos maliciosos.
• Carga de recursos no deseados: controlas de dónde vienen las imágenes (img-src), las fuentes (font-src) y todo lo demás.

Ejemplo práctico: un sitio Astro en GitHub Pages

Recientemente construí una aplicación de encuestas anónimas hecha con Astro + React, desplegada en GitHub Pages y estas son las decisiones de seguridad que tomé:

La política CSP que apliqué

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self';
    script-src 'self' 'unsafe-inline';
    style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
    font-src https://fonts.gstatic.com;
    img-src 'self' data:;
    connect-src 'self' https://api.web3forms.com https://api.fpjs.io;
    base-uri 'self';
    form-action 'none';"
/>

Si echamos un vistazo a cada una de las directivas:

Otras meta etiquetas de seguridad

Además del CSP, añadí estas dos:

<!-- Evita enviar el referrer a sitios externos -->
<meta name="referrer" content="no-referrer" />

<!-- Evita que el navegador adivine el MIME type -->
<meta http-equiv="X-Content-Type-Options" content="nosniff" />

Cómo probarlo

Para comprobar que esto que hemos configurado tiene su efecto puedes abrir las DevTools de tu navegador y en la sección de consola podrías intentar añadir algo como esto:

const s = document.createElement('script');
s.src = 'https://evil.example.com/test.js';
document.head.appendChild(s);

Si está bien configurado debería de devolver algo como lo siguiente:

Deberías ver un error de CSP en la consola confirmando que script-src bloquea el recurso. Si no aparece error, la política no se está aplicando.

También es posible confirmar la configuración aplicada yendo a la sección Application > Frames > top y ahí podrás ver una sección sobre la configuración relacionada con Content Security Policy (CSP)

Lo que NO puedes hacer con meta tags

Hay directivas CSP y headers de seguridad que solo funcionan como headers HTTP y no se pueden aplicar via <meta>:

• frame-ancestors: controla quién puede embeber tu página en un iframe. En GitHub Pages no puedes configurarlo.
• Permissions-Policy: restringe el acceso a APIs del navegador (cámara, micrófono, geolocalización). No existe como meta tag.
• X-Frame-Options: la versión legacy de frame-ancestors. Tampoco funciona como meta tag.

Si necesitas control total sobre estos headers, tendrás que considerar un hosting que permita configurar headers HTTP personalizados.

Conclusión

GitHub Pages es una opción más que suficiente para sitios estáticos, y aunque tiene limitaciones al no poder configurar headers HTTP, puedes hacer bastante con meta tags. Un CSP bien configurado via <meta> te protege contra XSS, controla qué recursos se cargan y limita las conexiones salientes.

No esperes a tener un hosting «de pago» para aplicar buenas prácticas de seguridad. Con unas pocas líneas en tu <head> puedes mejorar significativamente la postura de seguridad de tu sitio.

¡Nos vemos 👋🏻!

La entrada Seguridad en GitHub Pages con CSP se publicó primero en return(GiS);.

Y en este artículo quiero dejarte las configuraciones que mostré durante el mismo con su correspondiente explicación para que te sea lo más sencillo posible copiarlas y adaptarlas a tus aplicaciones 😃

Qué es launch.json

launch.json es el archivo donde VS Code guarda las configuraciones de ejecución y depuración de un proyecto. Se encuentra normalmente dentro de la carpeta .vscode en la raíz del repositorio.

Cada entrada dentro de configurations es una receta. Esa receta le dice a VS Code qué debe ejecutar, con qué depurador, desde qué carpeta y con qué comportamiento adicional.

En este ejemplo real, el archivo define cuatro configuraciones principales y un compound:

{
  "configurations": [
    {
      "type": "java",
      "name": "☕ Backend (Spring Boot)",
      "request": "launch"
    },
    {
      "type": "node",
      "name": "🌐 Frontend (Vite Dev Server)",
      "request": "launch"
    },
    {
      "type": "msedge",
      "name": "🔍 Edge: Debug Frontend",
      "request": "launch"
    },
    {
      "type": "editor-browser",
      "name": "🌐 Launch Integrated Browser",
      "request": "launch"
    }
  ],
  "compounds": [
    {
      "name": "🚀 Full Stack (Backend + Frontend)"
    }
  ]
}

Eso ya deja ver algo importante: launch.json no se limita a una sola forma de arrancar cosas. Puede lanzar procesos Java, ejecutar comandos de Node, abrir Edge para depuración o incluso abrir el navegador integrado de VS Code.

La configuración del backend

La primera pieza del ejemplo es el backend en Spring Boot:

{
  "type": "java",
  "name": "☕ Backend (Spring Boot)",
  "request": "launch",
  "mainClass": "com.ideaforge.quickstart.Application",
  "cwd": "${workspaceFolder}/backend",
  "env": {
    "SPRING_PROFILES_ACTIVE": "default"
  },
  "console": "integratedTerminal"
}

Aquí hay varios campos que merece la pena entender:

• type indica que se usará el depurador de Java.
• mainClass señala la clase principal de Spring Boot que se debe lanzar.
• cwd fija la carpeta de trabajo en backend.
• env permite definir variables de entorno, en este caso el perfil activo de Spring.
• console manda la salida al terminal integrado.

Esta configuración sí representa una depuración clásica del backend: VS Code lanza la aplicación Java y puede engancharse al proceso para depurarla.

La configuración del frontend con Vite

La segunda pieza arranca el frontend:

{
  "type": "node",
  "name": "🌐 Frontend (Vite Dev Server)",
  "request": "launch",
  "runtimeExecutable": "npm",
  "runtimeArgs": [
    "run",
    "dev"
  ],
  "cwd": "${workspaceFolder}/frontend",
  "console": "integratedTerminal",
  "skipFiles": [
    "<node_modules>/**"
  ]
}

Aquí el patrón es distinto al de Java. No se está arrancando una clase principal, sino ejecutando npm run dev desde la carpeta frontend. Eso pone en marcha el servidor de desarrollo de Vite.

Este detalle importa porque muchas veces se mezclan dos cosas distintas:

• arrancar el servidor del frontend
• abrir un navegador o una sesión de depuración sobre la aplicación web

En este launch.json esas responsabilidades están separadas, y eso está bien diseñado.

Cómo entra en juego serverReadyAction

La parte más interesante del ejemplo está dentro de la configuración del frontend, donde aparece serverReadyAction:

{
  "type": "node",
  "name": "🌐 Frontend (Vite Dev Server)",
  "request": "launch",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "dev"],
  "cwd": "${workspaceFolder}/frontend",
  "serverReadyAction": {
    "pattern": "Local:.+(https?://\\S+)",
    "uriFormat": "%s",
    "action": "startDebugging",
    "name": "🌐 Launch Integrated Browser"
  }
}

Esto significa que VS Code vigila la salida del proceso de Vite y espera a detectar una línea como la que imprime normalmente el servidor:

Local:   http://localhost:5176/

En cuanto encuentra una URL que encaja con el patrón, dispara otra configuración con action: "startDebugging". En este caso, la configuración que se lanza es 🌐 Launch Integrated Browser.

Aquí sí hay una secuencia real: primero Vite, después el navegador.

La configuración del navegador integrado

La configuración que se dispara cuando Vite está listo es esta:

{
  "name": "🌐 Launch Integrated Browser",
  "request": "launch",
  "type": "editor-browser",
  "url": "http://localhost:5176",
  "webRoot": "${workspaceFolder}"
}

Su función es sencilla: abrir la aplicación dentro del navegador integrado de VS Code, usando la URL local del frontend.

Además del navegador integrado, el archivo también incluye una configuración adicional para Edge:

{
  "type": "msedge",
  "name": "🔍 Edge: Debug Frontend",
  "request": "launch",
  "url": "http://localhost:5176",
  "webRoot": "${workspaceFolder}/frontend/src"
}

Esa configuración está oculta en la presentación habitual y sirve como alternativa cuando interesa depurar en Edge con soporte de source maps, pero no es la que forma parte del flujo automático principal.

Compounds

Si lo que te interesa es ejecutar más de una configuración a la vez, que suele ser lo habitual cuando tienes un backend y un frontend, también te interesará configurar lo que se llaman compounds:

{
  "name": "🚀 Full Stack (Backend + Frontend)",
  "configurations": [
    "☕ Backend (Spring Boot)",
    "🌐 Frontend (Vite Dev Server)"
  ],
  "stopAll": true
}

Esto permite lanzar backend y frontend desde una única entrada. Es cómodo, pero conviene entenderlo bien: el compound no establece dependencia entre ambos procesos. Los dos arranques se lanzan en paralelo.

Eso quiere decir que, en este ejemplo, la secuencia controlada existe entre el frontend y el navegador, pero no entre el backend y el frontend.

Dicho de otra forma:

1. el compound arranca backend y frontend al mismo tiempo
2. Vite termina de levantar su servidor
3. serverReadyAction detecta la URL local
4. VS Code lanza el navegador integrado

Este matiz es importante porque a veces se dice que todo está encadenado cuando en realidad solo una parte del flujo lo está.

Cuándo usar cada pieza

Una forma práctica de pensarlo es esta:

• Usa una configuración normal cuando quieres arrancar una sola pieza, como el backend o el frontend.
• Usa un compound cuando quieres lanzar varias piezas desde una única orden, aunque eso ocurra en paralelo.
• Usa serverReadyAction cuando necesitas reaccionar a una señal real de disponibilidad, como la URL que imprime Vite al arrancar.
• Usa una configuración de navegador separada cuando quieres distinguir claramente entre arrancar un servidor y abrir la interfaz.

Ese reparto de responsabilidades hace que el archivo sea más fácil de mantener y también más fácil de entender por parte de cualquier persona que se incorpore al proyecto.

Si quisieras secuencia completa backend → frontend → navegador

Este ejemplo no hace eso todavía. El backend y el frontend arrancan en paralelo porque así está definido el compound. Si el objetivo fuera esperar a que Spring Boot estuviera listo antes de lanzar Vite, haría falta introducir un encadenado adicional desde la configuración Java o reestructurar el flujo con tareas y dependencias.

Precisamente por eso este archivo es un buen ejemplo didáctico: muestra muy bien la diferencia entre agrupar procesos y secuenciarlos de verdad.

Conclusión

launch.json es mucho más que un archivo para pulsar F5. Bien usado, te permite describir el flujo de arranque real de tu aplicación y reducir bastante la fricción diaria.

La idea más importante es esta: los compounds agrupan, pero no ordenan. El orden real aparece cuando introduces una señal verificable del proceso, como hace aquí serverReadyAction al detectar la URL de Vite y lanzar después el navegador integrado.

Cuando entiendes esa diferencia, launch.json deja de ser un archivo misterioso y se convierte en una herramienta muy potente para automatizar el desarrollo local 🚀

¡Nos vemos 👋🏻!

La entrada Cómo funciona launch.json en VS Code: configuraciones, compounds y arranques secuenciales se publicó primero en return(GiS);.

Cuando Dependabot te abre una pull request de seguridad, lo primero que sabes es esto: una versión concreta de una dependencia está dentro de un rango vulnerable.

Perfecto 👍
Pero… eso no responde a la pregunta importante: ¿esto es realmente explotable en mi código?

Porque una cosa es que exista una advisory…
y otra muy distinta es que tu aplicación esté usando justo ese patrón vulnerable y además se cumplan las condiciones para explotarlo.

Con esa idea en mente he jugado con una prueba de concepto en la que he estado trabajando en el repositorio dependabot-security-analyzer. La idea en este caso es usar un GitHub Agentic Workflow para analizar una PR de Dependabot de forma más profunda: identificar la dependencia afectada, consultar la advisory completa, revisar el repositorio y decidir si el caso merece prioridad alta o si la exposición no está realmente demostrada. En este artículo te muestro cómo lo estoy comprobando gracias a estos nuevos flujos.

Si todavía no has visto qué son los GitHub Agentic Workflows, aquí tienes un vídeo donde te lo explico en 30 minutos:

El problema no es detectar vulnerabilidades (eso ya lo hacemos bien)

Herramientas como Dependabot hacen muy bien la parte de detectar versiones afectadas y proponer actualizaciones. Pero entre “la dependencia es vulnerable” y “mi aplicación es explotable por esa vulnerabilidad” hay bastante distancia. A veces tu código ni siquiera usa la parte afectada. Otras veces sí la usa, pero sin cumplir las condiciones reales del exploit. Y en otros casos sí se da toda la cadena y entonces esa PR merece atención inmediata.

La intención de esta PoC no es discutir si hay que actualizar o no. Las dependencias vulnerables conviene corregirlas igualmente. La cuestión aquí es otra: aportar más contexto para priorizar mejor, reducir ruido y distinguir entre presencia de una advisory y exposición real en el código.

Cómo funciona el workflow

El flujo está definido en lenguaje natural dentro del propio workflow y se activa cuando un usuario de confianza comenta /dependabot-analyze en una pull request. El comando tiene que ser el primer token del comentario. A partir de ahí, el agente solo sigue adelante si el evento está realmente ligado a una PR y si esa PR ha sido abierta por dependabot[bot].

Ese filtro es importante porque el objetivo no es analizar cualquier cambio, sino específicamente pull requests automáticas de seguridad. Si el comentario no está en una PR o la PR no es de Dependabot, el flujo se detiene y deja una explicación breve.

El frontmatter del workflow deja bastante claro cómo está configurado este ejemplo. Aquí se define el trigger, los permisos, las herramientas disponibles, la red permitida y también el engine y el modelo que quiero usar:

---
name: 🛡️ VulnScope PR Guard 🔎

on:
  slash_command:
    name: dependabot-analyze
    events: [pull_request_comment]
  reaction: eyes

permissions:
  contents: read
  pull-requests: read
  security-events: read

tools:
  github:
    toolsets: [context, repos, pull_requests, security_advisories]

network:
  allowed:
    - defaults

engine:
  id: copilot
  model: gpt-4.1

safe-outputs:
  add-labels:
    allowed: ["🔴 vulnerability:in-use", "🟢 vulnerability:not-in-use", "🤔 vulnerability:unclear", "🚨 priority:high", "🕓 priority:low"]
    max: 2
  add-comment:
    max: 1
---

En este ejemplo he usado engine: copilot y el modelo gpt-4.1 por una razón bastante práctica: no consume premium requests y quería comprobar si era capaz de resolver bien un caso como este. La parte interesante es que esto no está cerrado. El workflow se puede adaptar para usar otros modelos e incluso otros agentes de IA si hiciera falta, dependiendo del nivel de razonamiento, del coste o del tipo de repositorio que quieras analizar.

También es importante tener en cuenta que este tipo de flujos no siempre se comportan igual con todos los modelos. A veces el prompt necesita pequeños ajustes en cómo formula las instrucciones, cómo restringe la salida o cómo pide justificar el veredicto. Yo lo voy iterando y afinando con el tiempo, y no me extrañaría que la versión óptima del prompt para un modelo no fuese exactamente la mejor para otro.

También es posible que en lugar de un slash command se lanzara siempre que ocurre una PR ejecutada por Dependabot, pero en este caso quería ser yo quien lo controlara. También por supuesto se puede «complicar más» y que cada vez que se haga push del código si todavía hay alertas de Dependabot pendientes que se ordene la re-ejecución de estos flujos para ver si en una siguiente iteración no solo no se ha arreglado la versión de la dependencia sino que encima ahora se está haciendo uso de la funcionalidad que la hace vulnerable 😅

Una vez validado el contexto, el workflow toma la propia pull request como fuente inicial para identificar qué paquete se actualiza, desde qué versión y hacia cuál. Si en el PR aparecen identificadores como un CVE o un GHSA, los usa como punto de partida; si no aparecen, intenta inferir la advisory a partir del paquete y del rango de versiones.

La parte clave: ir a la advisory completa

Aquí está una de las diferencias importantes respecto a una automatización más superficial. El flujo no se conforma con el resumen del PR de Dependabot. Va a buscar los detalles completos en GitHub Security Advisories para entender qué patrón concreto es vulnerable, qué versiones están afectadas, qué CWE aplica y, sobre todo, qué condiciones hacen falta para que el problema sea explotable.

Eso cambia bastante el tipo de análisis que se puede hacer. No es lo mismo detectar que una librería está instalada que saber que la advisory solo afecta a una función concreta, a cierto modo de invocación o a un caso donde el input del usuario llega sin validación a un punto determinado. El workflow intenta aterrizar precisamente eso.

Si la advisory pública no da suficiente detalle técnico, el planteamiento del flujo contempla ampliar contexto con referencias adicionales y fuentes públicas más detalladas. La idea es que el veredicto no salga de una lectura superficial del PR, sino de entender bien el patrón vulnerable que describe la advisory.

El prompt también forma parte del diseño

Otro punto que me parece muy interesante es que el comportamiento del workflow no está definido solo por el frontmatter. El prompt en sí también es parte central del diseño, porque es donde se obliga al agente a seguir un orden concreto, a no confundir riesgos adyacentes con la advisory analizada y a justificar por qué marca un caso como realmente explotable o no.

Este es un fragmento representativo del prompt actual:

## Trigger

This workflow runs when a trusted user comments `/dependabot-analyze` on a pull request.
The command must be the first token in the comment.

If the command was not used on a pull request, stop immediately and do nothing.

You must then check if the target PR was created by Dependabot (author is `dependabot[bot]`).
If it was NOT created by Dependabot, stop here and leave a short comment explaining that this command only supports Dependabot PRs.

## Your tasks

### 3. Get complete vulnerability details from GitHub Security Advisories
- Extract from the advisory:
  - Vulnerable version range
  - Vulnerable code patterns
  - CWE classification
  - Exploitation conditions
  - References

### 4. Analyze the codebase
- Distinguish clearly between these three questions:
  - Is the vulnerable method/pattern present?
  - Are the advisory's exploitation preconditions actually satisfied in this codebase?
  - Is there a different security issue nearby that is real but outside the scope of this advisory?

### 6. Add labels to the PR
- `🔴 vulnerability:in-use` + `🚨 priority:high`
- `🟢 vulnerability:not-in-use` + `🕓 priority:low`
- `🤔 vulnerability:unclear` when the vulnerable pattern cannot be determined

Me gusta enseñar esta parte porque aquí se ve muy bien que el valor no está solo en “usar IA”, sino en cómo se define el criterio. El prompt no le pide al agente que mire si una librería sale en un fichero, sino que determine si el patrón vulnerable existe de verdad, si las precondiciones del exploit están demostradas y si hay que separar ese análisis de otros problemas de seguridad que puedan aparecer cerca.

Y aquí vuelve a entrar el tema del modelo. Este prompt seguramente seguirá cambiando. Yo lo voy mejorando a medida que pruebo más escenarios y, muy probablemente, algunas decisiones de redacción, granularidad o formato de salida tendrán que ser un poco distintas según el modelo o el agente que quiera usar detrás.

Pero lo que si que es realmente importante aquí es: esta ayuda adicional es más que cero.

Qué devuelve en la PR de Dependabot

El resultado del análisis se deja directamente en la propia PR. El workflow comprueba primero si existen las labels que necesita y, si no están, las crea. Luego aplica una combinación de etiquetas según el veredicto:

• 🔴 vulnerability:in-use y 🚨 priority:high si el patrón vulnerable está en uso y las precondiciones del exploit están demostradas o muy respaldadas por el código.
• 🟢 vulnerability:not-in-use y 🕓 priority:low si el patrón vulnerable no aparece, el uso es seguro o la explotabilidad no está demostrada.
• 🤔 vulnerability:unclear si después de consultar advisories y fuentes públicas no hay suficiente detalle técnico para identificar el patrón vulnerable con confianza.

Algo como esto:

Además deja un comentario estructurado con el resumen de la advisory, severidad, CWE, patrón vulnerable, condiciones de explotación, referencias y una tabla por archivos donde distingue entre uso del patrón, precondiciones cumplidas, riesgos adyacentes y veredicto final.

Ese detalle me parece importante porque convierte la PR en algo bastante más accionable. No es solo una actualización propuesta por Dependabot, sino una revisión con criterio explícito sobre si el riesgo está realmente activado en el código del repositorio.

Lo que me parece interesante de esta PoC

Lo que más me interesa aquí no es solo automatizar pasos, sino introducir mejor criterio de priorización en un problema muy ruidoso. En muchos repositorios acaban acumulándose alertas, PRs automáticas y decisiones rápidas basadas únicamente en la existencia de una advisory. Tener un flujo que intente responder si el patrón vulnerable está de verdad en uso me parece bastante más útil.

También me gusta porque obliga al análisis a no mezclar hallazgos distintos. Puede haber una advisory que no aplique realmente a tu código y, al mismo tiempo, puede existir otro problema de seguridad cerca de ese mismo flujo. El workflow intenta dejar claro cuándo está hablando de la advisory concreta de Dependabot y cuándo se trata de un riesgo adyacente distinto.

Una forma más útil de revisar PRs de seguridad

En definitiva, esta prueba de concepto busca responder una pregunta que Dependabot, y otras herramientas, no resuelven a día de hoy del todo: no solo si una dependencia está afectada por una advisory, sino si tu repositorio está usando realmente el patrón que convierte esa advisory en un problema práctico.

Para mí ese es el punto interesante de combinar GitHub Agentic Workflows con análisis de seguridad de dependencias: usar la automatización no solo para abrir PRs, sino para devolver contexto que ayude a decidir mejor qué corregir primero y por qué.

Si quieres explorar otros escenarios en los que GitHub Agentic Workflows pueden tener sentido aquí te dejo otro vídeo donde te muestro dónde lo estoy usando yo:

¡Nos vemos 👋🏻!

La entrada Dependabot te dice que es vulnerable… ¿pero es explotable de verdad? se publicó primero en return(GiS);.

Si estás evaluando GitHub Advanced Security es posible que cuando revises la parte de Code scanning, que analiza las vulnerabilidades que podemos introducir, sin querer claro está 😅, en nuestro propio código, puede que te preguntes:

👉 “¿Puedo controlar qué analiza CodeQL?”
👉 “¿Puedo limitarlo al OWASP Top 10 e incluso incluir mis propias reglas?”

Y la respuesta es: sí y en este artículo te cuento cómo configurarlo.

Si no conoces muchos de GitHub Advanced Security aquí te dejo un vídeo de mi canal donde hago un repaso de sus funcionalidades principals:

🤔 ¿Por qué limitar las queries de CodeQL?

Por defecto, CodeQL ejecuta cientos de queries de seguridad. Aquí puedes encontrar las CWEs que cubre a día de hoy. Esto está genial… pero en algunos casos algunos el sentimiento es:

❌ Ejecuciones muy largas en repositorios inmensos
❌ Genera ruido
❌ Puede ser difícil priorizar
❌ No siempre encaja con tus políticas de seguridad

Y aquí es donde entra el verdadero valor: 👉 definir tu propio conjunto de queries siguiendo marcos normativos o incluso añadiendo alguna query interna propia que también se quiere tener en consideración.

📦 Repositorio de ejemplo

Así para poder ilustrar esto he creado un repositorio que te dejo en mi cuenta de GitHub, en el cual me he marcado dos objetivos:

1. Ejecutar solo un subconjunto de queries

En lugar de usar:

queries: security-and-quality

Puedes definir exactamente qué quieres ejecutar:

• OWASP Top 10
• solo ciertos CWE
• queries críticas
• etc.

OWASP Top 10 es el estándar más común en AppSec.

Cada categoría (por ejemplo Injection) se corresponde con múltiples CWE y queries.

👉 Ejemplo:

• SQL Injection → CWE-89
• XSS → CWE-79

Y CodeQL ya tiene queries que cubren estos casos.

Incluso puedes crear suites específicas tipo:

name: OWASP-Top-10
queries:
  - codeql/java/queries/security/sql-injection.ql
  - codeql/javascript/queries/security/xss.ql

Este enfoque está bastante extendido en la comunidad (Medium)

2. Añadir custom queries

Aquí es donde la cosa se pone interesante 🔥 CodeQL permite escribir queries propias porque:

👉 trata el código como datos consultables
👉 puedes detectar patrones específicos de tu empresa

Ejemplos reales:

• uso de librerías internas inseguras
• validaciones corporativas obligatorias
• patrones legacy peligrosos

Vale, pues ahora ¿Cómo configuramos esto? Pues vamos a verlo 😃

Configuración del flujo avanzado de GitHub Actions con queries personalizadas para CodeQL

Para que todo esto sea posible tienes que tener configurado CodeQL en su modo avanzado. Esto lo que significa es que necesitamos tener el flujo definido en el repo o al menos tener un flujo reusable en algún sitio donde tener toda esta configuración. Pero antes de nada necesitamos un archivo de configuración con las reglas personalizadas.

1. Crear tu archivo de configuración

En .github/codeql/codeql-config.yml:

Lo que tengo es algo como lo siguiente:

# Configuración de CodeQL para OWASP Top 10
# Este archivo indica a CodeQL que use SOLO la query suite personalizada
# de OWASP Top 10, en lugar de las suites predefinidas (default o security-extended).
#
# Documentación:
# https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning

name: "CodeQL - OWASP Top 10"

# ⚠️ CLAVE: Desactivar las queries predefinidas (default suite)
# Sin esto, CodeQL ejecuta las queries por defecto ADEMÁS de las personalizadas
disable-default-queries: true

# Queries a ejecutar:
# 1. Suite OWASP Top 10 (2025) - queries estándar filtradas por marco normativo
# 2. Queries personalizadas de negocio bancario (custom rules)
queries:
  - uses: ./.github/codeql/owasp-top-10-js.qls
  - uses: ./.github/codeql/custom-queries

# Paths a analizar (solo el código fuente de la aplicación)
paths:
  - src

# Paths a ignorar (tests, fixtures, etc.)
paths-ignore:
  - node_modules
  - "**/*.test.js"
  - "**/*.spec.js"

Este me va a permitir indicar dónde están las queries que quiero lanzar. En el caso del archivo .github/codeql/owasp-top-10-js.qls lo que he hecho es algo como lo siguiente:

# -----------------------------------------------------------
# CodeQL Query Suite: OWASP Top 10 (2025) - JavaScript/TypeScript
# -----------------------------------------------------------
#
# Este archivo define un conjunto personalizado de queries de CodeQL
# que cubren exclusivamente las categorías del OWASP Top 10 (2025).
#
# Al usar esta suite en lugar de "security-extended" o "default",
# solo se ejecutarán las queries relevantes para OWASP Top 10,
# filtrando cualquier otra regla que no aplique a este marco normativo.
#
# Documentación de query suites:
# https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/
#
# Lista completa de CWEs cubiertos por CodeQL:
# https://codeql.github.com/codeql-query-help/full-cwe/
#
# -----------------------------------------------------------
# Para limitar aún más por severidad o precisión, descomenta:
#- include:
#    problem.severity:
#    - medium
#    - high
#    - very-high
#    - critical
#    precision:
#    - high
#    - very-high
# -----------------------------------------------------------

# Importar el pack de queries de JavaScript/TypeScript
# Necesario cuando se usa disable-default-queries: true en la config
- qlpack: codeql/javascript-queries

- include:
    id:

    # =========================================================
    # A01:2025 - Broken Access Control
    # Mantiene #1. Ahora incluye SSRF (antes era A10:2021)
    # CWE-22: Path Traversal
    # CWE-601: URL Redirection to Untrusted Site
    # CWE-918: SSRF (movido desde A10:2021)
    # =========================================================
    - js/path-injection
    - js/ml-powered/path-injection
    - js/server-side-unvalidated-url-redirection
    - js/client-side-unvalidated-url-redirection
    - js/user-controlled-bypass
    - js/exposure-of-private-files
    - js/request-forgery
    - js/client-side-request-forgery
    - js/file-access-to-http
    - js/http-to-file-access
    - js/sensitive-get-query

    # =========================================================
    # A02:2025 - Security Misconfiguration
    # Sube de A05:2021 a A02:2025
    # CWE-16: Configuration
    # CWE-611: XXE
    # =========================================================
    - js/cors-misconfiguration-for-credentials
    - js/disabling-certificate-validation
    - js/disabling-electron-websecurity
    - js/enabling-electron-insecure-content
    - js/functionality-from-untrusted-source
    - js/unsafe-external-link
    - js/double-escaping
    - js/incomplete-hostname-regexp
    - js/incomplete-url-scheme-check
    - js/incomplete-url-substring-sanitization
    - js/incorrect-suffix-check
    - js/incomplete-sanitization
    - js/incomplete-html-attribute-sanitization
    - js/incomplete-multi-character-sanitization
    - js/samesite-none-cookie

    # =========================================================
    # A03:2025 - Software Supply Chain Failures
    # Expandido desde A06:2021 (Vulnerable and Outdated Components)
    # (Dependabot + CodeQL para dependencias inseguras)
    # =========================================================
    - js/insecure-dependency
    - js/insecure-download

    # =========================================================
    # A04:2025 - Cryptographic Failures
    # Baja de A02:2021 a A04:2025
    # CWE-327: Use of Broken/Weak Crypto Algorithm
    # CWE-328: Reversible One-Way Hash
    # CWE-330: Insufficient Randomness
    # =========================================================
    - js/weak-cryptographic-algorithm
    - js/insufficient-key-size
    - js/biased-cryptographic-random
    - js/insecure-randomness
    - js/clear-text-storage-of-sensitive-data
    - js/clear-text-logging
    - js/clear-text-cookie

    # =========================================================
    # A05:2025 - Injection
    # Baja de A03:2021 a A05:2025
    # CWE-79: XSS
    # CWE-78: OS Command Injection
    # CWE-89: SQL Injection
    # CWE-94: Code Injection
    # CWE-917: Expression Language Injection
    # CWE-1321: Prototype Pollution
    # =========================================================
    - js/sql-injection
    - js/ml-powered/sql-injection
    - js/nosql-injection
    - js/ml-powered/nosql-injection
    - js/reflected-xss
    - js/stored-xss
    - js/xss
    - js/xss-through-dom
    - js/xss-through-exception
    - js/ml-powered/xss
    - js/command-line-injection
    - js/indirect-command-line-injection
    - js/shell-command-constructed-from-input
    - js/shell-command-injection-from-environment
    - js/code-injection
    - js/unsafe-code-construction
    - js/bad-code-sanitization
    - js/bad-tag-filter
    - js/html-constructed-from-input
    - js/unsafe-html-expansion
    - js/prototype-pollution
    - js/prototype-polluting-assignment
    - js/prototype-pollution-utility
    - js/tainted-format-string
    - js/template-object-injection
    - js/xpath-injection
    - js/xml-bomb
    - js/xxe
    - js/log-injection
    - js/regex/missing-regexp-anchor

    # =========================================================
    # A06:2025 - Insecure Design
    # Baja de A04:2021 a A06:2025
    # CWE-799: Improper Control of Interaction Frequency
    # =========================================================
    - js/missing-rate-limiting

    # =========================================================
    # A07:2025 - Authentication Failures
    # Mantiene #7 (renombrado de "Identification and Auth Failures")
    # CWE-798: Hardcoded Credentials
    # CWE-259: Hardcoded Password
    # CWE-384: Session Fixation
    # =========================================================
    - js/hardcoded-credentials
    - js/empty-password-in-configuration-file
    - js/password-in-configuration-file
    - js/jwt-missing-verification
    - js/missing-token-validation
    - js/missing-origin-check
    - js/session-fixation
    - js/insufficient-password-hash
    - js/client-exposed-cookie

    # =========================================================
    # A08:2025 - Software or Data Integrity Failures
    # Mantiene #8
    # CWE-502: Deserialization of Untrusted Data
    # =========================================================
    - js/unsafe-deserialization
    - js/unsafe-jquery-plugin
    - js/zipslip
    - js/identity-replacement

    # =========================================================
    # A09:2025 - Security Logging & Alerting Failures
    # Mantiene #9 (renombrado, ahora enfatiza "Alerting")
    # CWE-778: Insufficient Logging
    # (CodeQL tiene cobertura limitada aquí)
    # =========================================================
    - js/stack-trace-exposure
    - js/cross-window-information-leak

    # =========================================================
    # A10:2025 - Mishandling of Exceptional Conditions (NUEVO)
    # Reemplaza SSRF (que se movió a A01)
    # CWE-248: Uncaught Exception
    # CWE-754: Improper Check for Unusual/Exceptional Conditions
    # CWE-391: Unchecked Error Condition
    # =========================================================
    - js/resource-exhaustion

    # =========================================================
    # GitHub Actions (bonus - seguridad en CI/CD)
    # =========================================================
    - js/actions/command-injection
    - js/actions/pull-request-target
    - js/build-artifact-leak
    - js/host-header-forgery-in-email-generation
    - js/remote-property-injection
    - js/unsafe-dynamic-method-access
    - js/useless-regexp-character-escape

Aquí no te voy a engañar, le he pedido ayuda a GitHub Copilot para recopilar todas las reglas que me hacen falta y sería cuestión de probarlo bien para que no se nos olvide nada.

El segundo archivo apunta a una custom query en CodeQL que valida que haya una validación previa a ciertas operaciones que pueden ser críticas, por ejemplo en un banco. En la configuración a lo que se está apuntando en realidad es a una carpeta dentro de la cual hay dos archivos, el qlpack.yml:

# CodeQL Query Pack personalizado para reglas de negocio bancarias
# Este pack contiene queries custom que no están en las suites estándar de CodeQL
name: custom-banking-queries
version: 0.0.1
dependencies:
  codeql/javascript-all: "*"

Y por otro lado uno que he llamado missing-context-validation.ql:

/**
 * @name Operación bancaria sensible sin validación de contexto
 * @description Detecta llamadas a operaciones bancarias sensibles que no están
 *              precedidas por una llamada de validación de contexto en la misma función.
 *              En entornos bancarios, toda operación crítica debe validar el contexto
 *              (sesión, autorización) antes de ejecutarse.
 * @kind problem
 * @problem.severity error
 * @precision high
 * @id custom/missing-context-validation
 * @tags security
 *       banking
 *       compliance
 *       custom
 */

import javascript

/**
 * Nombres de operaciones bancarias sensibles.
 * Cualquier llamada a estas funciones DEBE estar precedida
 * por una validación de contexto en la misma función.
 */
predicate isSensitiveOperationName(string name) {
  name = "executeTransaction" or
  name = "transferFunds" or
  name = "processPayment" or
  name = "approveCredit" or
  name = "withdrawFunds"
}

/**
 * Nombres de funciones de validación de contexto.
 * Al menos una de estas debe aparecer antes de cualquier operación sensible.
 */
predicate isValidationFunctionName(string name) {
  name = "validateContext" or
  name = "validateSession" or
  name = "verifyAuthorization"
}

/**
 * Obtiene el nombre de la función llamada, sea como llamada directa
 * (executeTransaction(...)) o como método (bankService.executeTransaction(...))
 */
string getCallName(CallExpr call) {
  result = call.getCalleeName()
  or
  exists(DotExpr dot |
    dot = call.getCallee() and
    result = dot.getPropertyName()
  )
}

from CallExpr sensitiveCall, Function enclosingFunc, string opName
where
  // Identificar llamadas a operaciones sensibles
  opName = getCallName(sensitiveCall) and
  isSensitiveOperationName(opName) and
  // Obtener la función que contiene la llamada
  enclosingFunc = sensitiveCall.getEnclosingFunction() and
  // Verificar que NO existe una llamada de validación ANTES en la misma función
  not exists(CallExpr validationCall, string valName |
    valName = getCallName(validationCall) and
    isValidationFunctionName(valName) and
    validationCall.getEnclosingFunction() = enclosingFunc and
    validationCall.getLocation().getStartLine() < sensitiveCall.getLocation().getStartLine()
  )
select sensitiveCall,
  "La operación bancaria sensible '" + opName +
  "' se ejecuta sin validación de contexto previa. " +
  "Añade una llamada a validateContext(), validateSession() o verifyAuthorization() antes de esta operación."

Con todo esto ya solo nos queda usarlo como parte de nuestro flujo de GitHub Actions para esa configuración avanzada de CodeQL.

.github/workflows/codeql.yml

💡 Aquí es donde conectas todo:

name: "🛡️ CodeQL - OWASP Top 10"

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  # Escaneo programado semanal (lunes a las 8:00 UTC)
  schedule:
    - cron: '0 8 * * 1'

jobs:
  analyze:
    name: Analyze (OWASP Top 10)
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
      actions: read

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Initialize CodeQL
      uses: github/codeql-action/init@v4
      with:
        languages: javascript-typescript
        # Usar la configuración personalizada que apunta a la suite OWASP
        config-file: ./.github/codeql/codeql-config.yml

    - name: Autobuild
      uses: github/codeql-action/autobuild@v4

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        category: "/language:javascript-typescript"

Aquí lo importante es que en el paso init le pasamos el config file que definí más arriba y con ello ya sabe cuáles son las reglas, preconstruidas y generadas por mi, que tiene que utilizar.

En el caso de las personalizadas, en este ejemplo, verás algo como lo siguiente:

y el detalle se vería así:

🧩 Estrategias que puedes aplicar

Aquí tienes varios patrones reales que puedes usar:

✅ 1. OWASP-only scanning

👉 Ideal para:

• compliance
• auditorías
• equipos empezando con seguridad

⚡ 2. Only critical queries

👉 Reduce ruido
👉 Mejora adopción

🏢 3. Security policies corporativas

👉 Custom queries + suites
👉 Enforcing en PRs

🧪 4. Demo / training environments

👉 Como este repo 😄
👉 Muy útil para workshops o sesiones técnicas

Además, encaja perfectamente con el enfoque shift-left de GitHub Advanced Security, donde detectas vulnerabilidades antes de producción.

¡Nos vemos 👋🏻!

La entrada 🔐 Cómo configurar CodeQL para ejecutar solo las queries que necesitas (OWASP Top 10 + custom queries) se publicó primero en return(GiS);.

El problema es que los agentes trabajan mucho mejor con Markdown que con HTML lleno de clases CSS, menús, sidebars y estructuras de tema. Así que me puse a crear un plugin de WordPress que convierte los posts y las páginas en Markdown limpio para que los agentes puedan consumirlos directamente. El plugin se llama Markdown View for AI Agents y a día de hoy todavía está en revisión por WordPress.org, así que ya os contaré más cuando esté publicado. Aunque si eres curios@ ya lo puedes ver funcionando en este mismo blog 👆🏻😇: en cada artículo verás un botón que pone View as Markdown y voilà, el contenido pasa a ser algo mucho más manejable para nuestros amigos los agentes.

Pero este artículo, más allá de mi plugin, de lo que va es del entorno que he utilizado para desarrollarlo, probarlo y verificar que cumple con todos los requisitos antes de hacer la submission. Y como no podía ser de otra manera, la respuesta fue: Dev Containers.

Si no sabes de qué van los Dev Containers te dejo este vídeo que grabé hace tiempo para mi canal de YouTube:

🎯 El problema

Desarrollar un plugin de WordPress no es como hacer un npm init y a correr. Necesitas:

• Una instancia de WordPress funcionando
• PHP con las extensiones correctas
• MySQL/MariaDb como base de datos
• WP-CLI para gestionar WordPress desde la terminal
• Composer para las dependencias PHP
• PHP_CodeSniffer con los estándares de WordPress

Configurar todo esto en tu máquina local es un dolor. Y si trabajas en más de un proyecto, los conflictos entre versiones son inevitables. Así que lo metí todo en un Dev Container 🎉

📦 La estructura

La configuración vive en la carpeta .devcontainer/ del repositorio:

.devcontainer/
├── devcontainer.json
├── Dockerfile
├── docker-compose.yml
└── setup.sh

Vamos parte por parte.

🐳 Docker Compose

En el docker compose que utilizará mi configuración de Dev Container para levantar los servicios incluí tres contenedores:

services:
  workspace:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspaces/wp-markdown-for-agents:cached
      - composer-cache:/home/vscode/.composer/cache
      - wordpress-data:/srv/wordpress
      - plugins:/home/vscode/.local/share/plugins
      - plugins:/srv/wordpress/wp-content/plugins
      - ..:/srv/wordpress/wp-content/plugins/markdown-view-for-ai-agents:cached
    environment:
      COMPOSER_MEMORY_LIMIT: -1
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    command: sleep infinity
    depends_on:
      - db
      - wordpress

  wordpress:
    image: wordpress:php8.3-apache
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    volumes:
      - wordpress-data:/var/www/html
      - plugins:/var/www/html/wp-content/plugins
      - ..:/var/www/html/wp-content/plugins/markdown-view-for-ai-agents:cached
    depends_on:
      - db

  db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: wordpress
      MARIADB_ROOT_PASSWORD: root
    volumes:
      - mariadb-data:/var/lib/mysql

volumes:
  composer-cache:
  plugins:
  wordpress-data:
  mariadb-data:

El primero de ellos, workspace, es el contenedor principal, en el que estaré desarrollando mi plugin. Los otros dos son los contenedores que me facilitarán una instancia de WordPress, con su correspondiente base de datos, para poder probarlo de forma súper sencilla.

La clave aquí está en el bind mount del plugin. Al montar el directorio del proyecto directamente en wp-content/plugins/, cualquier cambio que hago en el código se refleja inmediatamente en la instancia de WordPress. No hay que copiar archivos, ni reconstruir nada. Edito, guardo, refresco el navegador y listo.

🏗️ El Dockerfile

Para que el contenedor llamado workspace funcione correctamente está esperando poder generar una imagen de Docker, para la que va a usar el Dockerfile que se encuentra en el mismo directorio, .devcontainer:

FROM mcr.microsoft.com/devcontainers/php:3-8.3-trixie

RUN apt-get update \
	&& export DEBIAN_FRONTEND=noninteractive \
	&& apt-get install -y --no-install-recommends default-mysql-client libmariadb-dev librsvg2-bin \
	&& docker-php-ext-install mysqli pdo_mysql \
	&& curl -fsSL -o /usr/local/bin/wp https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar \
	&& chmod +x /usr/local/bin/wp \
	&& mkdir -p /home/vscode/.local/share/plugins \
	&& chown -R vscode:vscode /home/vscode/.local \
	&& apt-get clean \
	&& rm -rf /var/lib/apt/lists/*

Con esto tengo:

• PHP 8.3 en el contenedor donde realmente estoy desarrollando mi plugin
• Cliente de MySQL
• La librería librsvg2-bin, la cual me va a permitir de forma sencilla poder convertir imágenes svg a png.
• WP-CLI para gestionar WordPress desde la terminal (instalar plugins, crear posts de prueba, activar/desactivar el plugin…). Porque no me vale tener el WordPress pelado sino que es mucho más rápido tener ya artículos con los que poder probar el botón/URL en mi caso.

⚙️ El devcontainer.json

Aquí es donde se conecta todo. El devcontainer.json le dice a VS Code qué servicio de Docker Compose usar, qué extensiones instalar, qué puertos reenviar y qué ejecutar después de crear el contenedor:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/php
{
	"name": "🧪 markdown-view-for-ai-agents",
	"dockerComposeFile": "compose.yml",
	"service": "workspace",
	"runServices": [
		"workspace",
		"wordpress",
		"db"
	],
	"workspaceFolder": "/workspaces/wp-markdown-for-agents",
	"shutdownAction": "stopCompose",

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [
		8080
	],
	"portsAttributes": {
		"8080": {
			"label": "📰 WordPress",
			"onAutoForward": "notify"
		}
	},
	"postCreateCommand": "./install-git-hooks.sh",
	"postStartCommand": "bash .devcontainer/post-start.sh",
	"customizations": {
		"vscode": {
			"settings": {
				"php.validate.executablePath": "/usr/local/bin/php",
				"files.associations": {
					"*.inc": "php"
				},
				"[php]": {
					"editor.formatOnSave": false
				},
				"intelephense.environment.phpVersion": "8.3.0",
				"intelephense.files.exclude": [
					"vendor/**"
				],
				"search.exclude": {
					"vendor": true
				}
			},
			"extensions": [
				"GitHub.vscode-github-actions",
				"bmewburn.vscode-intelephense-client",
				"DEVSENSE.composer-php-vscode",
				"xdebug.php-debug"
			]
		}
	},
	"features": {
		"ghcr.io/devcontainers/features/github-cli:1": {}
	}

}

Las extensiones que incluyo son las que uso para desarrollar en PHP con WordPress, pero aquí cada uno puede añadir las suyas. Lo importante es que al abrir el proyecto todo el mundo tiene el mismo entorno con las mismas herramientas.

🚀 El script de setup

Y aquí viene la magia para que el WordPress de pruebas esté configurado tal y como lo necesitas: El postCreateCommand ejecuta un script que se encarga de dejarlo todo listo:

#!/usr/bin/env bash

set -eu

wp_path="/srv/wordpress"
site_url="http://localhost:8080"
sample_seed_option="md_for_agents_sample_content_seeded"
plugin_check_dir="/home/vscode/.local/share/plugins/plugin-check"
plugin_check_main_file="$plugin_check_dir/plugin-check.php"
plugin_check_cli_file="$plugin_check_dir/cli.php"

export XDEBUG_MODE=off

wp_cli() {
	wp --path="$wp_path" "$@"
}

ensure_plugin_check_files() {
	mkdir -p "$plugin_check_dir"

	if [ -f "$plugin_check_main_file" ] && [ -f "$plugin_check_cli_file" ]; then
		return 0
	fi

	tmp_dir="$(mktemp -d)"
	archive="$tmp_dir/plugin-check.zip"
	extracted_dir="$tmp_dir/plugin-check"

	cleanup_plugin_check_tmp() {
		rm -rf "$tmp_dir"
	}

	trap cleanup_plugin_check_tmp RETURN

	curl -fsSL -o "$archive" "https://downloads.wordpress.org/plugin/plugin-check.latest-stable.zip"
	unzip -q "$archive" -d "$tmp_dir"

	find "$plugin_check_dir" -mindepth 1 -maxdepth 1 ! -name '.gitkeep' -exec rm -rf {} +
	cp -R "$extracted_dir"/. "$plugin_check_dir"/

	trap - RETURN
	cleanup_plugin_check_tmp
}

upsert_post() {
	post_type="$1"
	post_slug="$2"
	post_title="$3"
	post_content="$4"

	post_id="$(wp_cli post list --post_type="$post_type" --name="$post_slug" --field=ID 2>/dev/null | head -n 1 || true)"

	if [ -n "$post_id" ]; then
		wp_cli post update "$post_id" \
			--post_title="$post_title" \
			--post_name="$post_slug" \
			--post_content="$post_content" >/dev/null
		echo "$post_id"
		return 0
	fi

	wp_cli post create \
		--post_type="$post_type" \
		--post_status=publish \
		--post_title="$post_title" \
		--post_name="$post_slug" \
		--post_content="$post_content" \
		--porcelain
}

set_post_terms() {
	post_slug="$1"
	taxonomy="$2"
	terms_csv="$3"

	post_id="$(wp_cli post list --post_type=post --name="$post_slug" --field=ID 2>/dev/null | head -n 1 || true)"

	if [ -z "$post_id" ]; then
		return 0
	fi

	wp_cli post term set "$post_id" "$taxonomy" "$terms_csv" >/dev/null
}

seed_sample_content() {
	getting_started_page_id="$(upsert_post \
		page \
		getting-started-markdown-agents \
		'Getting Started with Markdown for Agents' \
		"<!-- wp:paragraph {\"fontSize\":\"large\"} --><p class=\"has-large-font-size\">This local page exists to test the plugin output quickly from a realistic WordPress page.</p><!-- /wp:paragraph --><!-- wp:heading {\"level\":2} --><h2>Checklist</h2><!-- /wp:heading --><!-- wp:list --><ul><li>WordPress installed through WP-CLI</li><li>Plugin activated automatically</li><li>Sample content seeded idempotently</li></ul><!-- /wp:list --><!-- wp:heading {\"level\":2} --><h2>Example prompt</h2><!-- /wp:heading --><!-- wp:paragraph --><p>Summarize this page for an autonomous coding agent.</p><!-- /wp:paragraph -->")"

	upsert_post \
		post \
		release-notes-draft \
		'Release Notes Draft' \
		"<!-- wp:heading {\"level\":1} --><h1>Release Notes Draft</h1><!-- /wp:heading --><!-- wp:heading {\"level\":2} --><h2>Highlights</h2><!-- /wp:heading --><!-- wp:list --><ul><li>Automated WordPress bootstrap</li><li>Local plugin activation</li><li>Repeatable demo content</li></ul><!-- /wp:list --><!-- wp:heading {\"level\":2} --><h2>Pending</h2><!-- /wp:heading --><!-- wp:list {\"ordered\":true} --><ol><li>Verify markdown export output</li><li>Review button placement in the editor</li><li>Package the release zip</li></ol><!-- /wp:list -->" >/dev/null

	upsert_post \
		post \
		agent-qa-scenario \
		'Agent QA Scenario' \
		"<!-- wp:heading {\"level\":2} --><h2>Scenario</h2><!-- /wp:heading --><!-- wp:paragraph --><p>Use this post to test how the plugin exposes headings, lists, and links for agents.</p><!-- /wp:paragraph --><!-- wp:list --><ul><li>Visit the generated markdown endpoint</li><li>Confirm headings remain stable</li><li>Confirm links remain absolute</li></ul><!-- /wp:list --><!-- wp:paragraph --><p>Related page ID: ${getting_started_page_id}</p><!-- /wp:paragraph -->" >/dev/null

	upsert_post \
		post \
		headings-lists-and-frontmatter \
		'Headings, Lists, and Frontmatter' \
		"<!-- wp:paragraph --><p>This post exists to check heading depth, ordered lists, unordered lists, and YAML frontmatter metadata.</p><!-- /wp:paragraph --><!-- wp:heading {\"level\":2} --><h2>Acceptance checklist</h2><!-- /wp:heading --><!-- wp:list --><ul><li>Heading levels remain stable</li><li>Bullet items stay as bullet items</li><li>Categories and tags appear in the frontmatter</li></ul><!-- /wp:list --><!-- wp:heading {\"level\":3} --><h3>Release steps</h3><!-- /wp:heading --><!-- wp:list {\"ordered\":true} --><ol><li>Run linting</li><li>Package the plugin</li><li>Smoke-test the markdown endpoint</li></ol><!-- /wp:list -->" >/dev/null

	upsert_post \
		post \
		links-quotes-and-inline-code \
		'Links, Quotes, and Inline Code' \
		"<!-- wp:paragraph --><p>Use this example to verify how inline links and inline code are represented in the markdown output.</p><!-- /wp:paragraph --><!-- wp:quote --><blockquote class=\"wp-block-quote\"><p>Agents work best when the source content is explicit, stable, and easy to parse.</p><cite>Local demo note</cite></blockquote><!-- /wp:quote --><!-- wp:paragraph --><p>Open the <a href=\"http://localhost:8080/getting-started-markdown-agents/\">getting started page</a> and compare the endpoint output to <code>wp post get</code>.</p><!-- /wp:paragraph -->" >/dev/null

	upsert_post \
		post \
		code-blocks-and-tables \
		'Code Blocks and Tables' \
		"<!-- wp:paragraph --><p>This sample covers fenced code blocks and HTML tables converted into markdown tables.</p><!-- /wp:paragraph --><!-- wp:code --><pre class=\"wp-block-code\"><code lang=\"bash\">wp plugin activate markdown-view-for-ai-agents --path=/srv/wordpress
wp option get siteurl --path=/srv/wordpress</code></pre><!-- /wp:code --><!-- wp:table --><figure class=\"wp-block-table\"><table><thead><tr><th>Check</th><th>Expected result</th></tr></thead><tbody><tr><td>Code fence</td><td>Preserved with bash language</td></tr><tr><td>Table headers</td><td>Rendered as markdown table header row</td></tr></tbody></table></figure><!-- /wp:table -->" >/dev/null

	upsert_post \
		post \
		images-and-mixed-formatting \
		'Images and Mixed Formatting' \
		"<!-- wp:paragraph --><p>This example mixes <strong>bold text</strong>, <em>emphasis</em>, and an image with alt text for markdown conversion checks.</p><!-- /wp:paragraph --><!-- wp:image {\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} --><figure class=\"wp-block-image size-large\"><img src=\"https://wordpress.org/style/images/wp-header-logo.png\" alt=\"WordPress logo\" /></figure><!-- /wp:image --><!-- wp:paragraph --><p>Verify that the generated markdown keeps the image URL and preserves inline emphasis correctly.</p><!-- /wp:paragraph -->" >/dev/null

	set_post_terms headings-lists-and-frontmatter category "Demo Content,Frontmatter"
	set_post_terms headings-lists-and-frontmatter post_tag "headings,lists,metadata"
	set_post_terms links-quotes-and-inline-code category "Demo Content,Links"
	set_post_terms links-quotes-and-inline-code post_tag "quotes,links,inline-code"
	set_post_terms code-blocks-and-tables category "Demo Content,Code"
	set_post_terms code-blocks-and-tables post_tag "code-blocks,tables"
	set_post_terms images-and-mixed-formatting category "Demo Content,Media"
	set_post_terms images-and-mixed-formatting post_tag "images,bold,italic"

	hello_world_id="$(wp_cli post list --post_type=post --name=hello-world --field=ID 2>/dev/null | head -n 1 || true)"
	if [ -n "$hello_world_id" ]; then
		wp_cli post delete "$hello_world_id" --force >/dev/null
	fi

	sample_page_id="$(wp_cli post list --post_type=page --name=sample-page --field=ID 2>/dev/null | head -n 1 || true)"
	if [ -n "$sample_page_id" ]; then
		wp_cli post delete "$sample_page_id" --force >/dev/null
	fi

	privacy_policy_id="$(wp_cli post list --post_type=page --name=privacy-policy --field=ID 2>/dev/null | head -n 1 || true)"
	if [ -n "$privacy_policy_id" ]; then
		wp_cli option delete wp_page_for_privacy_policy >/dev/null 2>&1 || true
		wp_cli post delete "$privacy_policy_id" --force >/dev/null
	fi

	wp_cli option update show_on_front posts >/dev/null
	wp_cli option delete page_on_front >/dev/null 2>&1 || true
	wp_cli option delete page_for_posts >/dev/null 2>&1 || true

	if wp_cli option get "$sample_seed_option" >/dev/null 2>&1; then
		wp_cli option update "$sample_seed_option" 1 >/dev/null
	else
		wp_cli option add "$sample_seed_option" 1 >/dev/null
	fi
}

if [ ! -d "$wp_path" ]; then
	exit 0
fi

attempt=1
max_attempts=30

while [ "$attempt" -le "$max_attempts" ]; do
	if [ -f "$wp_path/wp-config.php" ]; then
		break
	fi
	sleep 2
	attempt=$((attempt + 1))
done

if [ ! -f "$wp_path/wp-config.php" ]; then
	if [ -n "${WORDPRESS_DB_HOST:-}" ] && [ -n "${WORDPRESS_DB_NAME:-}" ] && [ -n "${WORDPRESS_DB_USER:-}" ] && [ -n "${WORDPRESS_DB_PASSWORD:-}" ]; then
		wp config create \
			--path="$wp_path" \
			--dbname="$WORDPRESS_DB_NAME" \
			--dbuser="$WORDPRESS_DB_USER" \
			--dbpass="$WORDPRESS_DB_PASSWORD" \
			--dbhost="$WORDPRESS_DB_HOST" \
			--skip-check \
			--force >/dev/null 2>&1 || true
	fi

	if [ ! -f "$wp_path/wp-config.php" ]; then
		echo "WordPress config is not ready yet; skipping local bootstrap."
		exit 0
	fi
fi

installed=0
attempt=1

while [ "$attempt" -le "$max_attempts" ]; do
	if wp_cli core is-installed >/dev/null 2>&1; then
		installed=1
		break
	fi

	if wp_cli core install \
		--url="$site_url" \
		--title="Markdown View for AI Agents" \
		--admin_user="admin" \
		--admin_password="admin" \
		--admin_email="admin@example.com" \
		--skip-email >/dev/null 2>&1; then
		installed=1
		break
	fi

	sleep 2
	attempt=$((attempt + 1))
done

if [ "$installed" -eq 0 ]; then
	echo "WordPress database bootstrap is not ready yet; skipping local site installation."
	exit 0
fi

ensure_plugin_check_files

wp_cli option update blog_public 0 >/dev/null 2>&1 || true
wp_cli rewrite structure '/%postname%/' >/dev/null 2>&1 || true
wp_cli rewrite flush --hard >/dev/null 2>&1 || true
wp_cli theme activate twentytwentythree >/dev/null 2>&1 || true
wp_cli plugin activate markdown-view-for-ai-agents >/dev/null 2>&1 || true
wp_cli plugin activate plugin-check >/dev/null 2>&1 || true
seed_sample_content

Si, lo sé, es un poco largo y un poco complicado leerlo directamente desde el artículo, pero es básicamente el que me va a permitir que cuando abro el proyecto, en unos segundos tengo un WordPress funcionando con el plugin activado y contenido de prueba para poder probarlo. No tengo que hacer nada manual.

🔍 PHP_CodeSniffer y WordPress Coding Standards

Si quieres subir un plugin al directorio oficial de WordPress.org, el proceso de revisión es bastante estricto. El código tiene que seguir los WordPress Coding Standards. Y para eso, PHP_CodeSniffer es imprescindible.

El proyecto usa Composer para gestionar estas dependencias:

{
  "name": "0gis0/markdown-view-for-agents",
  "description": "Development tooling for the Markdown View for AI Agents WordPress plugin.",
  "type": "project",
  "require": {},
  "require-dev": {
    "dealerdirect/phpcodesniffer-composer-installer": "^1.0",
    "phpcompatibility/phpcompatibility-wp": "^2.1",
    "squizlabs/php_codesniffer": "^3.10",
    "wp-coding-standards/wpcs": "^3.1"
  },
  "config": {
    "allow-plugins": {
      "dealerdirect/phpcodesniffer-composer-installer": true
    },
    "sort-packages": true
  },
  "scripts": {
    "lint": "phpcs",
    "lint:php": "phpcs --standard=phpcs.xml.dist"
  }
}

Y el archivo phpcs.xml.dist define las reglas que se aplican al proyecto:

<?xml version="1.0"?>
<ruleset name="Markdown View for AI Agents">
  <description>PHP quality and security checks for the plugin.</description>

  <file>markdown-view-for-ai-agents.php</file>
  <file>includes</file>

  <exclude-pattern>vendor/*</exclude-pattern>
  <exclude-pattern>dist/*</exclude-pattern>
  <exclude-pattern>.wordpress-org/*</exclude-pattern>
  <exclude-pattern>.github/*</exclude-pattern>

  <arg name="basepath" value="."/>
  <arg name="extensions" value="php"/>
  <arg value="sp"/>

  <config name="testVersion" value="7.4-"/>

  <rule ref="WordPress-Core"/>
  <rule ref="WordPress-Docs"/>
  <rule ref="WordPress-Extra"/>
  <rule ref="WordPress.Security"/>
  <rule ref="PHPCompatibilityWP"/>

  <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
    <properties>
      <property name="prefixes" type="array">
        <element value="md_for_agents"/>
      </property>
    </properties>
  </rule>

  <rule ref="WordPress.WP.EnqueuedResourceParameters.NotInFooter">
    <exclude name="WordPress.WP.EnqueuedResourceParameters.MissingVersion"/>
  </rule>
</ruleset>

Al principio es frustrante porque te marca cosas que parecen menores (como el formato de los comentarios o los espacios dentro de los paréntesis), pero te fuerza a escribir código limpio y consistente. Y sobre todo, te ahorra que te rechacen el plugin en la revisión 😅.

Todo esto se instala con composer install que forma parte del postCreateCommand del Dev Container. Así que al abrir el proyecto ya tienes el linter configurado y listo para usar.

🎣 Git Hooks

Igual que en el artículo sobre pre-commit hooks en Java, aquí también he configurado un pre-commit hook que ejecuta PHP_CodeSniffer automáticamente antes de cada commit. Si el código no pasa el linter, el commit se bloquea:

#!/usr/bin/env bash

set -euo pipefail

if ! command -v php >/dev/null 2>&1; then
  echo "PHP is not installed. Skipping PHP pre-commit checks."
  exit 0
fi

staged_php_files="$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.php$' || true)"

if [[ -z "$staged_php_files" ]]; then
  echo "No staged PHP files."
  exit 0
fi

echo "Running PHP syntax checks on staged files..."
while IFS= read -r file; do
  [[ -z "$file" ]] && continue
  php -l "$file" >/dev/null
done <<< "$staged_php_files"

if [[ -x "vendor/bin/phpcs" ]]; then
  echo "Running PHPCS on staged files..."
  vendor/bin/phpcs --standard=phpcs.xml.dist $staged_php_files
else
  echo "PHPCS is not installed. Run 'composer install' to enable quality and security checks."
fi

El hook vive en .githooks/ y se instala con el script install-git-hooks.sh, que también se ejecuta como parte del setup del Dev Container. Así, al clonar y abrir el proyecto, los hooks ya están activos. Los desarrolladores no tienen que hacer nada manual.

🔄 GitHub Actions

Pero no se trata solo de validar en local. Para mí es igual de importante que estas mismas reglas se ejecuten en el CI, de forma que todo el código que llegue al repositorio siga exactamente el mismo estilo y formato. Si el lint pasa en tu máquina pero no se valida en el pipeline, al final cada uno acaba formateando como quiere y las reglas se convierten en papel mojado.

Así que el repositorio también tiene un workflow de CI en GitHub Actions que ejecuta PHP_CodeSniffer en cada push y pull request. Las mismas reglas, el mismo resultado.

💡 Lo que aprendí

Algunas cosas que me llevo:

WP-CLI es imprescindible en el Dev Container. Poder instalar WordPress, activar plugins, crear contenido de prueba y configurar permalinks desde un script automatizado hace que el setup sea completamente hands-off.

El bind mount del plugin es la clave. Montar el directorio del proyecto directamente en wp-content/plugins/ elimina cualquier fricción entre el código que editas y lo que WordPress ejecuta.

El readme.txt de WordPress.org no es un README normal. Tiene un formato específico con secciones predefinidas que el directorio parsea para mostrar la información del plugin. Es diferente del README.md de GitHub, así que necesitas mantener los dos.

PHP_CodeSniffer con WordPress Coding Standards es estricto pero necesario. Te fuerza a escribir código limpio y consistente desde el primer momento. Y tenerlo integrado en el Dev Container, en los git hooks y en el CI hace que no haya escapatoria 😄.

🚀 Cómo probarlo

Si quieres usar esta misma configuración para tu propio plugin de WordPress, puedes echar un vistazo a cómo lo tengo montado en el repositorio:

👉 github.com/0GiS0/markdown-view-for-agents

Clona el repo, ábrelo en VS Code y te preguntará si quieres reabrir el proyecto en el contenedor. Acepta y en unos minutos tendrás un WordPress funcionando con el plugin listo para probar. También puedes abrirlo directamente en GitHub Codespaces desde el repositorio, sin necesidad de tener Docker instalado en tu máquina. Si quieres saber más sobre Codespaces aquí tienes otro vídeo de mi canal de YouTube 😊

Y ahora crucemos los dedos a ver si me aceptan el plugin 🤞🏻

¡Nos vemos 👋🏻!

La entrada Mi configuración de Dev Container para desarrollar plugins de WordPress se publicó primero en return(GiS);.

Después de haber estado afinando mis dev containers para Spring Boot y Quarkus, esta vez me dio por investigar otra pieza importante del workflow de desarrollo: los pre-commit hooks.

En muchos proyectos es bastante habitual usar como herramienta pre-commit, el framework escrito en Python que permite ejecutar checks automáticos antes de hacer un commit. Funciona muy bien y es extremadamente popular… pero tiene un pequeño inconveniente en el contexto Java: introduce una dependencia externa que realmente no necesitamos. Y cuando estamos trabajando con Dev Containers, y por extensión con contenedores, cuanto más pequeña sea la imagen mejor que mejor. Si no sabes de qué va esto de los Dev Containers te dejo este vídeo que grabé hace tiempo para mi canal de YouTube:

Por lo que en este caso mi objetivo era claro 🎯: conseguir pre-commit hooks en proyectos Java sin obligar a nadie a instalar Python, o tener que incluirlo en la configuración del Dev Container, solo para ejecutar unas validaciones básicas de formato o estilo de código.

Pero no se trata solo de validar en local. Para mí es igual de importante que estas mismas reglas se ejecuten en el CI, de forma que todo el código que llegue al repositorio siga exactamente el mismo estilo y formato. Si el lint pasa en tu máquina pero no se valida en el pipeline, al final cada uno acaba formateando como quiere y las reglas se convierten en papel mojado.

Así que en este artículo te cuento cómo he configurado pre-commit hooks usando Spotless, Checkstyle y Gradle, de forma que podamos validar automáticamente el código antes de cada commit manteniéndonos completamente dentro del ecosistema Java.

📝 Modificar el archivo build.gradle

Lo primero que he necesitado hacer a sido modificar el archivo build.gradle que ya conoces, para poder instalar un par de plugins: checkstyle y com.diffplug.spotless:

plugins {
    id 'java'
    id 'checkstyle'                              // Plugin nativo de Gradle
    id 'com.diffplug.spotless' version '7.0.2'  // Formateo automático
}

Después en este mismo archivo, necesitas añadir el siguiente bloque:

spotless {
    java {
        target 'src/*/java/**/*.java'
        googleJavaFormat('1.25.2')      // Formateador de Google
        removeUnusedImports()
        importOrder('java', 'javax', 'jakarta', '', 'com.tuempresa')
        trimTrailingWhitespace()
        endWithNewline()
    }

    format 'misc', {
        target '*.md', '*.yml', '*.yaml', '*.properties', '*.gradle', '.gitignore'
        trimTrailingWhitespace()
        endWithNewline()
    }
}

Con este conseguimos:

• Un formato consistente usando Google Java Format
• Eliminación automática de imports no usados
• Un orden homogéneo de imports
• Archivos sin espacios sobrantes
• Aplicar las mismas reglas a ficheros no Java

Y ahora el bloque de Checkstyle:

checkstyle {
    toolVersion = '10.21.4'
    configFile = file("${rootDir}/config/checkstyle/checkstyle.xml")
    ignoreFailures = false
    maxWarnings = 0
}

Esto fuerza a que:

• Las reglas vivan dentro del repositorio
• Se use una versión concreta de Checkstyle
• El build falle ante cualquier warning

💄 Configuración de Checkstyle (config/checkstyle)

Para Checkstyle he creado un directorio específico dentro del proyecto:

config/
└── checkstyle/
    ├── checkstyle.xml
    └── suppressions.xml

Aquí es donde definimos las reglas principales:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">

<!--
    Checkstyle configuration based on Google Java Style Guide (simplified).
    Full guide: https://google.github.io/styleguide/javaguide.html

    Note: Formatting is handled by Spotless (google-java-format).
    This config focuses on naming conventions, best practices, and code quality.
-->
<module name="Checker">
    <property name="charset" value="UTF-8"/>
    <property name="severity" value="error"/>
    <property name="fileExtensions" value="java"/>

    <!-- Suppressions for test files (allow snake_case method names) -->
    <module name="SuppressionFilter">
        <property name="file" value="${config_loc}/suppressions.xml"/>
    </module>

    <!-- Suppress checks on generated sources -->
    <module name="BeforeExecutionExclusionFileFilter">
        <property name="fileNamePattern" value=".*[\\/]build[\\/].*"/>
    </module>

    <!-- File-level checks -->
    <module name="FileTabCharacter">
        <property name="eachLine" value="true"/>
    </module>

    <module name="LineLength">
        <property name="max" value="120"/>
        <property name="ignorePattern" value="^package.*|^import.*|a]* href|href|http://|https://|ftp://"/>
    </module>

    <module name="TreeWalker">
        <!-- ========== Naming Conventions ========== -->
        <module name="PackageName">
            <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
        </module>

        <module name="TypeName">
            <property name="format" value="^[A-Z][a-zA-Z0-9]*$"/>
        </module>

        <module name="MethodName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="MemberName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="ParameterName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="LocalVariableName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="ConstantName">
            <property name="format" value="^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
        </module>

        <!-- ========== Imports ========== -->
        <module name="AvoidStarImport"/>
        <module name="RedundantImport"/>
        <module name="UnusedImports"/>

        <!-- ========== Code Quality ========== -->
        <module name="EqualsHashCode"/>
        <module name="SimplifyBooleanExpression"/>
        <module name="SimplifyBooleanReturn"/>
        <module name="StringLiteralEquality"/>
        <module name="NestedTryDepth">
            <property name="max" value="2"/>
        </module>

        <!-- ========== Best Practices ========== -->
        <module name="OneStatementPerLine"/>
        <module name="MultipleVariableDeclarations"/>
        <module name="MissingSwitchDefault"/>
        <module name="DefaultComesLast"/>
        <module name="FallThrough"/>

        <!-- ========== Modifiers ========== -->
        <module name="ModifierOrder"/>
        <module name="RedundantModifier"/>

        <!-- ========== Annotations ========== -->
        <module name="MissingOverride"/>

        <!-- ========== Whitespace (complementary to Spotless) ========== -->
        <module name="NoWhitespaceAfter">
            <property name="tokens" value="AT,INC,DEC,UNARY_MINUS,UNARY_PLUS,BNOT,LNOT,DOT,ARRAY_DECLARATOR,INDEX_OP"/>
        </module>
        <module name="NoWhitespaceBefore"/>
    </module>
</module>

Está basado en la Google Java Style Guide, pero simplificado y con una idea clara:

Checkstyle valida, Spotless formatea. Y sí, es XML y parece sacado de los 90… pero es lo que hay 😄

El fichero incluye:

• Convenciones estrictas de nombres
• Control de imports
• Reglas de calidad de código
• Buenas prácticas
• Exclusión de código generado

Luego por otro lado tengo otro archivo llamado supressions.xml por si hay de alguna cosa de la que no quiero que se queje:

<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
    "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
    "https://checkstyle.org/dtds/suppressions_1_2.dtd">

<!--
    Checkstyle suppressions for test files.
    Allows snake_case method names in tests (common pattern: methodName_shouldDoSomething).
-->
<suppressions>
    <!-- Allow underscores in test method names (e.g., givenX_whenY_thenZ pattern) -->
    <suppress checks="MethodName" files=".*Test\.java$"/>
    <suppress checks="MethodName" files=".*IT\.java$"/>
</suppressions>

🎣 Script del pre-commit hook

Aquí es donde echo un poco de menos herramientas como pre-commit o Husky 🥲, porque en este caso toca crear el hook a mano.

El script vive en gradle/hooks/pre-commit:

#!/bin/bash
# =============================================================================
# Pre-commit hook for Sports Events Service
# Installed automatically by: ./gradlew installGitHooks
# =============================================================================

set -e

echo "🔍 Running pre-commit checks..."

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Get only staged Java files
STAGED_JAVA_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.java$' || true)

if [ -z "$STAGED_JAVA_FILES" ]; then
    echo -e "${YELLOW}No Java files staged for commit. Skipping Java checks.${NC}"
else
    # Check formatting with Spotless
    echo "📝 Checking code formatting (Spotless)..."
    if ! ./gradlew spotlessCheck --quiet 2>/dev/null; then
        echo -e "${RED}❌ Code formatting issues found!${NC}"
        echo -e "${YELLOW}Run './gradlew spotlessApply' to fix formatting automatically.${NC}"
        exit 1
    fi
    echo -e "${GREEN}✓ Code formatting OK${NC}"

    # Run Checkstyle
    echo "🔍 Checking code style (Checkstyle)..."
    if ! ./gradlew checkstyleMain checkstyleTest --quiet 2>/dev/null; then
        echo -e "${RED}❌ Checkstyle violations found!${NC}"
        echo "Check the report at: build/reports/checkstyle/"
        exit 1
    fi
    echo -e "${GREEN}✓ Checkstyle OK${NC}"
fi

# =============================================================================
# Agentic Workflows Validation
# Compile .md workflows in .github/workflows/ to ensure they are valid
# =============================================================================

# Get staged workflow markdown files
STAGED_WORKFLOW_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '^\.github/workflows/.*\.md$' || true)

if [ -z "$STAGED_WORKFLOW_FILES" ]; then
    echo -e "${YELLOW}No agentic workflow files staged. Skipping workflow validation.${NC}"
else
    echo "🤖 Validating agentic workflows..."
    
    # Check if gh aw is available
    if ! command -v gh &> /dev/null || ! gh aw --help &> /dev/null; then
        echo -e "${RED}❌ GitHub CLI with Agentic Workflows extension not found!${NC}"
        echo -e "${YELLOW}Install it with: gh extension install github/gh-aw${NC}"
        exit 1
    fi
    
    # Compile each staged workflow file
    for workflow in $STAGED_WORKFLOW_FILES; do
        echo "  Compiling: $workflow"
        if ! gh aw compile "$workflow" > /dev/null 2>&1; then
            echo -e "${RED}❌ Workflow compilation failed: $workflow${NC}"
            echo -e "${YELLOW}Run 'gh aw compile $workflow' to see errors.${NC}"
            exit 1
        fi
    done
    echo -e "${GREEN}✓ Agentic workflows OK${NC}"
fi

echo -e "${GREEN}✅ All pre-commit checks passed!${NC}"
exit 0

Y hace lo siguiente:

• Detecta si hay archivos Java en staging
• Ejecuta spotlessCheck
• Ejecuta checkstyleMain y checkstyleTest
• Bloquea el commit si algo falla

Además de todo esto estoy lanzando la herramienta gh aw para forzar la compilación de mis flujos agenticos de GitHub, que era uno de los motivos principales de querer todo esto 😇

🔄 Instalación automática del pre-commit hook

El último paso es instalar este script automáticamente usando Gradle:

// ============================================================================
// Git Hooks Installation
// ============================================================================

tasks.register('installGitHooks', Copy) {
    description = 'Installs pre-commit hooks into .git/hooks'
    group = 'git hooks'

    from("${rootDir}/gradle/hooks/") {
        include 'pre-commit'
    }
    into "${rootDir}/.git/hooks"
    filePermissions {
        user {
            read = true
            write = true
            execute = true
        }
        group {
            read = true
            execute = true
        }
        other {
            read = true
            execute = true
        }
    }
}

// Auto-install hooks on first build
tasks.named('compileJava') {
    dependsOn 'installGitHooks'
}

¿Qué conseguimos con esto?

• El hook se copia automáticamente a .git/hooks
• Tiene permisos de ejecución (755)
• Se instala en cualquier build
• Los desarrolladores no tienen que hacer nada manual
• Al clonar y compilar, los hooks ya están activos

Instalación manual si hiciera falta:

./gradlew installGitHooks  # Instalar/reinstalar hooks manualmente

y si quieres ver qué tareas tienes disponibles:

./gradlew tasks --group "git hooks"  # Ver tasks de hooks

¡Nos vemos 👋🏻!

La entrada Pre-commit hooks en Java sin Python: Spotless + Checkstyle + Gradle se publicó primero en return(GiS);.