# Install pulls superpowers from git — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** `dsh/install.sh --skills` сам клонирует и обновляет superpowers из git, оставляя явные источники и офлайн-кэш рабочими.

**Architecture:** В `install.sh` появляется git-шаг: клон `$DSH_HOME/superpowers` из `$DSH_SUPERPOWERS_REPO` (по умолчанию GitHub) или `fetch --depth 1` + `reset --hard FETCH_HEAD` для существующего клона. Резолвер для `--check` отдельный и офлайновый. Тесты используют локальный `file://`-репозиторий.

**Tech Stack:** bash (`set -euo pipefail`), git CLI, Node.js ESM (node:test), OpenSpec.

**Spec:** `openspec/changes/dsh-superpowers-git/specs/dsh-install/spec.md` (дизайн — `design.md`).

## Global Constraints

- Порядок источников: `--superpowers-from` → `$DSH_SUPERPOWERS_SOURCE` → git (`$DSH_HOME/superpowers`) → legacy-кэш CC → `~/.claude/skills`.
- Явный валидный источник MUST NOT запускать git и не создавать `$DSH_HOME/superpowers`.
- Репозиторий: `$DSH_SUPERPOWERS_REPO`, default `https://github.com/obra/superpowers`; глубина 1; обновление `fetch --depth 1 origin` + `reset --hard FETCH_HEAD`.
- Фактический вывод `--skills` для git: `(source: <dir>, git <short-sha>)`.
- `--check` MUST NOT клонировать/обновлять; показывает `ok: superpowers source (<dir>, git <sha>)`.
- Неудачный первый клон MUST NOT оставлять каталог: `rm -rf $DSH_HOME/superpowers`.
- Ручная копия `$DSH_HOME/superpowers` без `.git` — `pinned`, без обновления, с `WARN`.
- Тесты не выходят в сеть: `installerEnv` задаёт недоступный `DSH_SUPERPOWERS_REPO`, git-тесты — `file://`-фикстуру.
- Маркировка: `T<n>.<k>` (ревью задачи), `C/I/M` (ревью ветки), `R-n`/`O-n` (рулинги/наблюдения).

## Review Focus

- Клон падает на середине: каталог не остаётся, следующий запуск клонирует заново.
- Офлайн при существующем клоне: `WARN`, копии из кэша, код 0 (не FAIL).
- Ручная копия без `.git`: используется, `WARN` об отсутствии обновления, копии на месте.
- Явный источник при пустом `DSH_HOME`: git не вызывается, `$DSH_HOME/superpowers` не появляется.
- `--check` на пустом HOME с недоступным репозиторием: `WARN`, код 0, клон не создан.
- Путь `$DSH_HOME` с пробелами: клон в кавычках, sha/копирование работают.

---

### Task 1: git-источник в `--skills`

**Files:**
- Modify: `dsh/install.sh` (`CLONE_HINT`, `git_superpowers_source`, `superpowers_source`, `install_skills`, `usage`)
- Modify: `dsh/tests/install.test.mjs`

**Interfaces:**
- Produces:
  - `git_superpowers_source() -> rc 0` и stdout `<skills-dir>\tgit:<sha>`; `rc 1` без источника (печатает `WARN`/`FAIL` причину);
  - `superpowers_source()` — прежний контракт `<dir>\t<explicit|pinned|legacy|git:<sha>>`;
  - `install_skills` печатает `copied N superpowers skills into <dest> (source: <dir>, git <sha>)` для git и `(source: <dir>)` иначе.
- Consumes: `normalize_superpowers_dir`, `$DSH_HOME`, `$DSH_SUPERPOWERS_REPO`.

- [ ] **Step 1: Тестовый хелпер и падающие тесты**

В `dsh/tests/install.test.mjs` импортировать `mkdirSync` из `node:fs`, `git` из `./helpers.mjs`, `pathToFileURL` из `node:url`; добавить:

```js
function makeSuperpowersRepo(home, name = 'superpowers-src') {
  const repo = join(home, name)
  mkdirSync(repo, { recursive: true })
  git(repo, ['init', '-b', 'main'])
  git(repo, ['config', 'user.email', 'test@example.invalid'])
  git(repo, ['config', 'user.name', 'Test'])
  makeSuperpowers(repo)
  git(repo, ['add', '.'])
  git(repo, ['commit', '-m', 'init'])
  return repo
}
```

`installerEnv` дополнительно: `delete env.DSH_SUPERPOWERS_REPO` и
`env.DSH_SUPERPOWERS_REPO = join(home, 'no-superpowers-repo')` (недоступный путь — сеть в тестах не нужна). Git-тесты переопределяют его через `file://`-URL.

Тесты:

```js
test('--skills clones the git source on first run', ...)
// home; repo = makeSuperpowersRepo(home); env repo = pathToFileURL(repo).href;
// run --skills; status 0; <dshHome>/superpowers/.git существует;
// stdout /copied 2 superpowers skills/ и new RegExp(`git ${git(repo,['rev-parse','--short','HEAD'])}`);
// skills/using-superpowers на месте

test('--skills updates an existing clone to the new commit', ...)
// после первого прогона: write(join(repo,'skills','new-skill','SKILL.md'), ...);
// git add/commit; повторить --skills; status 0;
// <dshHome>/skills/new-skill/SKILL.md существует; stdout содержит новый short-sha

test('an offline update keeps the cached clone', ...)
// после клона: env repo = join(home,'gone'); run --skills; status 0;
// stdout/stderr /WARN: cannot update superpowers/; /copied 2 superpowers skills/

test('a failed first clone leaves no checkout', ...)
// пустой home (repo недоступен); run --skills; status 1;
// <dshHome>/superpowers НЕ существует; FAIL упоминает no-superpowers-repo и --superpowers-from

test('an explicit source never touches git', ...)
// --skills --superpowers-from <fixture>; status 0; <dshHome>/superpowers НЕ существует

test('a manual non-git checkout is used but not updated', ...)
// write <dshHome>/superpowers/skills/using-superpowers/SKILL.md; repo недоступен;
// run --skills; status 0; stderr /not a git checkout/; /copied 1 superpowers skills/
```

- [ ] **Step 2: Прогнать, увидеть падение**

Run: `node --test dsh/tests/install.test.mjs`
Expected: новые тесты падают (нет клона/обновления/сообщений).

- [ ] **Step 3: Реализовать в `dsh/install.sh`**

- `SUPERPOWERS_REPO="${DSH_SUPERPOWERS_REPO:-https://github.com/obra/superpowers}"` рядом с `CLONE_HINT`; `CLONE_HINT` переписать на `git clone --depth 1 "$SUPERPOWERS_REPO" "$DSH_HOME/superpowers"`.
- `git_superpowers_source` по описанию из Interfaces: git-клон → fetch+reset → `normalize_superpowers_dir`; на неудачном клоне `rm -rf "$DSH_HOME/superpowers"` и `return 1`; на неудачном fetch — `WARN` и работа из кэша.
- `superpowers_source`: после явных источников вызвать `git_superpowers_source`; её успех вернуть как есть, `rc 1` — продолжить на legacy-кэш и `~/.claude/skills`.
- `install_skills`: разобрать kind `git:<sha>` → в итоговой строке `(source: $source, git $sha)`; `FAIL`-сообщение — репозиторий и `--superpowers-from` вместо ручного клона.
- `usage`: пункт 3 — git-клон `$SUPERPOWERS_REPO` → `$DSH_HOME/superpowers`, обновляется при каждом `--skills`.

- [ ] **Step 4: Прогнать тесты**

Run: `node --test dsh/tests/install.test.mjs`
Expected: PASS всех тестов файла.

- [ ] **Step 5: Commit**

```bash
git add dsh/install.sh dsh/tests/install.test.mjs
git commit -m "feat(dsh): install pulls superpowers from git (#67)"
```

---

### Task 2: офлайновый `--check` с git-версией

**Files:**
- Modify: `dsh/install.sh` (`static_superpowers_source`, блок `check`)
- Modify: `dsh/tests/install.test.mjs`

**Interfaces:**
- Produces: `static_superpowers_source()` — тот же формат, но без сети: явные источники → существующий git-клон (`git:<sha>`) → ручная копия (`pinned`) → legacy; `--check` печатает `ok: superpowers source (<dir>, git <sha>)`, `WARN` для `pinned`/legacy/отсутствия, `FAIL` для невалидного явного.

- [ ] **Step 1: Падающие тесты**

```js
test('--check reports the git sha and does not clone', ...)
// сначала --skills с file://-репозиторием (клон создан);
// затем env repo = недоступный путь; run --check;
// stdout /ok: superpowers source \(.*superpowers\/skills, git [0-9a-f]+\)/; status 0

test('--check never clones on an empty HOME', ...)
// empty home, repo недоступен; run --check; status 0;
// <dshHome>/superpowers НЕ существует; stderr /WARN: no superpowers source/

test('--check warns about a manual non-git checkout', ...)
// write <dshHome>/superpowers/skills/using-superpowers/SKILL.md;
// run --check; stdout/stderr /not a git checkout/
```

Существующий тест `--check reports the pinned source` заменить этим кейсом (ручная копия больше не `ok`), сценарий спеки #49 обновлён в change.

- [ ] **Step 2: Прогнать, увидеть падение**

Run: `node --test dsh/tests/install.test.mjs`
Expected: FAIL на новых и переименованном тестах.

- [ ] **Step 3: Реализовать**

- Вынести `static_superpowers_source` (без вызова git-команд, меняющих состояние; `rev-parse --short HEAD` — чтение).
- `check()` переключить с `superpowers_source` на `static_superpowers_source`; разобрать kind: `git:<sha>` → `ok: superpowers source ($src, git $sha)`, `pinned` → `WARN: ... is not a git checkout; --skills will not update it`, `legacy` → `WARN`, нет — `WARN` с `$SUPERPOWERS_REPO` и `--superpowers-from`.
- `--check` не должен создавать `$DSH_HOME/superpowers` и не вызывать `git clone`/`fetch`.

- [ ] **Step 4: Прогнать тесты**

Run: `bash dsh/tests/run.sh`
Expected: PASS всего набора.

- [ ] **Step 5: Commit**

```bash
git add dsh/install.sh dsh/tests/install.test.mjs
git commit -m "feat(dsh): offline --check reports the git source (#67)"
```

---

### Task 3: документация, приёмка, PR

**Files:**
- Modify: `dsh/README.md` (Quick start, Known limits, config)
- Modify: `dsh/PORT.md` (§5 install, §7 risks, §8 phases)
- Modify: `openspec/changes/dsh-superpowers-git/design.md` (раздел приёмки)

- [ ] **Step 1: README/PORT**

Quick start: убрать ручной `git clone`, оставить `bash dsh/install.sh --global --skills --roles`; описать `DSH_SUPERPOWERS_REPO`, офлайн-кэш и `--superpowers-from`. Known limits: свежий апстрим тянется при каждом `--skills`; ручная копия без `.git` не обновляется. PORT §5: git-источник и sha; §7: сеть в установке и откат на `--superpowers-from`; §8: #67.

- [ ] **Step 2: Полный прогон и приёмка**

```bash
bash dsh/tests/run.sh
bash tests/run.sh
openspec validate dsh-superpowers-git --strict
```

Живой прогон на машине владельца (после merge): `bash dsh/install.sh --skills`
→ клон GitHub, `--check` → `git <sha>`, повторный `--skills` → обновление.
В design.md записать `### Приёмка: прогон <дата>` с результатами.

- [ ] **Step 3: Commit, push, PR**

```bash
git add -A
git commit -m "docs(dsh): git source для superpowers (#67)"
git push -u origin feat/67-dsh-superpowers-git
tea pulls create --head feat/67-dsh-superpowers-git --base main \
  --title "DSH: install сам тянет свежий superpowers с git (#67)" \
  --description-file <подготовленный файл>
```

- [ ] **Step 4: Ревью ветки и итог**

Свежий ревьюер (`deepseek-v4-pro`) по `review-package`; Critical/Important → один fix pass по TDD; Minor → ledger и PR; итоговая таблица маркеров.

## Acceptance

- Спека `dsh-install` (delta) покрыта тестами: клон, обновление, офлайн-кэш, неудачный клон, явный источник без сети, ручная копия, `--check` без сети и с sha.
- `bash dsh/tests/run.sh`, `bash tests/run.sh`, `openspec validate --strict` — зелёные.
- Тесты не обращаются к GitHub: единственный источник — `file://`-фикстура или недоступный путь.
- После merge: `--skills` на машине владельца тянет GitHub и убирает `WARN: legacy superpowers source`.