Versión mala de un plugin de Claude Code: cómo volver atrás sin perder el changelog
Hola, bienvenido. En esta lección vamos a publicar una versión del plugin que rompe el hook de todo el equipo. Vamos a ver qué le pasa a quien la instala y cómo se retira. La vuelta atrás tiene una forma correcta y otra que parece más rápida y borra la historia del plugin, y vamos a ver por qué la segunda no vale.
Marta quiere que el hook que comprueba el repo sea más estricto en los repos que lo pidan. Con una variable nueva en el env del repo, TEAM_STRICT, doctor.sh comprobará además que nadie ha subido a git los archivos personales, .claude/settings.local.json y CLAUDE.local.md. Es un cambio pequeño, y tiene prisa.
Hasta ahora, cada pieza del repo del plugin ha hecho su trabajo: el changelog, los tests, el pre-push y los tags. Con una versión mala vamos a ver qué detiene cada una, qué deja pasar y qué le llega al equipo cuando alguien decide saltarse una barrera. Y vamos a terminar con una versión que corrige el error, con la entrada de la versión mala todavía en el changelog y un test nuevo para que el mismo error no vuelva a salir.
La 1.2.0: el modo estricto de doctor.sh
Vamos a añadir el cambio en claude-plugins/plugins/team/scripts/doctor.sh, justo antes de decidir si hay algo que avisar:
1
2set -euo pipefail
3
4input=$(cat)
5
6if ! command -v jq >/dev/null 2>&1; then
7 message="team doctor: falta jq en esta máquina y no puede comprobar el repo. Instálalo con sudo apt-get install jq (Ubuntu, Debian o WSL2) o brew install jq (macOS) y abre otra sesión."
8 printf '{"systemMessage":"%s","hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$message" "$message"
9 exit 0
10fi
11
12cwd=$(jq -r '.cwd // empty' <<<"$input")
13root=$(cd "$(dirname "$0")/.." && pwd)
14cd "${cwd:-.}"
15
16contract='["qa","test","test:arch","pint","pint:all","pint:test","phpstan","rector","rector:dry"]'
17gitignore_lines='/.claude/settings.local.json CLAUDE.local.md'
18problems=""
19
20warn() {
21 problems="$problems
22- $1"
23}
24
25version_lt() {
26 local IFS=.
27 local a=($1) b=($2) i
28 for i in 0 1 2; do
29 [ "${a[i]:-0}" -lt "${b[i]:-0}" ] && return 0
30 [ "${a[i]:-0}" -gt "${b[i]:-0}" ] && return 1
31 done
32 return 1
33}
34
35if [ -f composer.json ]; then
36 missing=$(jq -r --argjson contract "$contract" '$contract - (.scripts // {} | keys) | join(", ")' composer.json)
37 [ -z "$missing" ] || warn "faltan scripts del contrato en composer.json ($missing): pide a Claude que los añada con /team:doctor."
38else
39 warn "no hay composer.json en $PWD."
40fi
41
42for line in $gitignore_lines; do
43 grep -qxF "$line" .gitignore 2>/dev/null || warn "falta $line en .gitignore: añádelo con echo '$line' >> .gitignore."
44done
45
46installed=$(jq -r '.version' "$root/.claude-plugin/plugin.json")
47minimum=${TEAM_PLUGIN_MIN:-}
48if [ -n "$minimum" ] && version_lt "$installed" "$minimum"; then
49 warn "el plugin team está en $installed y este repo pide $minimum o superior: actualízalo con claude plugin update team@cursosdesarrolloweb --scope project."
50fi
51
+if [ "$TEAM_STRICT" = 1 ]; then
+ for file in .claude/settings.local.json CLAUDE.local.md; do
+ if git ls-files --error-unmatch "$file" >/dev/null 2>&1; then
+ warn "$file es personal y está en git: sácalo con git rm --cached $file."
+ fi
+ done
+fi
+
60[ -n "$problems" ] || exit 0
61
62message="team doctor ha encontrado problemas en este repo:$problems"
63jq -n --arg message "$message" '{
64 systemMessage: $message,
65 hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $message}
66}'
1
2set -euo pipefail
3
4input=$(cat)
5
6if ! command -v jq >/dev/null 2>&1; then
7 message="team doctor: falta jq en esta máquina y no puede comprobar el repo. Instálalo con sudo apt-get install jq (Ubuntu, Debian o WSL2) o brew install jq (macOS) y abre otra sesión."
8 printf '{"systemMessage":"%s","hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$message" "$message"
9 exit 0
10fi
11
12cwd=$(jq -r '.cwd // empty' <<<"$input")
13root=$(cd "$(dirname "$0")/.." && pwd)
14cd "${cwd:-.}"
15
16contract='["qa","test","test:arch","pint","pint:all","pint:test","phpstan","rector","rector:dry"]'
17gitignore_lines='/.claude/settings.local.json CLAUDE.local.md'
18problems=""
19
20warn() {
21 problems="$problems
22- $1"
23}
24
25version_lt() {
26 local IFS=.
27 local a=($1) b=($2) i
28 for i in 0 1 2; do
29 [ "${a[i]:-0}" -lt "${b[i]:-0}" ] && return 0
30 [ "${a[i]:-0}" -gt "${b[i]:-0}" ] && return 1
31 done
32 return 1
33}
34
35if [ -f composer.json ]; then
36 missing=$(jq -r --argjson contract "$contract" '$contract - (.scripts // {} | keys) | join(", ")' composer.json)
37 [ -z "$missing" ] || warn "faltan scripts del contrato en composer.json ($missing): pide a Claude que los añada con /team:doctor."
38else
39 warn "no hay composer.json en $PWD."
40fi
41
42for line in $gitignore_lines; do
43 grep -qxF "$line" .gitignore 2>/dev/null || warn "falta $line en .gitignore: añádelo con echo '$line' >> .gitignore."
44done
45
46installed=$(jq -r '.version' "$root/.claude-plugin/plugin.json")
47minimum=${TEAM_PLUGIN_MIN:-}
48if [ -n "$minimum" ] && version_lt "$installed" "$minimum"; then
49 warn "el plugin team está en $installed y este repo pide $minimum o superior: actualízalo con claude plugin update team@cursosdesarrolloweb --scope project."
50fi
51
52if [ "$TEAM_STRICT" = 1 ]; then
53 for file in .claude/settings.local.json CLAUDE.local.md; do
54 if git ls-files --error-unmatch "$file" >/dev/null 2>&1; then
55 warn "$file es personal y está en git: sácalo con git rm --cached $file."
56 fi
57 done
58fi
59
60[ -n "$problems" ] || exit 0
61
62message="team doctor ha encontrado problemas en este repo:$problems"
63jq -n --arg message "$message" '{
64 systemMessage: $message,
65 hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $message}
66}'
Fíjate en la línea de minimum, unas líneas más arriba: TEAM_PLUGIN_MIN se lee con ${TEAM_PLUGIN_MIN:-}, que da un valor vacío si la variable no existe. TEAM_STRICT se lee sin valor por defecto. Con set -u, que el script tiene desde la primera versión, bash termina con error en cuanto lee una variable que no existe. Y TEAM_STRICT no existe en ningún repo del equipo, porque es nueva. Un repo que quiera el modo estricto tiene que añadir "TEAM_STRICT": "1" a su env, igual que hizo helpdesk con TEAM_PLUGIN_MIN, y los demás no tendrían que notar nada.
Vamos a añadir la entrada a claude-plugins/plugins/team/CHANGELOG.md:
1# Changelog del plugin team
2
3Cada versión publicada tiene aquí su entrada, también la de una versión que haya que retirar. Ninguna entrada se borra.
4
+## 1.2.0
+
+- Modo estricto de `doctor.sh`: con `TEAM_STRICT` a `1` en el `env` del repo, avisa también si `.claude/settings.local.json` o `CLAUDE.local.md` están en git.
+- Qué tienes que hacer: actualizar con `claude plugin update team@cursosdesarrolloweb --scope project`. El modo estricto lo activa cada repo, si quiere.
+
10## 1.1.0
11
12- `doctor.sh` comprueba que `jq` está instalado antes de usarlo. Si falta, avisa con el comando para instalarlo, en vez de fallar al arrancar la sesión.
13- Qué tienes que hacer: actualizar con `claude plugin update team@cursosdesarrolloweb --scope project` en cada repo. Si el aviso dice que falta `jq`, instalarlo.
14
15## 1.0.0
16
17- Skill `conventional-commits`, movida desde `.claude/skills/` de `helpdesk`.
18- Skill `doctor` y hook `SessionStart` que comprueban el contrato del repo: los scripts de Composer, las líneas de `.gitignore` y la versión mínima del plugin que pide `TEAM_PLUGIN_MIN`.
19- `tests/run.sh`, con las fixtures de `SessionStart`.
1# Changelog del plugin team
2
3Cada versión publicada tiene aquí su entrada, también la de una versión que haya que retirar. Ninguna entrada se borra.
4
5## 1.2.0
6
7- Modo estricto de `doctor.sh`: con `TEAM_STRICT` a `1` en el `env` del repo, avisa también si `.claude/settings.local.json` o `CLAUDE.local.md` están en git.
8- Qué tienes que hacer: actualizar con `claude plugin update team@cursosdesarrolloweb --scope project`. El modo estricto lo activa cada repo, si quiere.
9
10## 1.1.0
11
12- `doctor.sh` comprueba que `jq` está instalado antes de usarlo. Si falta, avisa con el comando para instalarlo, en vez de fallar al arrancar la sesión.
13- Qué tienes que hacer: actualizar con `claude plugin update team@cursosdesarrolloweb --scope project` en cada repo. Si el aviso dice que falta `jq`, instalarlo.
14
15## 1.0.0
16
17- Skill `conventional-commits`, movida desde `.claude/skills/` de `helpdesk`.
18- Skill `doctor` y hook `SessionStart` que comprueban el contrato del repo: los scripts de Composer, las líneas de `.gitignore` y la versión mínima del plugin que pide `TEAM_PLUGIN_MIN`.
19- `tests/run.sh`, con las fixtures de `SessionStart`.
Y vamos a subir la versión en claude-plugins/plugins/team/.claude-plugin/plugin.json:
1{
2 "name": "team",
3 "description": "Cómo trabaja el equipo con Claude Code: las skills y los hooks comunes a todos los repos",
− "version": "1.1.0",
+ "version": "1.2.0",
5 "author": {
6 "name": "cursosdesarrolloweb"
7 }
8}
1{
2 "name": "team",
3 "description": "Cómo trabaja el equipo con Claude Code: las skills y los hooks comunes a todos los repos",
4 "version": "1.2.0",
5 "author": {
6 "name": "cursosdesarrolloweb"
7 }
8}
Lo que queda de esta lección
- 02validate no lo ve, tests/run.sh sí
- 03Lo que ve el equipo con la 1.2.0
- 04Volver atrás sin perder el changelog
- 05La fixture que lo habría parado
- 06La 1.2.1: retirar la 1.2.0
- 07El repo pide la 1.2.1
Sigue leyendo con tu suscripción
El curso completo, con su proyecto final, el certificado y el foro, está incluido en la suscripción.
Ver los planes
¿Ya tienes cuenta? Entra
