apply_plan/apply_bootstrap_plan required the raw plan object, but the natural capture workflow (repoctl ... --output json > plan.json) saves the full result envelope, so following the documented workflow verbatim failed the hash check. repoctl now unwraps a stored envelope's `data` automatically (an idea worth keeping from codex/repoctl-l1's cli.py, which had the same fallback). Found while walking docs/repoctl.md's adopt and cross-repo examples live end to end: two more invocation bugs in the doc itself (`config add-root` takes a positional path, not `--path`; `--output` must follow `config` itself, not the add-root/remove-root subaction) -- fixed and clarified in place.
150 lines
12 KiB
Markdown
150 lines
12 KiB
Markdown
---
|
||
documentId: repoctl-human-guide
|
||
documentVersion: 0.1.0
|
||
schemaApiVersion: stewardship.corsus.ru/v1alpha1
|
||
status: draft
|
||
normative: false
|
||
language: ru
|
||
companionDocument: docs/specification.md
|
||
---
|
||
|
||
# repoctl: руководство для человека
|
||
|
||
Этот документ объясняет `repoctl` — CLI Repository Stewardship — так, как его видит человек: зачем он нужен, как установить и вызвать его на конкретном репозитории, что означает каждая команда и как читать её вывод. Нормативные определения полей и правил остаются в [specification.md](specification.md); здесь — практика.
|
||
|
||
## Зачем нужен `repoctl`
|
||
|
||
`repoctl` не заменяет Git, LXD, Docker, Terraform или ваши domain-инструменты. Его задача — единообразно ответить на четыре вопроса про любой репозиторий, оформленный по стандарту Repository Stewardship:
|
||
|
||
1. что это за репозиторий и кто его владелец (`ops/contract.yaml`);
|
||
2. какие знания нужны для конкретной задачи, а не вся документация целиком (`kdb/kdb.yaml` + `context`);
|
||
3. корректно ли он оформлен (`validate`);
|
||
4. как безопасно создать новый репозиторий по стандарту или подключить существующий (`init`, `adopt`) — только после явного просмотра плана и подтверждения его хэша.
|
||
|
||
По умолчанию все команды **read-only**. Запись происходит только в `init --apply` и `adopt --mode apply`, и только после того, как вы одобрили ранее построенный план по его SHA-256.
|
||
|
||
## Модель установки: один инструмент — много репозиториев
|
||
|
||
`repoctl` устанавливается один раз из репозитория `.repoctl` (этот репозиторий), а затем вызывается **из любого другого репозитория**, который вы хотите проверить, описать или подключить к стандарту. Сам `.repoctl` не обязан быть тем репозиторием, над которым вы сейчас работаете:
|
||
|
||
```bash
|
||
# Один раз: установить repoctl из этого репозитория
|
||
cd path/to/.repoctl
|
||
uv tool install --editable .
|
||
|
||
# Дальше: вызывать его из любого управляемого репозитория
|
||
cd path/to/any-other-repo
|
||
repoctl validate --repo .
|
||
```
|
||
|
||
Пока `repoctl` не установлен как инструмент, из исходников этого репозитория он запускается через `uv run repoctl ...` (см. README.md). Если репозиториев несколько и они лежат в общем каталоге, добавьте этот каталог как root один раз:
|
||
|
||
```bash
|
||
repoctl config --output json add-root C:/Users/example/Git
|
||
repoctl describe --repo some-repo-name --output json
|
||
```
|
||
|
||
Порядок разрешения имени репозитория: явный `--root` → переменная окружения `REPOCTL_ROOTS` → сохранённый `config add-root` → текущий репозиторий (если команда запущена изнутри него).
|
||
|
||
`--output` — параметр конкретной подкоманды, а не общий флаг: он идёт **после** имени команды (`repoctl validate --output json ...`), а для `config` — сразу после `config`, перед `show`/`add-root`/`remove-root` (`repoctl config --output json add-root ...`).
|
||
|
||
## Команды по порядку знакомства
|
||
|
||
### `validate` — всё ли корректно
|
||
|
||
```bash
|
||
repoctl validate --repo . --output json
|
||
```
|
||
|
||
Проверяет `ops/contract.yaml` и `kdb/kdb.yaml`: envelope, ID, типы, безопасность путей, ссылки между темами и документами, secret-shaped поля, отсутствие shell-строк в operations. Ничего не пишет. На чистом репозитории:
|
||
|
||
```json
|
||
{
|
||
"schema": "stewardship/repoctl-result@0.1",
|
||
"command": "validate",
|
||
"outcome": "success",
|
||
"data": { "repository": "...", "valid": true },
|
||
"findings": []
|
||
}
|
||
```
|
||
|
||
При ошибке `outcome` становится `"failure"`, `findings` заполняется, а процесс завершается кодом `1`.
|
||
|
||
### `discover` — что есть в каталоге репозиториев
|
||
|
||
```bash
|
||
repoctl discover --root C:/Users/example/Git --output json
|
||
```
|
||
|
||
Обходит указанный каталог, находит все `ops/contract.yaml`, строит `CatalogIndex` — детерминированно отсортированный список репозиториев с их типом, lifecycle и hash контракта. Не следует по symlink, пропускает `.git`, `.venv`, `node_modules` и подобные. Дублирующиеся имена репозиториев — ошибка (`CATALOG_REPOSITORY_DUPLICATE`).
|
||
|
||
### `describe` — паспорт одного репозитория
|
||
|
||
```bash
|
||
repoctl describe --repo some-repo-name --output json
|
||
```
|
||
|
||
Возвращает нормализованный `RepositoryContract` — только контракт, без загрузки KDB. Полезно, чтобы быстро узнать тип, владельца и content roots репозитория, не читая ничего лишнего.
|
||
|
||
### `context` — только нужные знания под задачу
|
||
|
||
Главная команда для агента. Вместо чтения всей документации репозитория:
|
||
|
||
```bash
|
||
repoctl context --repo . --intent domain.action --output json
|
||
```
|
||
|
||
Возвращает `ContextBundle`: подходящие темы (`topics`) по точному совпадению `intent`, связанные операции, content roots и — если передан `--materialize` — сами тексты нужных разделов, без остального репозитория. `--budget-bytes N` ограничивает объём материализованного текста; при превышении бюджета контент обрезается и в `warnings` появляется `CONTEXT_BUDGET_TRUNCATED`. Флаг `--strict` превращает такую усечённость (или устаревший/отсутствующий документ) в код возврата `4`, а не в тихое предупреждение — используйте его, когда неполный контекст недопустим для задачи.
|
||
|
||
### `init` — создать новый репозиторий по стандарту
|
||
|
||
Двухшаговый процесс: сначала план, затем — только после ревью — применение.
|
||
|
||
```bash
|
||
# Шаг 1: построить план (ничего не пишет на диск)
|
||
repoctl init --repo ../new-repo --name new-repo --type project --owner team-name --output json > plan.json
|
||
```
|
||
|
||
В ответе — полный список файлов, которые будут созданы (`ops/contract.yaml`, `kdb/kdb.yaml`, `AGENTS.md`, `CLAUDE.md`, `.claude/skills/*`, и т.д.) и `planHash`. Прочитайте план, убедитесь, что он ожидаем.
|
||
|
||
```bash
|
||
# Шаг 2: применить план, явно подтвердив его хэш
|
||
repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256:<planHash-из-плана> --output json
|
||
```
|
||
|
||
`--approve` должен побайтово совпасть с `planHash` — иначе команда завершится кодом `5` (approval required/denied) и ничего не запишет. `init` также повторно проверяет, что ни один из планируемых файлов не появился с момента построения плана — иначе откажется перезаписывать существующее. `--plan` принимает как файл, сохранённый напрямую из `--output json > plan.json` (полный envelope с `data`), так и голый объект плана — `repoctl` сам распознаёт и разворачивает envelope.
|
||
|
||
### `adopt` — подключить существующий репозиторий
|
||
|
||
Четыре режима, соответствующие фазам runbook (см. [adoption-runbook.md](adoption-runbook.md)):
|
||
|
||
```bash
|
||
repoctl adopt --repo ../legacy-repo --mode assess --output json # инвентаризация, ничего не пишет
|
||
repoctl adopt --repo ../legacy-repo --mode plan --output json # предлагаемый diff + planHash, ничего не пишет
|
||
repoctl adopt --repo ../legacy-repo --mode apply --plan plan.json --approve sha256:<planHash> --output json
|
||
repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт о совместимости после apply
|
||
```
|
||
|
||
По умолчанию используется стратегия `overlay`: existing domain-native layout (например, `profiles-source/`, существующий `kdb.yaml` в корне) не перемещается и не переписывается — поверх него добавляется только недостающая метадата Stewardship. Если в репозитории уже занят путь `kdb/kdb.yaml`, `adopt` предложит `ops/knowledge.yaml` вместо конфликта. `apply` никогда не делает `git commit`, `push` или `clone`.
|
||
|
||
## Коды возврата
|
||
|
||
| Код | Значение |
|
||
|---|---|
|
||
| `0` | успех, ошибок нет |
|
||
| `1` | ошибка валидации или операции |
|
||
| `2` | некорректный вызов CLI или входные данные |
|
||
| `3` | репозиторий или ресурс не найден |
|
||
| `4` | неполный/устаревший context при `--strict` |
|
||
| `5` | approval не совпал или отсутствует (`init`/`adopt --mode apply`) |
|
||
|
||
Машинный вывод (`--output json` или `--output yaml`) всегда идёт в stdout как единый envelope `stewardship/repoctl-result@0.1` (`schema`, `command`, `outcome`, `data`, `findings`). Диагностика и предупреждения человеку — в stderr, вне зависимости от `--output`.
|
||
|
||
## Устранение неполадок
|
||
|
||
- **`ERROR: No .git ancestor found`** — команда запущена вне git-репозитория и `--repo` не указан явно; передайте `--repo <путь>` или запустите `git init` в целевом каталоге.
|
||
- **`APPROVAL_FAILED` при `init --apply`/`adopt --mode apply`** — переданный `--approve` не совпадает с `planHash` в файле плана; пересчитайте план заново (сравнение файла плана и `planHash` в нём — самопроверка от случайной правки плана вручную).
|
||
- **`ADOPT_BASELINE_CHANGED`** — репозиторий изменился между `--mode plan` и `--mode apply` (кто-то создал файл из плана вручную); постройте план заново.
|
||
- **`ADOPT_PATH_COLLISION` / `init` отказывается писать** — план целится в уже существующий файл; `repoctl` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново.
|
||
- **Windows: кириллица или спецсимволы искажены в выводе** — используйте актуальную версию `repoctl`; вывод принудительно кодируется в UTF-8 независимо от кодовой страницы консоли.
|