# Gstack Upgrade > Actualiza gstack a la última versión. Fuente: https://skillsagentes.com/skills/garrytan/gstack/gstack-upgrade Markdown: https://skillsagentes.com/skills/garrytan/gstack/gstack-upgrade.md Repositorio: https://github.com/garrytan/gstack Autor: garrytan Licencia: MIT Actualizado: anteayer Coste de contexto: 9 tok instalada, 3.8k tok al activarse, 21.4k tok con todos los archivos del bundle Bundle: 14 archivos, 83 KB Permisos que pide: bash, read, write, askuserquestion ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add garrytan/gstack --skill gstack-upgrade --agent claude-code # Cursor npx -y skills add garrytan/gstack --skill gstack-upgrade --agent cursor # Codex npx -y skills add garrytan/gstack --skill gstack-upgrade --agent codex # Gemini CLI npx -y skills add garrytan/gstack --skill gstack-upgrade --agent gemini # Windsurf npx -y skills add garrytan/gstack --skill gstack-upgrade --agent windsurf # Cline npx -y skills add garrytan/gstack --skill gstack-upgrade --agent cline ``` ## Qué hace - Detecta si gstack está instalado globalmente o vendorizado y ejecuta el flujo de actualización correspondiente - Actualiza vía git pull --ff-only o reclona en instalaciones vendorizadas, luego corre ./setup - Ejecuta migraciones de versión pendientes y detiene daemons de browse obsoletos - Sincroniza o elimina copias vendorizadas locales según si el modo equipo está activo - Muestra un resumen de las novedades desde CHANGELOG.md tras la actualización ## Cuándo usarla - El usuario pide "upgrade gstack", "update gstack" o "get latest version" - Otro skill detecta UPGRADE_AVAILABLE y necesita delegar el flujo de actualización - Se invoca directamente como /gstack-upgrade para forzar una verificación de actualización ## Qué la activa - "Actualiza gstack a la última versión" - "/gstack-upgrade" - "Hay una nueva versión de gstack, instálala" ## Antes de instalar - Requiere una instalación previa de gstack (global vía git, local vía git, o vendorizada) y acceso a bin/gstack-config y bin/gstack-update-check. - Necesita en el PATH: awk, git, sed - Variables de entorno: BROWSE_STATE_FILE, DAEMON_PID, DAEMON_PORT, GSTACK_AUTO_UPGRADE, INSTALL_DIR, INSTALL_DIR_PLACEHOLDER, INSTALL_TYPE, LOCAL_GSTACK, LOCAL_VER, MIGRATIONS_DIR, NEW_HASH, OLD_HASH, OLD_VERSION, PRIMARY_VER, TMP_DIR - runs shell commands - writes to your files - makes network requests - reads environment config ## Archivos - SKILL.md — 15 KB - SKILL.md.tmpl — 15 KB - migrations/v0.15.2.0.sh — 854 B - migrations/v0.16.2.0.sh — 2 KB - migrations/v1.0.0.0.sh — 2 KB - migrations/v1.1.3.0.sh — 6 KB - migrations/v1.17.0.0.sh — 2 KB - migrations/v1.27.0.0.sh — 16 KB - migrations/v1.37.0.0.sh — 4 KB - migrations/v1.38.1.0.sh — 4 KB - migrations/v1.40.0.0.sh — 5 KB - migrations/v1.58.0.0.sh — 2 KB - migrations/v1.65.0.0.sh — 7 KB - migrations/v1.67.0.0.sh — 3 KB ## SKILL.md Reproducido tal cual desde garrytan/gstack bajo MIT. Esta sección es el documento original y está en inglés. ## When to invoke this skill Detects global vs vendored install, runs the upgrade, and shows what's new. Use when asked to "upgrade gstack", "update gstack", or "get latest version". Voice triggers (speech-to-text aliases): "upgrade the tools", "update the tools", "gee stack upgrade", "g stack upgrade". # /gstack-upgrade Upgrade gstack to the latest version and show what's new. ## Inline upgrade flow This section is referenced by all skill preambles when they detect `UPGRADE_AVAILABLE`. ### Step 1: Ask the user (or auto-upgrade) First, check if auto-upgrade is enabled: ```bash _AUTO="" [ "${GSTACK_AUTO_UPGRADE:-}" = "1" ] && _AUTO="true" [ -z "$_AUTO" ] && _AUTO=$(~/.claude/skills/gstack/bin/gstack-config get auto_upgrade 2>/dev/null || true) echo "AUTO_UPGRADE=$_AUTO" ``` **If `AUTO_UPGRADE=true` or `AUTO_UPGRADE=1`:** Skip AskUserQuestion. Log "Auto-upgrading gstack v{old} → v{new}..." and proceed directly to Step 2. If `./setup` fails during auto-upgrade, restore from backup (`.bak` directory) and warn the user: "Auto-upgrade failed — restored previous version. Run `/gstack-upgrade` manually to retry." **Otherwise**, use AskUserQuestion: - Question: "gstack **v{new}** is available (you're on v{old}). Upgrade now?" - Options: ["Yes, upgrade now", "Always keep me up to date", "Not now", "Never ask again"] **If "Yes, upgrade now":** Proceed to Step 2. **If "Always keep me up to date":** ```bash ~/.claude/skills/gstack/bin/gstack-config set auto_upgrade true ``` Tell user: "Auto-upgrade enabled. Future updates will install automatically." Then proceed to Step 2. **If "Not now":** Write snooze state with escalating backoff (first snooze = 24h, second = 48h, third+ = 1 week), then continue with the current skill. Do not mention the upgrade again. ```bash _SNOOZE_FILE="$HOME/.gstack/update-snoozed" _REMOTE_VER="{new}" _CUR_LEVEL=0 if [ -f "$_SNOOZE_FILE" ]; then _SNOOZED_VER=$(awk '{print $1}' "$_SNOOZE_FILE") if [ "$_SNOOZED_VER" = "$_REMOTE_VER" ]; then _CUR_LEVEL=$(awk '{print $2}' "$_SNOOZE_FILE") case "$_CUR_LEVEL" in *[!0-9]*) _CUR_LEVEL=0 ;; esac fi fi _NEW_LEVEL=$((_CUR_LEVEL + 1)) [ "$_NEW_LEVEL" -gt 3 ] && _NEW_LEVEL=3 echo "$_REMOTE_VER $_NEW_LEVEL $(date +%s)" > "$_SNOOZE_FILE" ``` Note: `{new}` is the remote version from the `UPGRADE_AVAILABLE` output — substitute it from the update check result. Tell user the snooze duration: "Next reminder in 24h" (or 48h or 1 week, depending on level). Tip: "Set `auto_upgrade: true` in `~/.gstack/config.yaml` for automatic upgrades." **If "Never ask again":** ```bash ~/.claude/skills/gstack/bin/gstack-config set update_check false ``` Tell user: "Update checks disabled. Run `~/.claude/skills/gstack/bin/gstack-config set update_check true` to re-enable." Continue with the current skill. ### Step 2: Detect install type ```bash if [ -d "$HOME/.claude/skills/gstack/.git" ]; then INSTALL_TYPE="global-git" INSTALL_DIR="$HOME/.claude/skills/gstack" elif [ -d "$HOME/.gstack/repos/gstack/.git" ]; then INSTALL_TYPE="global-git" INSTALL_DIR="$HOME/.gstack/repos/gstack" elif [ -d ".claude/skills/gstack/.git" ]; then INSTALL_TYPE="local-git" INSTALL_DIR=".claude/skills/gstack" elif [ -d ".agents/skills/gstack/.git" ]; then INSTALL_TYPE="local-git" INSTALL_DIR=".agents/skills/gstack" elif [ -d ".claude/skills/gstack" ]; then INSTALL_TYPE="vendored" INSTALL_DIR=".claude/skills/gstack" elif [ -d "$HOME/.claude/skills/gstack" ]; then INSTALL_TYPE="vendored-global" INSTALL_DIR="$HOME/.claude/skills/gstack" else echo "ERROR: gstack not found" exit 1 fi echo "Install type: $INSTALL_TYPE at $INSTALL_DIR" ``` The install type and directory path printed above will be used in all subsequent steps. ### Step 3: Save old version Use the install directory from Step 2's output below: ```bash OLD_VERSION=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown") ``` ### Step 4: Upgrade Use the install type and directory detected in Step 2: **For git installs** (global-git, local-git): Fast-forward first (#2517) — the same policy the session-update auto-upgrade uses. `--autostash` carries local edits over the pull; render-footprint dirt is discarded first because it is regenerable and poisons stashes (#2569): ```bash cd "$INSTALL_DIR" # Discard render-footprint dirt (#2569): pre-v1.67 gbrain-enabled installs # ran gen:skill-docs:user IN PLACE, leaving generated SKILL.md / sections # files permanently modified. They are regenerable (setup re-renders to # ~/.gstack/render), so discarding is lossless. git checkout -- 'SKILL.md' '*/SKILL.md' '*/sections/*.md' 2>/dev/null || true git fetch origin git pull --ff-only --autostash origin main && ./setup && echo "FF_OK" ``` If the output ends with `FF_OK`, the upgrade is done — skip the fallback below entirely. **Fallback (ff-only refused — local commits or divergence).** `git reset --hard` DESTROYS things: a clean tree with unpushed local commits still loses those commits. Gate it (#2517): 1. Run `git status --porcelain` and `git rev-list origin/main..HEAD --oneline` in `$INSTALL_DIR`. 2. If BOTH are empty, the reset is provably safe — run the fallback block below without asking. 3. Otherwise ask via AskUserQuestion (one-way door — destructive), listing exactly what will be discarded: each dirty file and each unpushed commit by hash + subject. Options: **A)** Discard them and upgrade (reset) — requires the explicit letter; **B)** Abort the upgrade so the user can rescue their work first (recommended when local commits exist). Never proceed on a vague reply. ```bash cd "$INSTALL_DIR" STASH_OUTPUT=$(git stash 2>&1) git reset --hard origin/main ./setup ``` If `$STASH_OUTPUT` contains "Saved working directory", warn the user: "Note: local changes were stashed (any modified generated SKILL.md/sections files were discarded first — they regenerate on setup). Run `git stash pop` in the skill directory to restore your own changes." **For vendored installs** (vendored, vendored-global): ```bash PARENT=$(dirname "$INSTALL_DIR") TMP_DIR=$(mktemp -d) git clone --depth 1 https://github.com/garrytan/gstack.git "$TMP_DIR/gstack" mv "$INSTALL_DIR" "$INSTALL_DIR.bak" mv "$TMP_DIR/gstack" "$INSTALL_DIR" cd "$INSTALL_DIR" && ./setup rm -rf "$INSTALL_DIR.bak" "$TMP_DIR" ``` ### Step 4.5: Handle local vendored copy Use the install directory from Step 2. Check if there's also a local vendored copy, and whether team mode is active: ```bash _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) LOCAL_GSTACK="" if [ -n "$_ROOT" ] && [ -d "$_ROOT/.claude/skills/gstack" ]; then _RESOLVED_LOCAL=$(cd "$_ROOT/.claude/skills/gstack" && pwd -P) _RESOLVED_PRIMARY=$(cd "$INSTALL_DIR" && pwd -P) if [ "$_RESOLVED_LOCAL" != "$_RESOLVED_PRIMARY" ]; then LOCAL_GSTACK="$_ROOT/.claude/skills/gstack" fi fi _TEAM_MODE=$(~/.claude/skills/gstack/bin/gstack-config get team_mode 2>/dev/null || echo "false") echo "LOCAL_GSTACK=$LOCAL_GSTACK" echo "TEAM_MODE=$_TEAM_MODE" ``` **If `LOCAL_GSTACK` is non-empty AND `TEAM_MODE` is `true`:** Remove the vendored copy. Team mode uses the global install as the single source of truth. ```bash cd "$_ROOT" git rm -r --cached .claude/skills/gstack/ 2>/dev/null || true if ! grep -qF '.claude/skills/gstack/' .gitignore 2>/dev/null; then echo '.claude/skills/gstack/' >> .gitignore fi rm -rf "$LOCAL_GSTACK" ``` Tell user: "Removed vendored copy at `$LOCAL_GSTACK` (team mode active — global install is the source of truth). Commit the `.gitignore` change when ready." **If `LOCAL_GSTACK` is non-empty AND `TEAM_MODE` is NOT `true`:** Update it by copying from the freshly-upgraded primary install (same approach as README vendored install): ```bash mv "$LOCAL_GSTACK" "$LOCAL_GSTACK.bak" cp -Rf "$INSTALL_DIR" "$LOCAL_GSTACK" rm -rf "$LOCAL_GSTACK/.git" cd "$LOCAL_GSTACK" && ./setup rm -rf "$LOCAL_GSTACK.bak" ``` Tell user: "Also updated vendored copy at `$LOCAL_GSTACK` — commit `.claude/skills/gstack/` when you're ready." If `./setup` fails, restore from backup and warn the user: ```bash rm -rf "$LOCAL_GSTACK" mv "$LOCAL_GSTACK.bak" "$LOCAL_GSTACK" ``` Tell user: "Sync failed — restored previous version at `$LOCAL_GSTACK`. Run `/gstack-upgrade` manually to retry." ### Step 4.75: Run version migrations After `./setup` completes, run any migration scripts for versions between the old and new version. Migrations handle state fixes that `./setup` alone can't cover (stale config, orphaned files, directory structure changes). ```bash MIGRATIONS_DIR="$INSTALL_DIR/gstack-upgrade/migrations" if [ -d "$MIGRATIONS_DIR" ]; then for migration in $(find "$MIGRATIONS_DIR" -maxdepth 1 -name 'v*.sh' -type f 2>/dev/null | sort -V); do # Extract version from filename: v0.15.2.0.sh → 0.15.2.0 m_ver="$(basename "$migration" .sh | sed 's/^v//')" # Run if this migration version is newer than old version # (simple string compare works for dotted versions with same segment count) if [ "$OLD_VERSION" != "unknown" ] && [ "$(printf '%s\n%s' "$OLD_VERSION" "$m_ver" | sort -V | head -1)" = "$OLD_VERSION" ] && [ "$OLD_VERSION" != "$m_ver" ]; then echo "Running migration $m_ver..." # GSTACK_INSTALL_DIR: migrations that clean the INSTALL (not just # ~/.gstack state) default to ~/.claude/skills/gstack when unset — # a repo-local install would silently no-op without this. GSTACK_INSTALL_DIR="$INSTALL_DIR" bash "$migration" || echo " Warning: migration $m_ver had errors (non-fatal)" fi done fi ``` Migrations are idempotent bash scripts in `gstack-upgrade/migrations/`. Each is named `v{VERSION}.sh` and runs only when upgrading from an older version. See CONTRIBUTING.md for how to add new migrations. ### Step 4.8: Stop any stale daemon (unconditional) A browse daemon started before the upgrade keeps serving the OLD binary's code until it is stopped — it survives `git reset --hard` and `./setup` because the running process holds the old executable (#2551). Always run this step, using the install directory detected in Step 2. ```bash INSTALL_DIR_PLACEHOLDER="" NEW_HASH=$(cat "$INSTALL_DIR_PLACEHOLDER/browse/dist/.version" 2>/dev/null || echo "") _STATE_FILE="${BROWSE_STATE_FILE:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/browse.json}" if [ -z "$NEW_HASH" ] || [ ! -f "$_STATE_FILE" ]; then echo "DAEMON_CHECK=none (no state file or no fresh build hash)" else DAEMON_PID=$(sed -n 's/.*"pid"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$_STATE_FILE" | head -1) DAEMON_PORT=$(sed -n 's/.*"port"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$_STATE_FILE" | head -1) OLD_HASH=$(sed -n 's/.*"binaryVersion"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_STATE_FILE" | head -1) if [ -z "$DAEMON_PID" ] || ! kill -0 "$DAEMON_PID" 2>/dev/null; then echo "DAEMON_CHECK=dead (no live daemon to stop)" elif [ "$OLD_HASH" = "$NEW_HASH" ]; then echo "DAEMON_CHECK=current (daemon already runs the new binary)" elif curl -fsS --max-time 2 "http://127.0.0.1:$DAEMON_PORT/health" 2>/dev/null | grep -q '"status":"healthy"'; then echo "DAEMON_CHECK=stale-responsive pid=$DAEMON_PID hash=${OLD_HASH:-unknown} -> $NEW_HASH" "$INSTALL_DIR_PLACEHOLDER/browse/dist/browse" stop && echo "DAEMON_STOPPED=yes" else echo "DAEMON_CHECK=stale-busy pid=$DAEMON_PID hash=${OLD_HASH:-unknown} -> $NEW_HASH" fi fi ``` Replace `` with the actual install directory before running. Interpret the `DAEMON_CHECK` result: 1. **`stale-responsive` + `DAEMON_STOPPED=yes`:** Tell the user "Stopped the old browse daemon (binary {OLD_HASH} → {NEW_HASH}). The next browse command starts a fresh daemon on the new binary." 2. **`stale-busy`:** The daemon runs the old binary but is mid-work — DEFER to it, never kill a busy daemon during upgrade. Tell the user: "A browse daemon is still running the pre-upgrade binary ({OLD_HASH} → {NEW_HASH}) but is busy right now. When it finishes, stop it with `browse stop` — or force it immediately with `browse --force-restart stop` (loses that session's tabs/cookies/logins)." 3. **`none` / `dead` / `current`:** Nothing to do — say nothing. ### Step 5: Write marker + clear cache ```bash mkdir -p ~/.gstack echo "$OLD_VERSION" > ~/.gstack/just-upgraded-from rm -f ~/.gstack/last-update-check rm -f ~/.gstack/update-snoozed ``` ### Step 6: Show What's New Read `$INSTALL_DIR/CHANGELOG.md`. Find all version entries between the old version and the new version. Summarize as 5-7 bullets grouped by theme. Don't overwhelm — focus on user-facing changes. Skip internal refactors unless they're significant. Format: ``` gstack v{new} — upgraded from v{old}! What's new: - [bullet 1] - [bullet 2] - ... Happy shipping! ``` ### Step 7: Continue After showing What's New, continue with whatever skill the user originally invoked. The upgrade is done — no further action needed. --- ## Standalone usage When invoked directly as `/gstack-upgrade` (not from a preamble): 1. Force a fresh update check (bypass cache): ```bash ~/.claude/skills/gstack/bin/gstack-update-check --force 2>/dev/null || \ .claude/skills/gstack/bin/gstack-update-check --force 2>/dev/null || true ``` Use the output to determine if an upgrade is available. 2. If `UPGRADE_AVAILABLE `: follow Steps 2-6 above. 3. If no output (primary is up to date): check for a stale local vendored copy. Run the Step 2 bash block above to detect the primary install type and directory (`INSTALL_TYPE` and `INSTALL_DIR`). Then run the Step 4.5 detection bash block above to check for a local vendored copy (`LOCAL_GSTACK`) and team mode status (`TEAM_MODE`). **If `LOCAL_GSTACK` is empty** (no local vendored copy): tell the user "You're already on the latest version (v{version})." **If `LOCAL_GSTACK` is non-empty AND `TEAM_MODE` is `true`:** Remove the vendored copy using the Step 4.5 team-mode removal bash block above. Tell user: "Global v{version} is up to date. Removed stale vendored copy (team mode active). Commit the `.gitignore` change when ready." **If `LOCAL_GSTACK` is non-empty AND `TEAM_MODE` is NOT `true`**, compare versions: ```bash PRIMARY_VER=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown") LOCAL_VER=$(cat "$LOCAL_GSTACK/VERSION" 2>/dev/null || echo "unknown") echo "PRIMARY=$PRIMARY_VER LOCAL=$LOCAL_VER" ``` **If versions differ:** follow the Step 4.5 sync bash block above to update the local copy from the primary. Tell user: "Global v{PRIMARY_VER} is up to date. Updated local vendored copy from v{LOCAL_VER} → v{PRIMARY_VER}. Commit `.claude/skills/gstack/` when you're ready." **If versions match:** tell the user "You're on the latest version (v{PRIMARY_VER}). Global and local vendored copy are both up to date." ## Dónde encaja - Categoría: [DevOps e infraestructura](https://skillsagentes.com/categorias/devops-infraestructura.md) — Despliegues, contenedores, IaC y flujos de gestión de incidentes. - Creador: [garrytan](https://skillsagentes.com/creators/garrytan.md) — 134 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Browse](https://skillsagentes.com/skills/garrytan/gstack/browse.md): Navegador headless rápido para QA testing y dogfooding de sitios (gstack). - [Ship](https://skillsagentes.com/skills/garrytan/gstack/ship.md): Flujo de ship: detecta y fusiona la rama base, corre tests, revisa el diff, sube VERSION, actualiza CHANGELOG, hace commit, push y crea el PR (gstack). - [Ios Qa](https://skillsagentes.com/skills/garrytan/gstack/ios-qa.md): QA en dispositivo iOS real para apps SwiftUI, con bucle de agente guiado por visión sobre USB (gstack). - [Plan Design Review](https://skillsagentes.com/skills/garrytan/gstack/plan-design-review.md): Revisión de planes con ojo de diseñador — interactiva, al estilo de las revisiones de CEO e Ingeniería. (gstack) - [Plan Eng Review](https://skillsagentes.com/skills/garrytan/gstack/plan-eng-review.md): Revisión de plan en modo gerente de ingeniería: arquitectura, flujo de datos, diagramas, casos límite, cobertura de pruebas y rendimiento. (gstack) ## Skills relacionadas - [Wizard](https://skillsagentes.com/skills/mattpocock/skills/wizard.md): Genera un wizard bash interactivo que guía a un humano por los pasos que solo él puede dar. Úsalo para aprovisionar infraestructura, credenciales o secretos de CI, o una migración puntual. - [Canary](https://skillsagentes.com/skills/garrytan/gstack/canary.md): Monitoreo canary post-deploy: vigila la app en producción tras el despliegue. (gstack) - [Land And Deploy](https://skillsagentes.com/skills/garrytan/gstack/land-and-deploy.md): Fusiona el PR, espera CI y el despliegue, y verifica la salud de producción con checks canary. Continúa el trabajo que /ship dejó iniciado. (gstack) - [Landing Report](https://skillsagentes.com/skills/garrytan/gstack/landing-report.md): Panel de solo lectura sobre la cola de versiones, consciente de los workspaces (gstack). - [Setup Deploy](https://skillsagentes.com/skills/garrytan/gstack/setup-deploy.md): Configura los ajustes de despliegue para /land-and-deploy. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)