Обзор gstack: /gstack-upgrade

Slash-команда /gstack-upgrade предназначена для обновления инструментов gstack до последней версии, обеспечивая актуальность и доступность новых функций и исправлений. Этот навык может быть запущен как вручную, так и автоматически, предлагая пользователю различные опции управления обновлениями.

Кому полезен: Разработчики, QA-инженеры, релиз-менеджеры, системные администраторы. Категория процесса: Обслуживание, Разработка.

Исходный файл: gstack-upgrade/SKILL.md

Что делает команда /gstack-upgrade?

Команда /gstack-upgrade автоматизирует процесс обновления всего инструментария gstack до самой свежей версии. Она не только загружает и устанавливает новые файлы, но и интеллектуально обрабатывает различные сценарии: от обнаружения типа установки (через Git, поставляемый напрямую) до выполнения миграций данных и конфигураций между версиями. Ключевые функции включают:

• Обнаружение обновлений: Проверяет наличие новой версии gstack.
• Интерактивное взаимодействие: При обнаружении обновления предлагает пользователю выбрать действие: обновить сейчас, включить автообновление, отложить или никогда не спрашивать.
• Автоматическое обновление: Если включено, выполняет обновление без запроса.
• Определение типа установки: Выявляет, как был установлен gstack (через Git-репозиторий глобально/локально или как "vendored" копии), и применяет соответствующий метод обновления.
• Резервное копирование и восстановление: В случае сбоя при обновлении, пытается восстановить предыдущую рабочую версию.
• Миграции версий: Запускает специфичные скрипты для миграции данных, если это необходимо при переходе между старой и новой версиями.
• Синхронизация локальных копий: Если обнаружена локальная "vendored" копия gstack, она также обновляется и синхронизируется.
• Информирование о новинках: После успешного обновления отображает краткий список изменений и новых функций из CHANGELOG.md.

Как вписывается в цикл Think→Plan→Build→Review→Test→Ship

/gstack-upgrade играет важную роль на нескольких этапах цикла разработки:

• Think (Мыслить): Хотя команда не участвует напрямую в обдумывании идей, актуальность инструментов gstack, обеспечиваемая этой командой, гарантирует, что разработчики используют самые эффективные и функциональные версии, которые могут влиять на новые идеи и подходы.
• Plan (Планировать): Обновление инструментов помогает обеспечить, что планы по разработке и развертыванию будут реализованы с использованием последних возможностей и исправлений ошибок, что может повлиять на оценку сроков и рисков.
• Build (Создавать): Обновление критически важно для этапа сборки. Новые версии gstack могут включать улучшения в процессах сборки, поддержку новых технологий или оптимизацию производительности. Поддержание актуального инструментария минимизирует проблемы совместимости и повышает стабильность сборки.
• Review (Проверять): Обновленные инструменты могут предоставлять новые возможности для анализа кода, статического анализа или других форм ревью, делая его более эффективным.
• Test (Тестировать): Использование актуальных инструментов gstack на этапе тестирования обеспечивает, что тесты выполняются в среде, свободной от известных проблем старых версий, и могут использовать новые функции для более глубокого или быстрого тестирования.
• Ship (Выпускать): Перед выпуском продукта, убедившись, что все инструменты gstack обновлены, можно быть уверенным в том, что процесс сборки и развертывания использует самые надежные и безопасные версии, уменьшая риск проблем при доставке.

По сути, /gstack-upgrade — это механизм непрерывной поддержки и улучшения инфраструктуры разработки, который обеспечивает, что на каждом шаге цикла используются оптимальные инструменты.

Типичный сценарий использования

Рассмотрим два основных сценария использования /gstack-upgrade:

Сценарий 1: Автоматическое уведомление об обновлении

Представьте, что вы активно используете gstack в повседневной работе. Когда появляется новая версия, gstack автоматически обнаруживает это. При следующем вызове любой команды gstack, вы видите приглашение:

gstack v{новая_версия} доступен (вы используете v{старая_версия}). Обновить сейчас?

Опции: ["Да, обновить сейчас", "Всегда держать меня в курсе", "Не сейчас", "Никогда не спрашивать снова"]

Если вы выберете "Да, обновить сейчас", система проведет обновление, покажет вам список изменений и продолжит выполнение исходной команды. Если вы выберете "Всегда держать меня в курсе", gstack настроит автоматические обновления на будущее. "Не сейчас" отложит напоминание, а "Никогда не спрашивать снова" отключит проверки обновлений.

Сценарий 2: Ручной запуск обновления

Допустим, вы услышали о выходе новой версии gstack с важной функцией или исправлением ошибки и хотите обновиться немедленно, или вы просто хотите убедиться, что у вас установлена последняя версия. Вы можете вручную вызвать команду:

/gstack-upgrade

Система немедленно проверит наличие обновлений. Если обновление доступно, она проведет вас через процесс, аналогичный сценарию 1 (но без запроса, если включено автообновление). Если у вас уже последняя версия, gstack сообщит вам об этом. Если у вас есть локальная "vendored" копия, которая устарела, /gstack-upgrade предложит или выполнит её синхронизацию с основной, обновленной версией.

Параметры

Текст skill для копирования (перевод на русский)

<!-- АВТОГЕНЕРИРУЕМО из SKILL.md.tmpl — не редактировать напрямую -->
<!-- Перегенерировать: bun run gen:skill-docs -->

# /gstack-upgrade

Обновите gstack до последней версии и покажите, что нового.

## Процесс встроенного обновления

Этот раздел ссылается на все преамбулы навыков, когда они обнаруживают `UPGRADE_AVAILABLE`.

### Шаг 1: Спросите пользователя (или выполните автообновление)

Сначала проверьте, включено ли автообновление:
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"

**Если `AUTO_UPGRADE=true` или `AUTO_UPGRADE=1`:** Пропустить AskUserQuestion. Зарегистрировать "Автоматическое обновление gstack v{old} → v{new}..." и перейти непосредственно к Шагу 2. Если `./setup` завершится неудачей во время автообновления, восстановить из резервной копии (каталог `.bak`) и предупредить пользователя: "Автообновление не удалось — восстановлена предыдущая версия. Запустите `/gstack-upgrade` вручную, чтобы повторить попытку."

**В противном случае**, используйте AskUserQuestion:
- Вопрос: "gstack **v{new}** доступен (вы используете v{old}). Обновить сейчас?"
- Опции: ["Да, обновить сейчас", "Всегда держать меня в курсе", "Не сейчас", "Никогда не спрашивать снова"]

**Если "Да, обновить сейчас":** Перейдите к Шагу 2.

**Если "Всегда держать меня в курсе":**
bash
~/.claude/skills/gstack/bin/gstack-config set auto_upgrade true
Сообщить пользователю: "Автообновление включено. Будущие обновления будут устанавливаться автоматически." Затем перейти к Шагу 2.

**Если "Не сейчас":** Записать состояние отложенного напоминания с нарастающей задержкой (первое отложение = 24 часа, второе = 48 часов, третье+ = 1 неделя), затем продолжить текущий навык. Больше не упоминать об обновлении.
bash
_SNOOZE_FILE=~/.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"
Примечание: `{new}` — это удаленная версия из вывода `UPGRADE_AVAILABLE` — подставьте её из результата проверки обновлений.

Сообщить пользователю продолжительность отложения: "Следующее напоминание через 24 часа" (или 48 часов, или 1 неделю, в зависимости от уровня). Подсказка: "Установите `auto_upgrade: true` в `~/.gstack/config.yaml` для автоматических обновлений."

**Если "Никогда не спрашивать снова":**
bash
~/.claude/skills/gstack/bin/gstack-config set update_check false
Сообщить пользователю: "Проверки обновлений отключены. Запустите `~/.claude/skills/gstack/bin/gstack-config set update_check true`, чтобы повторно включить."
Продолжить текущий навык.

### Шаг 2: Определите тип установки

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 "ОШИБКА: gstack не найден"
  exit 1
fi
echo "Тип установки: $INSTALL_TYPE в $INSTALL_DIR"

Тип установки и путь к каталогу, выведенные выше, будут использоваться на всех последующих шагах.

### Шаг 3: Сохраните старую версию

Используйте каталог установки из вывода Шага 2 ниже:

bash
OLD_VERSION=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown")

### Шаг 4: Обновите

Используйте тип установки и каталог, определенные на Шаге 2:

**Для Git-установок** (global-git, local-git):
bash
cd "$INSTALL_DIR"
STASH_OUTPUT=$(git stash 2>&1)
git fetch origin
git reset --hard origin/main
./setup
Если `$STASH_OUTPUT` содержит "Saved working directory", предупредите пользователя: "Примечание: локальные изменения были застэшированы. Запустите `git stash pop` в каталоге навыка, чтобы восстановить их."

**Для vendored-установок** (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"

### Шаг 4.5: Синхронизация локальной vendored-копии

Используйте каталог установки из Шага 2. Проверьте, нужна ли также локальная vendored-копия для обновления:

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
echo "LOCAL_GSTACK=$LOCAL_GSTACK"

Если `LOCAL_GSTACK` не пуст, обновите его, скопировав из только что обновленной основной установки (тот же подход, что и в README для vendored-установки):
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"
Сообщить пользователю: "Также обновлена vendored-копия в `$LOCAL_GSTACK` — зафиксируйте `.claude/skills/gstack/`, когда будете готовы."

Если `./setup` завершится неудачей, восстановить из резервной копии и предупредить пользователя:
bash
rm -rf "$LOCAL_GSTACK"
mv "$LOCAL_GSTACK.bak" "$LOCAL_GSTACK"
Сообщить пользователю: "Синхронизация не удалась — восстановлена предыдущая версия в `$LOCAL_GSTACK`. Запустите `/gstack-upgrade` вручную, чтобы повторить попытку."

### Шаг 4.75: Запустите миграции версий

После завершения `./setup` запустите все скрипты миграции для версий между старой и новой версией. Миграции обрабатывают исправления состояния, которые `./setup` в одиночку не может охватить (устаревшая конфигурация, потерянные файлы, изменения структуры каталогов).

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
    # Извлеките версию из имени файла: v0.15.2.0.sh → 0.15.2.0
    m_ver="$(basename "$migration" .sh | sed 's/^v//')"
    # Запустить, если эта версия миграции новее старой версии
    # (простое сравнение строк работает для версий с точками с одинаковым количеством сегментов)
    if [ "$OLD_VERSION" != "unknown" ] && [ "$(printf '%s\n%s' "$OLD_VERSION" "$m_ver" | sort -V | head -1)" = "$OLD_VERSION" ] && [ "$OLD_VERSION" != "$m_ver" ]; then
      echo "Запуск миграции $m_ver..."
      bash "$migration" || echo "  Предупреждение: миграция $m_ver имела ошибки (не фатальные)"
    fi
  done
fi

Миграции — это идемпотентные bash-скрипты в `gstack-upgrade/migrations/`. Каждый из них назван `v{ВЕРСИЯ}.sh` и запускается только при обновлении со старой версии. См. CONTRIBUTING.md для получения информации о том, как добавлять новые миграции.

### Шаг 5: Запишите маркер + очистите кеш

bash
mkdir -p ~/.gstack
echo "$OLD_VERSION" > ~/.gstack/just-upgraded-from
rm -f ~/.gstack/last-update-check
rm -f ~/.gstack/update-snoozed

### Шаг 6: Покажите, что нового

Прочитайте `$INSTALL_DIR/CHANGELOG.md`. Найдите все записи версий между старой и новой версией. Суммируйте их в 5-7 пунктов, сгруппированных по темам. Не перегружайте — сосредоточьтесь на изменениях, ориентированных на пользователя. Пропустите внутренние рефакторинги, если они не являются значительными.

Формат:
gstack v{new} — обновлено с v{old}!

Что нового:
- [пункт 1]
- [пункт 2]
- ...

Успешной работы!

### Шаг 7: Продолжить

После демонстрации "Что нового" продолжить выполнение навыка, который пользователь изначально вызвал. Обновление завершено — никаких дальнейших действий не требуется.

---

## Автономное использование

При вызове напрямую как `/gstack-upgrade` (не из преамбулы):

1. Принудительно выполните свежую проверку обновлений (игнорируйте кеш):
bash
~/.claude/skills/gstack/bin/gstack-update-check --force 2>/dev/null || \
.claude/skills/gstack/bin/gstack-update-check --force 2>/dev/null || true
Используйте вывод, чтобы определить, доступно ли обновление.

2. Если `UPGRADE_AVAILABLE <old> <new>`: следуйте Шагам 2-6 выше.

3. Если нет вывода (основная версия актуальна): проверьте наличие устаревшей локальной vendored-копии.

Запустите bash-блок Шага 2 выше, чтобы определить основной тип установки и каталог (`INSTALL_TYPE` и `INSTALL_DIR`). Затем запустите bash-блок обнаружения Шага 4.5 выше, чтобы проверить наличие локальной vendored-копии (`LOCAL_GSTACK`).

**Если `LOCAL_GSTACK` пуст** (нет локальной vendored-копии): сообщите пользователю "Вы уже используете последнюю версию (v{версия})."

**Если `LOCAL_GSTACK` не пуст**, сравните версии:
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"

**Если версии отличаются:** следуйте bash-блоку синхронизации Шага 4.5 выше, чтобы обновить локальную копию из основной. Сообщите пользователю: "Глобальная v{PRIMARY_VER} актуальна. Обновлена локальная vendored-копия с v{LOCAL_VER} → v{PRIMARY_VER}. Зафиксируйте `.claude/skills/gstack/`, когда будете готовы."

**Если версии совпадают:** сообщите пользователю "Вы используете последнюю версию (v{PRIMARY_VER}). Глобальная и локальная vendored-копии актуальны."