Files
repoctl/docs/repoctl.md
T
Alexander Baranov 4fbe56d81f docs: add human-facing repoctl guide in Russian, route it via KDB
docs/repoctl.md walks a human through what repoctl is, the install-once
/ invoke-from-other-repositories model (folding in the framing already
present on the sibling codex/repoctl-l1 branch's docs/repoctl.md), each
command with real sample output, the exit-code table, and troubleshooting.
docs/specification.md stays the normative machine reference.

kdb/kdb.yaml routes the new document into the tooling-implementation
topic; README.md links it and documents running tests-universal.
2026-08-24 15:42:48 +03:00

148 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 add-root --path C:/Users/example/Git
repoctl describe --repo some-repo-name
```
Порядок разрешения имени репозитория: явный `--root` → переменная окружения `REPOCTL_ROOTS` → сохранённый `config 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` также повторно проверяет, что ни один из планируемых файлов не появился с момента построения плана — иначе откажется перезаписывать существующее.
### `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 независимо от кодовой страницы консоли.