8.8 KiB
Design: install тянет superpowers с git
Issue: #67. Спека: openspec/changes/dsh-superpowers-git/specs/dsh-install/spec.md.
Контекст: #49 (dsh-install-source) — источник был явным, сеть в установке
запрещена; это решение пересматривается по команде владельца 24.10.2026.
1. Что меняется в контракте #49
| #49 | #67 | |
|---|---|---|
| Источник по умолчанию | ручной клон/флаг | git: клон в $DSH_HOME/superpowers |
| Обновление | нет | fetch --depth 1 + reset --hard FETCH_HEAD при каждом --skills |
| Сеть в установке | запрещена | разрешена только для git-источника |
| Явный источник | главнее | главнее, сеть не трогает |
--check |
офлайн | офлайн + git sha |
| Офлайн-машина | явный источник | кэш клона (WARN) → legacy (WARN) → FAIL |
2. Решения
D-7 (решение владельца). Git — источник по умолчанию
--skills без флага/переменной клонирует репозиторий и обновляет его при
следующих запусках. Обоснование владельца: ручной клон не обновляется и
оставляет WARN: legacy superpowers source навсегда. Цена: установка требует
сеть (кроме явного источника и кэша), а свежий апстрим может принести
несовместимость — она лечится --superpowers-from на любой коммит.
D-8. Явный источник полностью отключает сеть
--superpowers-from и $DSH_SUPERPOWERS_SOURCE проверяются первыми и, если
валидны, git не вызывается вообще. Это и офлайн-путь, и отладка, и пиннинг на
конкретную версию. Цена: две ветки кода, покрыты тестами, включая «явный
источник не создаёт $DSH_HOME/superpowers».
D-9. Офлайн не ломает установку, если есть чем ставить
Порядок при недоступном git: существующий клон (в т.ч. с неудачным fetch) →
legacy-кэш CC → ~/.claude/skills → FAIL. Первые два шага печатают WARN с
причиной (репозиторий), чтобы деградация была видна, но машина без сети
продолжала работать. Цена: опечатка в DSH_SUPERPOWERS_REPO может привести к
legacy-источнику — сообщение называет репозиторий и путь кэша.
D-10. Ручная копия без .git — пиннинг, а не ошибка
Если $DSH_HOME/superpowers существует, валиден, но не является git-клоном,
он используется как есть с WARN, что обновляться не будет. Это совместимость
с #49: у кого уже лежит ручная копия, после обновления обвязки установка не
падает. Цена: такой каталог стареет молча — предупреждение на каждом --skills.
D-11. --check остаётся офлайновым
--check — диагностика; клонировать или обновлять из него нельзя (в #42 уже
принято: --check не должен иметь побочных эффектов). Он показывает
ok: superpowers source (<path>, git <sha>) для клона, WARN для ручной копии
и для legacy, и подсказку про --skills/DSH_SUPERPOWERS_REPO, когда клона нет.
Цена: --check не скажет, доступен ли репозиторий; это выясняется при установке.
D-12. Тесты идут через локальный file://-репозиторий
DSH_SUPERPOWERS_REPO — не только фича для зеркал, но и тестовый шов: набор не
ходит в GitHub. Тестовый хелпер создаёт git-репозиторий с skills/*/SKILL.md,
запускает --skills с DSH_SUPERPOWERS_REPO=file://<путь>, затем добавляет
коммит и проверяет обновление копий. Офлайн-кейс — репозиторий, которого нет.
3. Решения, принятые без обсуждения
- 2026-10-24.
--depth 1иreset --hard FETCH_HEAD, без тегов и подписей. «Свежая версия» = последний коммит default-ветки; глубина 1 экономит сеть,reset --hardгарантирует чистое управляемое дерево. Цена: локальные правки в~/.dsh/superpowersтеряются, подлинность апстрима не проверяется (TLS и доверие к GitHub); откат —--superpowers-fromна известный коммит. - 2026-10-24. Неудачный первый клон удаляет каталог.
rm -rf $DSH_HOME/superpowersпосле неудачи, чтобы следующий запуск снова клонировал, а не принимал половину за кэш. Цена: если пользователь положил туда что-то своё и не было.git— этот путь не трогается (D-10), удаление только для созданного нами каталога в текущем запуске. - 2026-10-24. Отдельного флага
--offlineнет. Офлайн покрыт существующим клоном (D-9) и явным источником (D-8). Цена: нет способа гарантированно запретить сеть, кроме явного источника; для установки это приемлемо. - 2026-10-24.
DSH_SUPERPOWERS_REPOвиден и в--check. ВWARN/FAILпечатается фактический репозиторий, чтобы зеркало и опечатка различались. Цена: строка вывода зависит от env — приемлемо. - 2026-10-24.
tasks.mdOpenSpec не заполняется (как в прошлых change): задачи в плане superpowers.
4. Риски
- Свежий апстрим ломает установку.
--skillsтянет последний коммит; если superpowers переименуетskills/using-superpowers,FAILскажет, что искать. Обход —--superpowers-fromс проверенной копией; sha в выводе помогает зафиксировать версию. - Сеть в установке. Машины без доступа к GitHub должны использовать
DSH_SUPERPOWERS_REPO(зеркало) или--superpowers-from; ошибка клона называет репозиторий и оба пути. - Тесты и сеть. Любой тест, забывший выставить
DSH_SUPERPOWERS_REPO, уйдёт в GitHub. ПоэтомуinstallerEnvв тестах задаёт недоступный repo по умолчанию, а тесты git-источника —file://-фикстуру; проверяется, что--checkне создаёт клон. - Офлайн-деградация незаметна. WARN есть на каждом шаге деградации;
--checkпоказывает, какой источник будет использован при следующем--skills. - Совместимость с #49. Ручная копия без
.gitи legacy-кэш остаются рабочими; тесты #49 переиспользуются, меняются только ожидания сообщений.
5. Приёмка
openspec validate dsh-superpowers-git --strict— change валиден.bash dsh/tests/run.sh— зелёный, включая клон/обновление/офлайн/--check.bash tests/run.sh— регрессий в CC-контуре нет.- Живой прогон на машине владельца:
--skillsклонирует GitHub-репозиторий,--checkпоказываетgit <sha>, повторный--skillsобновляет.