gstack-upgrade

<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs --> # /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. On setup failure, follow Step 4's install-specific recovery: vendored installs restore their backup; git installs stop with the pre-upgrade commit recorded, without a destructive reset. Never claim restoration unless it actually succeeded. **Otherwise**, use AskUserQuestion: - Question: "gstack **v{new}** is available (you're on v{old}). Upgrade now?" Four fields (`UPGRADE_AVAILABLE <old> <old>+<n> <sha>`, main moved): ask "gstack main is **{n} commit(s)** past v{old} (at {sha}). 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 GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}" _SNOOZE_FILE="$GSTACK_STATE_ROOT/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. On a four-field line use the SHA (fourth field) as `{new}`, so the snooze ends when main moves. 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" elif _SRC=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT 2>/dev/null) && _SRC=$(awk -F '\t' '$(1) == "claude" && $(6) != "-" { print $(6); exit }' "$_SRC/installs.tsv" 2>/dev/null) && [ -d "$_SRC/.git" ]; then # The install registry names the checkout setup activated for this host (e.g. a ~/gstack clone). INSTALL_TYPE="global-git" INSTALL_DIR="$_SRC" else echo "ERROR: gstack not found" exit 1 fi INSTALL_DIR=$(cd -- "$INSTALL_DIR" && pwd -P) || { echo "ERROR: cannot enter the gstack install directory" >&2; exit 1; } echo "Install type: $INSTALL_TYPE at $INSTALL_DIR" ``` The install type and the absolute directory printed above are used in all subsequent steps. Carry `INSTALL_TYPE`, `INSTALL_DIR`, `OLD_VERSION`, and later `UPSTREAM_REF` and `NEW_VERSION` forward explicitly: tool calls may run in fresh shells, so start each later block by assigning them from the captured output (for example `INSTALL_DIR=/abs/path/printed/above`). Do not rely on a prior call's working directory or shell variables. Every block that changes files first checks `INSTALL_DIR` and stops before any git command when it is unset, empty, missing, unreadable, or not gstack's own checkout. ### Step 3: Save old version Use the install directory from Step 2's output below: ```bash OLD_VERSION=$(cat "${INSTALL_DIR:?INSTALL_DIR is not set: re-run Step 2 and substitute the printed path}/VERSION" 2>/dev/null || echo "unknown") echo "OLD_VERSION=$OLD_VERSION" ``` ### Step 4: Upgrade Use the install type and directory detected in Step 2: **For git installs** (global-git, local-git): Fast-forward first, through `bin/gstack-ff-update`, the same code the session-update auto-upgrade uses: local edits that merge cleanly ride over the update, and an edit that conflicts (or a staged change, or an unmerged file) is saved in a rescue ref instead of being left as conflict markers: ```bash cd -- "${INSTALL_DIR:?INSTALL_DIR is not set: re-run Step 2 and substitute the printed path}" || exit 1 { [ -f VERSION ] && [ -f setup ] && [ -f bin/gstack-config ] && _p=$(git rev-parse --show-prefix 2>/dev/null) && [ -z "$_p" ] && [ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ]; } || { echo "ERROR: $INSTALL_DIR is not a gstack checkout; nothing was changed. Re-run Step 2." >&2; exit 1; } git fetch origin # Channel ref (docs/releases.md): origin/stable for a team install, else origin/main _CH=$(bash bin/gstack-update-channel.sh --fetch-ref 2>&1) || _CH=origin/main echo "$_CH"; UPSTREAM_REF=$(printf '%s\n' "$_CH" | tail -1) echo "UPSTREAM_REF=${UPSTREAM_REF:=origin/main}" # Same pre-advance check as the auto-updater: the incoming release's Bun floor, # judged by bash whatever this tool shell is (zsh does not word-split). HOLD=$(UPSTREAM_REF="$UPSTREAM_REF" bash -c '. bin/gstack-bun-version.sh && gstack_bun_incoming_hold . "$UPSTREAM_REF"' 2>/dev/null) && { case "$HOLD" in bun-version-unreadable*) echo "BUN_VERSION_UNREADABLE: $HOLD; nothing was changed" >&2 ;; *) echo "BUN_TOO_OLD: $HOLD; nothing was changed" >&2 ;; esac; exit 1; } PRE_UPGRADE_COMMIT=$(git rev-parse HEAD) echo "PRE_UPGRADE_COMMIT=$PRE_UPGRADE_COMMIT" # Past the release (by ancestry, or by VERSION in a depth-1 clone): wait for stable; nothing moves back. if [ "$UPSTREAM_REF" = origin/stable ] && [ "$(git rev-parse origin/stable)" != "$PRE_UPGRADE_COMMIT" ] && ! git merge-base --is-ancestor HEAD origin/stable 2>/dev/null \ && { git merge-base --is-ancestor origin/stable HEAD 2>/dev/null || [ "$(printf '%s\n%s\n' "$(git show origin/stable:VERSION)" "$(cat VERSION)" | sort -V | tail -1)" = "$(cat VERSION)" ]; }; then echo "AHEAD_OF_STABLE"; exit 0; fi FF=$(bash bin/gstack-ff-update . "$UPSTREAM_REF"); FF_RC=$? echo "$FF" case "$FF_RC" in 0) if ./setup --refresh-registered; then echo "FF_OK"; else echo "SETUP_FAILED: git update succeeded; stop and inspect setup output (previous commit: $PRE_UPGRADE_COMMIT)" >&2; exit 1; fi ;; 4) echo "FF_REFUSED" ;; *) echo "FF_STOPPED: $FF" >&2; exit 1 ;; esac ``` Setup's `--refresh-registered` refreshes every install this checkout registered (each host, global and this project's), prints the source first, and ends with an `Upgrade summary` of one row per install. Relay those rows as printed. A `failed` row means that host kept its previous install; give its retry command and never say every host was refreshed. A `skipped` row belongs to another checkout or project; pass on its command, do not run it. If the output ends with `FF_OK`, the upgrade is done — skip the fallback below entirely. When the line before it reads `rescued <old> <new> refs/gstack/rescue/<oid> unmerged=<0|1>`, tell the user their conflicting local edits were saved there and relay the `Inspect`, `Export` and `Delete` commands the script printed (export into a scratch checkout with `git apply -3`, never `stash apply` in the install; `unmerged=1` means the rescue needs manual resolution). On `FF_STOPPED`, STOP and relay the reason: nothing was changed. On `AHEAD_OF_STABLE`, STOP: the checkout is already past the latest stable release, so nothing changes until the next cut (`gstack-config set update_channel main` follows every merge). On a `fetching origin/stable failed` line above, STOP and relay it; nothing was changed. `ff-busy` means another gstack update is running (retry in a minute); `autostash-unrecoverable` names what is in the way (an untracked file the release adds, or another git command); `index-unreadable` means the checkout's index is damaged. On `BUN_TOO_OLD`, STOP: tell the user to run `bun upgrade`, then /gstack-upgrade again. On `BUN_VERSION_UNREADABLE`, STOP: `bun --version` did not print a version gstack can read, so `bun upgrade` may not run either; tell the user to reinstall Bun from https://bun.sh (`curl -fsSL https://bun.sh/install | bash` in Git Bash or a macOS/Linux terminal), check that `bun --version` prints a version such as 1.4.2, then run /gstack-upgrade again (docs/troubleshooting.md#bun-version-unreadable). On `SETUP_FAILED`, STOP; keep user changes and report the recovery commit. There is no `.bak` on the git path. Do not enter the divergence fallback merely because setup failed. Enter it only on `FF_REFUSED` (local commits or a diverged history); network/auth failures stop for repair, not reset. **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: 1. Run `git status --porcelain` and `git rev-list "${UPSTREAM_REF:?}"..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:?INSTALL_DIR is not set: re-run Step 2 and substitute the printed path}" || exit 1 { [ -f VERSION ] && [ -f setup ] && [ -f bin/gstack-config ] && _p=$(git rev-parse --show-prefix 2>/dev/null) && [ -z "$_p" ] && [ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ]; } || { echo "ERROR: $INSTALL_DIR is not a gstack checkout; nothing was changed. Re-run Step 2." >&2; exit 1; } # Regenerable render-footprint dirt (setup re-renders it) never goes into the stash. git checkout -- 'SKILL.md' '*/SKILL.md' '*/sections/*.md' 2>/dev/null || true STASH_OUTPUT=$(git stash 2>&1) git reset --hard "${UPSTREAM_REF:?UPSTREAM_REF is not set: substitute the value Step 4 printed}" ./setup --refresh-registered ``` 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