diff --git a/README.md b/README.md index b2a36a3..7d671f8 100644 --- a/README.md +++ b/README.md @@ -21,10 +21,12 @@ approval для любых записей. `ops/handlers/`, execution runner и | `docs/specification.md` | нормативная спецификация | | `docs/guide.md` | объяснение модели для человека | | `docs/adoption-runbook.md` | перевод существующих репозиториев на стандарт | +| `docs/repoctl.md` | руководство по `repoctl` для человека: установка, команды, коды возврата | | `docs/research/` | исходные архитектурные исследования | | `src/stewardship/` | реализация `repoctl` (модели, schemas, CLI) | | `src/stewardship/schemas/` | JSON Schemas (Draft 2020-12) для всех kinds | -| `tests/` | fixtures и pytest-набор (позитивные, негативные, adoption) | +| `tests/` | unit pytest-набор (позитивные, негативные, adoption fixtures) | +| `tests-universal/` | spec-driven CLI-контрактный набор, независимый от реализации | | `.claude/skills/` | три тонких Claude skill-адаптера над `repoctl` | ### Установка и запуск @@ -33,9 +35,10 @@ approval для любых записей. `ops/handlers/`, execution runner и uv sync uv run repoctl validate --repo . uv run pytest +uv run pytest tests-universal ``` -`uv sync` создаёт `.venv` в корне репозитория; все команды выполняются через `uv run`. +`uv sync` создаёт `.venv` в корне репозитория; все команды выполняются через `uv run`. `tests-universal` — отдельный набор: он вызывает `repoctl` только как внешний процесс и сверяется исключительно с `docs/specification.md`, поэтому им можно проверить любую совместимую реализацию, а не только эту. Практическое руководство по самому CLI — в [docs/repoctl.md](docs/repoctl.md). ## Как пользоваться содержимым diff --git a/docs/repoctl.md b/docs/repoctl.md new file mode 100644 index 0000000..3bdb0b3 --- /dev/null +++ b/docs/repoctl.md @@ -0,0 +1,147 @@ +--- +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: --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: --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 независимо от кодовой страницы консоли. diff --git a/kdb/kdb.yaml b/kdb/kdb.yaml index b8efa4b..8cb3d63 100644 --- a/kdb/kdb.yaml +++ b/kdb/kdb.yaml @@ -119,6 +119,7 @@ spec: - stewardship-specification - adoption-runbook - stewardship-guide + - repoctl-human-guide data: loadPolicy: selected-sections readHints: @@ -135,6 +136,11 @@ spec: - 14. Интерфейсы для агентов и людей - 15. Простая первая версия - 16. Предлагаемая внутренняя структура repoctl + - document: repoctl-human-guide + headings: + - Команды по порядку знакомства + - Коды возврата + - Устранение неполадок - id: architecture-research title: Revisit architecture choices summary: Earlier alternatives, trade-offs and external design lineage @@ -186,3 +192,10 @@ spec: mediaType: text/markdown authority: manual status: draft + - id: repoctl-human-guide + title: repoctl CLI reference for humans + role: explanation + path: docs/repoctl.md + mediaType: text/markdown + authority: local-canonical + status: draft diff --git a/tests-universal/conftest.py b/tests-universal/conftest.py index 4755c6d..46b5d91 100644 --- a/tests-universal/conftest.py +++ b/tests-universal/conftest.py @@ -16,7 +16,6 @@ from __future__ import annotations import json import os -import shutil import subprocess from pathlib import Path from typing import Any @@ -70,6 +69,7 @@ def run_repoctl(*args: str, cwd: Path | None = None) -> Result: capture_output=True, text=True, encoding="utf-8", + check=False, ) return Result(proc)