Files
repoctl/docs/repoctl.md
T
Alexander BaranovandClaude Opus 5 5b9c97fdcd fix(init): stop the entry point from disabling the command it reaches
A field report from bootstrapping Services/Vault: ~20 CLI calls produced
three productive writes, and four of those calls were deliberate failures
sent only to discover a vocabulary.

The worst of it was self-inflicted and new. `repoctl skills install` is the
documented way to make the bootstrap skill reachable, and it writes the
three skill files -- which `init` then reported as INIT_PATH_COLLISION and
redirected to `adopt`. Every skill-driven bootstrap of an empty repository
was pushed onto the adoption path. The collision check exists to protect
content the tool did not author, and identical bytes are nothing to
protect: a path already holding exactly what the plan would write is no
longer a collision, at plan time or at write time, while a file whose
content differs still is. `init` reports only the files it actually wrote.

`--lifecycle` advertised no choices, so its vocabulary was reachable only
by sending a wrong value and reading the refusal; it now carries `choices`
like `--type` does.

`--answers-template` prints a commented answers file naming every key, its
allowed values and its default. The answers keys are not the flag names
(`--type` sets `repositoryType`) and nothing printed the mapping. It lists
`summary` and `namespace` too, which are cheap to answer once and otherwise
survive as generated placeholders in the contract.

`--repo .` proposed the name `adopted-repository`: `Path(".").name` is the
empty string, so the ordinary way to name the current repository fell
through to the generic fallback. Resolve before deriving.

Both skills gained what the report had to discover by hand: that `--plan`
already unwraps a saved result envelope, and that sibling repositories are
where a naming convention comes from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-26 14:56:49 +03:00

198 lines
19 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 --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`.
### `skills` — поставить агентские скиллы туда, где агент их ищет
```bash
repoctl skills install --repo . # в этот репозиторий, .claude/skills/
repoctl skills install --global # в ~/.claude/skills/, для всех репозиториев
repoctl skills status --repo . # что установлено и не разошлось ли
```
Ставит `repository-adoption`, `repository-bootstrap` и `repo-handoff`. Это точка входа: до появления команды скиллы записывал только `init`, то есть они попадали исключительно в **новые** репозитории, а для приёма существующего нужен был скилл, который туда нечем было положить.
Область обязательно указывается явно — `--repo` или `--global`: локальная установка едет вместе с репозиторием и достаётся тому, кто его склонирует, глобальная следует за оператором в том числе в ещё не принятые репозитории. Угадывать между ними команда не будет (`SKILLS_SCOPE_MISSING`).
Повторный запуск идемпотентен. Скилл, содержимое которого отличается от поставляемого этой версией, **не перезаписывается**: команда сообщает `SKILLS_MODIFIED` и завершается кодом `1`, заменить его можно явным `--force`. Различить «оператор поправил файл» и «repoctl ушёл вперёд» нельзя, поэтому оба случая требуют подтверждения. Проверка проходит по всем скиллам до первой записи, так что отказ не оставляет каталог наполовину обновлённым.
В отличие от `init` и `adopt`, здесь нет плана и подтверждения по хэшу: эта дисциплина защищает содержимое репозитория, а команда пишет только файлы, принадлежащие инструменту, в фиксированный подкаталог.
### `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`).
Репозиторием считается корень git-репозитория. Контракт, лежащий внутри рабочего дерева другого репозитория — fixture, example, vendored copy — это его содержимое, а не равноправный сосед: такой путь в каталог не попадает и сообщается как `CATALOG_NESTED_CONTRACT_SKIPPED` (severity `info`).
### `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
# Шаг 0: получить шаблон ответов — он называет все ключи и их допустимые значения
repoctl init --answers-template > answers.yaml
# Шаг 1: построить план (ничего не пишет на диск)
repoctl init --repo ../new-repo --answers answers.yaml --output json > plan.json
```
Ключи файла ответов — не имена флагов (`--type` задаёт `repositoryType`), поэтому шаблон и существует. `summary` и `namespace` стоит заполнить сразу: они дёшевы, а иначе навсегда остаются заглушками в контракте.
Файлы скиллов, оставленные `repoctl skills install`, коллизией **не** считаются: путь, уже содержащий ровно то, что план собирался записать, — не конфликт. Файл с другим содержимым конфликтом остаётся.
Ответы проверяются до сборки плана, чтобы `init` не мог создать репозиторий, который не проходит собственный `validate`:
| Код | Когда |
|---|---|
| `INIT_ANSWERS_INCOMPLETE` | нет `--name` или `--type` |
| `INIT_NAME_INVALID` | имя не подходит под `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`; в сообщении есть готовая замена (`Services/Mail` → `services-mail`) |
| `INIT_TYPE_UNKNOWN`, `INIT_LIFECYCLE_UNKNOWN`, `INIT_ACCESS_UNKNOWN` | значение вне enum схемы |
| `INIT_OWNER_UNKNOWN` | владелец не подтверждён — та же граница, что у `adopt` |
| `INIT_PATH_COLLISION` | каталог уже содержит один из создаваемых путей; для существующего репозитория нужен `adopt`, а не `init` |
В ответе — полный список файлов, которые будут созданы (`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 --owner infra --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
```
`plan` требует подтверждённого владельца — `--owner` (можно повторять) либо `owners:` в `--answers`; без него он отказывается строиться, а не выпускает контракт с пустым `owners`. Имя репозитория берётся из URL remote (последние два сегмента: `.../OpTools/LXD.git` → `optools-lxd`), либо задаётся `name:` в файле ответов.
`plan` также отказывается строиться, пока `assess` оставил находку severity `error` — например, файл с живым credential в git. Принять такую находку осознанно можно в файле ответов; `reason` обязателен, а сам acknowledgement входит в `planHash`:
```yaml
owners: [infrastructure]
acknowledgedFindings:
- code: ADOPT_SECRET_CONTENT_VERIFIED
path: airflow/.env
reason: rotation scheduled, tracked separately
```
По умолчанию используется стратегия `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` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново. `INIT_PATH_COLLISION` на этапе плана означает, что каталог уже является репозиторием: используйте `adopt`.
- **`INIT_PATH_OUTSIDE_REPOSITORY`** — путь в файле плана ведёт наружу репозитория. План — обычный файл; если он был отредактирован вручную или перенесён между машинами, постройте его заново вместо правки.
- **Windows: кириллица или спецсимволы искажены в выводе** — используйте актуальную версию `repoctl`; вывод принудительно кодируется в UTF-8 независимо от кодовой страницы консоли.