diff --git a/docs/repoctl.md b/docs/repoctl.md index 3bdb0b3..9430f27 100644 --- a/docs/repoctl.md +++ b/docs/repoctl.md @@ -40,12 +40,14 @@ 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 +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` — всё ли корректно @@ -110,7 +112,7 @@ repoctl init --repo ../new-repo --name new-repo --type project --owner team-name repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256: --output json ``` -`--approve` должен побайтово совпасть с `planHash` — иначе команда завершится кодом `5` (approval required/denied) и ничего не запишет. `init` также повторно проверяет, что ни один из планируемых файлов не появился с момента построения плана — иначе откажется перезаписывать существующее. +`--approve` должен побайтово совпасть с `planHash` — иначе команда завершится кодом `5` (approval required/denied) и ничего не запишет. `init` также повторно проверяет, что ни один из планируемых файлов не появился с момента построения плана — иначе откажется перезаписывать существующее. `--plan` принимает как файл, сохранённый напрямую из `--output json > plan.json` (полный envelope с `data`), так и голый объект плана — `repoctl` сам распознаёт и разворачивает envelope. ### `adopt` — подключить существующий репозиторий diff --git a/src/stewardship/cli.py b/src/stewardship/cli.py index e76d602..23f0d67 100644 --- a/src/stewardship/cli.py +++ b/src/stewardship/cli.py @@ -13,7 +13,7 @@ from pathlib import Path from typing import Any from . import adoption, bootstrap, config, discovery, io -from .constants import CONTRACT_PATH +from .constants import CONTRACT_PATH, RESULT_SCHEMA from .context import build_context from .paths import find_repository_root from .render import build_envelope, emit @@ -59,6 +59,18 @@ def _write(envelope: dict[str, Any], output: str) -> None: emit(envelope, output) +def _load_plan(path: Path) -> dict[str, Any]: + """Load a plan file, transparently unwrapping a saved `--output json/yaml` + result envelope (`{"schema": "stewardship/repoctl-result@0.1", "data": {...}}`) + down to its `data`, since that is the natural way to capture a plan + (`repoctl ... --output json > plan.json`).""" + loaded: dict[str, Any] = io.load_yaml(path) + data = loaded.get("data") if isinstance(loaded, dict) else None + if isinstance(loaded, dict) and loaded.get("schema") == RESULT_SCHEMA and isinstance(data, dict): + return data + return loaded + + def cmd_config(args: argparse.Namespace) -> int: if args.config_action == "show": data = config.load_config() @@ -140,7 +152,7 @@ def cmd_init(args: argparse.Namespace) -> int: if args.apply: if not args.plan or not args.approve: raise CliError("--apply requires --plan and --approve", EXIT_INVALID_INPUT) - plan = io.load_yaml(Path(args.plan)) + plan = _load_plan(Path(args.plan)) repo_path.mkdir(parents=True, exist_ok=True) try: written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve) @@ -217,7 +229,7 @@ def cmd_adopt(args: argparse.Namespace) -> int: if args.mode == "apply": if not args.plan or not args.approve: raise CliError("--mode apply requires --plan and --approve", EXIT_INVALID_INPUT) - plan = io.load_yaml(Path(args.plan)) + plan = _load_plan(Path(args.plan)) try: written = adoption.apply_plan(repo_path, plan, args.approve) except ValueError as exc: @@ -231,7 +243,7 @@ def cmd_adopt(args: argparse.Namespace) -> int: return EXIT_SUCCESS if args.mode == "verify": - verify_plan = io.load_yaml(Path(args.plan)) if args.plan else None + verify_plan = _load_plan(Path(args.plan)) if args.plan else None report = adoption.verify(repo_path, verify_plan) outcome = "failure" if report["outcome"] == "fail" else "success" _write(build_envelope("adopt verify", outcome, report, []), args.output)