Files
repoctl/docs/repoctl.md
T
Alexander BaranovandClaude Opus 5 c21ffceef3 fix(discover): a contract inside another repository is not a repository
`tests/fixtures/positive/` holds four valid contracts. Running `discover`
over the machine's Git directory returned six repositories: two real ones
and those four, with nothing in the output to tell them apart. Any
catalog-wide question -- which repositories lack an owner, which are
behind the template version -- was answered over a set that included this
project's own test material.

A repository is the root of a git repository. A directory holding
ops/contract.yaml somewhere inside another repository's working tree is
that repository's content: a fixture, an example, a vendored copy. Skip
it, and say so with CATALOG_NESTED_CONTRACT_SKIPPED rather than silently,
so a genuinely misplaced contract is still visible.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 18:17:11 +03:00

15 KiB
Raw Blame History

documentId, documentVersion, schemaApiVersion, status, normative, language, companionDocument
documentId documentVersion schemaApiVersion status normative language companionDocument
repoctl-human-guide 0.1.0 stewardship.corsus.ru/v1alpha1 draft false ru docs/specification.md

repoctl: руководство для человека

Этот документ объясняет repoctl — CLI Repository Stewardship — так, как его видит человек: зачем он нужен, как установить и вызвать его на конкретном репозитории, что означает каждая команда и как читать её вывод. Нормативные определения полей и правил остаются в 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 не обязан быть тем репозиторием, над которым вы сейчас работаете:

# Один раз: установить 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 один раз:

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 — всё ли корректно

repoctl validate --repo . --output json

Проверяет ops/contract.yaml и kdb/kdb.yaml: envelope, ID, типы, безопасность путей, ссылки между темами и документами, secret-shaped поля, отсутствие shell-строк в operations. Ничего не пишет. На чистом репозитории:

{
  "schema": "stewardship/repoctl-result@0.1",
  "command": "validate",
  "outcome": "success",
  "data": { "repository": "...", "valid": true },
  "findings": []
}

При ошибке outcome становится "failure", findings заполняется, а процесс завершается кодом 1.

discover — что есть в каталоге репозиториев

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 — паспорт одного репозитория

repoctl describe --repo some-repo-name --output json

Возвращает нормализованный RepositoryContract — только контракт, без загрузки KDB. Полезно, чтобы быстро узнать тип, владельца и content roots репозитория, не читая ничего лишнего.

context — только нужные знания под задачу

Главная команда для агента. Вместо чтения всей документации репозитория:

repoctl context --repo . --intent domain.action --output json

Возвращает ContextBundle: подходящие темы (topics) по точному совпадению intent, связанные операции, content roots и — если передан --materialize — сами тексты нужных разделов, без остального репозитория. --budget-bytes N ограничивает объём материализованного текста; при превышении бюджета контент обрезается и в warnings появляется CONTEXT_BUDGET_TRUNCATED. Флаг --strict превращает такую усечённость (или устаревший/отсутствующий документ) в код возврата 4, а не в тихое предупреждение — используйте его, когда неполный контекст недопустим для задачи.

init — создать новый репозиторий по стандарту

Двухшаговый процесс: сначала план, затем — только после ревью — применение.

# Шаг 1: построить план (ничего не пишет на диск)
repoctl init --repo ../new-repo --name new-repo --type project --owner team-name --output json > plan.json

Ответы проверяются до сборки плана, чтобы 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. Прочитайте план, убедитесь, что он ожидаем.

# Шаг 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):

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:

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 независимо от кодовой страницы консоли.