120 lines
12 KiB
Markdown
120 lines
12 KiB
Markdown
# Реализация Repository Stewardship и `repoctl` L1
|
||
|
||
## Результат
|
||
|
||
В этом репозитории появится рабочий кроссплатформенный CLI `repoctl`, который станет единым интерфейсом для людей, Claude и других агентов:
|
||
|
||
- обнаруживает и описывает репозитории;
|
||
- валидирует contract, KDB, пути и документацию;
|
||
- выдаёт минимальный контекст по intent;
|
||
- создаёт новые репозитории;
|
||
- безопасно подключает существующие;
|
||
- строит каталог и связи между репозиториями;
|
||
- не выполняет инфраструктурные операции и не обращается к внешним системам.
|
||
|
||
Реализация — Python 3.11+, управление через `uv`, пакет `repository-stewardship`, модуль `stewardship`, команда `repoctl`. Используются `ruamel.yaml` для безопасного YAML и сохранения форматирования, `jsonschema` Draft 2020-12 для публичных схем и стандартный `argparse` без тяжёлого CLI-фреймворка. Структура `src/` и `uv_build` соответствует рекомендациям [uv](https://docs.astral.sh/uv/concepts/projects/init/).
|
||
|
||
## Архитектура и публичные интерфейсы
|
||
|
||
- Разделить код на независимые слои: модели и схемы, безопасный I/O, validation, discovery/catalog, context selection, bootstrap, adoption, CLI rendering. CLI остаётся тонким адаптером; эти же функции позднее сможет вызвать MCP server.
|
||
- Хранить versioned schemas и шаблоны как package resources, доступные и из исходников, и из установленного wheel.
|
||
- Добавить JSON Schemas для:
|
||
- `RepositoryContract`, `KnowledgeBase`, `CatalogIndex`, `ContextBundle`;
|
||
- `BootstrapPlan`;
|
||
- `AdoptionAssessment`, `AdoptionPlan`, `AdoptionReport`;
|
||
- пользовательской конфигурации и общего результата CLI.
|
||
- Ввести стабильный machine-output envelope `stewardship/repoctl-result@0.1` с полями `command`, `outcome`, `data`, `findings`. В `data` остаётся соответствующий protocol resource.
|
||
- Все команды поддерживают `--output human|yaml|json`. Machine output идёт только в stdout, диагностика процесса — в stderr.
|
||
- Неизвестные нормативные поля отклоняются; `x-*`, `metadata.annotations`, открытые content roles и domain data сохраняются.
|
||
- Зафиксировать exit codes из спецификации: `0` success, `1` validation failure, `2` invalid input, `3` repository not found, `4` incomplete/stale strict context, `5` approval failure.
|
||
|
||
Командный интерфейс:
|
||
|
||
```text
|
||
repoctl config show|add-root|remove-root
|
||
repoctl validate [--repo PATH]
|
||
repoctl discover [--root PATH ...]
|
||
repoctl describe --repo NAME|PATH [--root PATH ...]
|
||
repoctl context --repo NAME|PATH --intent INTENT
|
||
[--include-related] [--materialize]
|
||
[--budget-bytes N] [--strict]
|
||
repoctl init --repo PATH [--answers FILE] [--git-init|--no-git-init]
|
||
repoctl init --repo PATH --apply --plan FILE --approve SHA256
|
||
repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||
[--answers FILE] [--strategy overlay|normalize]
|
||
[--recipe ID] [--plan FILE] [--approve SHA256]
|
||
```
|
||
|
||
Разрешение имени репозитория выполняется в порядке: явные `--root` → `REPOCTL_ROOTS` → пользовательский config → текущий repository. Config хранится в `%APPDATA%\RepositoryStewardship\config.yaml` на Windows и в XDG config directory на Unix. Его изменение выполняется только явными `config add-root/remove-root`; скрытый cache по умолчанию не создаётся.
|
||
|
||
## Поведение инструментов
|
||
|
||
- `validate` проверяет schemas, IDs, ссылки, content roots, path/symlink confinement, freshness, provenance, secret-shaped поля, operations без shell strings, Markdown links/frontmatter/YAML fences, сбалансированные code fences и статический синтаксис Mermaid.
|
||
- `discover` ищет `ops/contract.yaml`, не следует по symlink/junction, пропускает `.git`, virtual environments и dependency caches, строит детерминированный `CatalogIndex`, capability/requirement/binding relations и выявляет дубликаты repository ID.
|
||
- `describe` читает только contract и никогда не загружает KDB.
|
||
- `context` по умолчанию возвращает компактный bundle: topic data, document metadata, selectors/headings, operations и content roots. `--materialize` извлекает только явно выбранные Markdown-разделы или ограниченные YAML key paths; сеть не используется.
|
||
- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при `--strict` даёт exit `4`.
|
||
- Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
|
||
|
||
`init`:
|
||
|
||
- собирает ответы через CLI или YAML answers file; CLI имеет приоритет;
|
||
- предлагает type-specific content roots, но не создаёт фиктивные domain artifacts;
|
||
- создаёт contract, KDB, `AGENTS.md`, импортирующий его `CLAUDE.md`, template answers, `.gitignore` и три Claude skills;
|
||
- записывает template ID/version и SHA-256 revision шаблона;
|
||
- при необходимости включает `git init`, но не создаёт remote, commit или push;
|
||
- выдаёт структурированную рекомендацию отдельного repository-scoped SSH key, не генерируя и не сохраняя secret;
|
||
- сначала возвращает полный `BootstrapPlan`; запись возможна только по plan-файлу и его SHA-256.
|
||
|
||
`adopt`:
|
||
|
||
- реализует runbook `assess → plan → apply → verify`;
|
||
- различает detected, inferred и confirmed данные;
|
||
- фиксирует HEAD либо состояние `unborn`, dirty paths и hashes всех входных/touched файлов;
|
||
- по умолчанию использует overlay и сохраняет domain-native layout;
|
||
- для legacy root `kdb.yaml` предлагает небольшой `kdb/kdb.yaml` adapter;
|
||
- если legacy KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`;
|
||
- существующие skills, handlers, KDB и agent instructions не переписывает;
|
||
- tracked secret является blocker; untracked secret-shaped paths показываются path-only без содержимого;
|
||
- `documents-to-content-root` выполняется только как явно выбранная normalization recipe с rename map, conservative Markdown/frontmatter/YAML rewrites и collision checks;
|
||
- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
|
||
- никогда не делает commit, push, clone или external operation.
|
||
|
||
## Claude и self-hosting
|
||
|
||
Добавить три коротких project skills:
|
||
|
||
- `repository-bootstrap`;
|
||
- `repository-adoption`;
|
||
- `repo-handoff`.
|
||
|
||
Они размещаются в `.claude/skills/<name>/SKILL.md`, как предусмотрено [Claude Code](https://code.claude.com/docs/en/skills), и только собирают недостающие решения, вызывают `repoctl` с machine output и объясняют findings. Логика CLI в skills не дублируется. Те же skills входят в bootstrap templates; остальные агенты используют команды из `AGENTS.md`.
|
||
|
||
Сам репозиторий переводится из `specification-only` в `l1-implemented`:
|
||
|
||
- contract получает реальные content roots для исходников, schemas/templates и Claude adapters;
|
||
- KDB индексирует новую справку `repoctl` и handoff intents;
|
||
- README, specification, guide, adoption runbook и agent instructions обновляются под фактический CLI;
|
||
- фиктивные handlers и operations не объявляются;
|
||
- MCP, L2 handler ABI и инфраструктурный apply остаются отложенными.
|
||
|
||
## Проверки и приёмка
|
||
|
||
- Fixtures четырёх repository types и отрицательные fixtures для неизвестных полей, `x-*`, duplicate IDs, Windows/Unix traversal, UNC/absolute paths, symlink escape, secrets и shell strings.
|
||
- Golden tests одинакового YAML/JSON output и exit codes.
|
||
- Context tests для exact intent, related topics, Markdown headings, legacy YAML selectors, stale/missing sources и byte-budget.
|
||
- Catalog tests для стабильной сортировки, hashes, duplicate repositories и capability matching.
|
||
- Init/adoption tests подтверждают отсутствие записей до approval, отказ при неверном hash или изменившемся baseline и отсутствие commit/push.
|
||
- LXD fixture сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml`.
|
||
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
|
||
- Normalization tests покрывают exclusions, case-insensitive collisions, reference rewrites и rollback.
|
||
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
|
||
- Реальные `Infra/LXD` и `Services/Antivirus` используются только для read-only `assess` и `plan`; Git status до и после должен совпасть. Никакие планы к ним не применяются.
|
||
|
||
## Зафиксированные ограничения
|
||
|
||
- Версия пакета и шаблонов начинается с `0.1.0`; protocol остаётся `stewardship.corsus.ru/v1alpha1`.
|
||
- Первая версия работает только с уже доступными локальными repositories; clone по URL отложен.
|
||
- Не реализуются handlers, execution runner, внешние credentials, immutable cross-repository L3 Plan, MCP server и автоматический catalog daemon.
|
||
- Пользовательские и пилотные dirty worktrees сохраняются без изменений.
|