125 lines
9.8 KiB
Markdown
125 lines
9.8 KiB
Markdown
# 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.md` OpenSpec не заполняется** (как в прошлых 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` обновляет.
|
||
|
||
### Приёмка: прогон 24.10.2026
|
||
|
||
- `openspec validate dsh-superpowers-git --strict` — change валиден.
|
||
- `bash dsh/tests/run.sh` — 71/71 pass; `bash tests/run.sh` — см. PR.
|
||
- Живой клон GitHub в temp HOME без `~/.claude`: `--skills` → 15
|
||
superpowers-скиллов, `source: .../.dsh/superpowers/skills, git 2ce8aa1`;
|
||
повторный `--skills` → обновление того же клона, снова `git 2ce8aa1`;
|
||
`--check` → `ok: superpowers source (.../.dsh/superpowers/skills, git 2ce8aa1)`.
|
||
- Тесты сети не касаются: `installerEnv` подставляет недоступный
|
||
`DSH_SUPERPOWERS_REPO`, git-кейсы — локальный `file://`-репозиторий; мутацией
|
||
проверено, что `--check never clones on an empty HOME` падает, если вернуть
|
||
`--check` на сетевой резолвер.
|