fix: accept saved result envelopes as plan files; fix docs CLI examples

apply_plan/apply_bootstrap_plan required the raw plan object, but the
natural capture workflow (repoctl ... --output json > plan.json) saves
the full result envelope, so following the documented workflow verbatim
failed the hash check. repoctl now unwraps a stored envelope's `data`
automatically (an idea worth keeping from codex/repoctl-l1's cli.py,
which had the same fallback).

Found while walking docs/repoctl.md's adopt and cross-repo examples
live end to end: two more invocation bugs in the doc itself
(`config add-root` takes a positional path, not `--path`; `--output`
must follow `config` itself, not the add-root/remove-root subaction) --
fixed and clarified in place.
This commit is contained in:
Alexander Baranov
2026-08-24 16:02:24 +03:00
parent 4fbe56d81f
commit 36d5d01d43
2 changed files with 21 additions and 7 deletions
+5 -3
View File
@@ -40,12 +40,14 @@ repoctl validate --repo .
Пока `repoctl` не установлен как инструмент, из исходников этого репозитория он запускается через `uv run repoctl ...` (см. README.md). Если репозиториев несколько и они лежат в общем каталоге, добавьте этот каталог как root один раз: Пока `repoctl` не установлен как инструмент, из исходников этого репозитория он запускается через `uv run repoctl ...` (см. README.md). Если репозиториев несколько и они лежат в общем каталоге, добавьте этот каталог как root один раз:
```bash ```bash
repoctl config add-root --path C:/Users/example/Git repoctl config --output json add-root C:/Users/example/Git
repoctl describe --repo some-repo-name repoctl describe --repo some-repo-name --output json
``` ```
Порядок разрешения имени репозитория: явный `--root` → переменная окружения `REPOCTL_ROOTS` → сохранённый `config add-root` → текущий репозиторий (если команда запущена изнутри него). Порядок разрешения имени репозитория: явный `--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` — всё ли корректно ### `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:<planHash-из-плана> --output json repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256:<planHash-из-плана> --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` — подключить существующий репозиторий ### `adopt` — подключить существующий репозиторий
+16 -4
View File
@@ -13,7 +13,7 @@ from pathlib import Path
from typing import Any from typing import Any
from . import adoption, bootstrap, config, discovery, io 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 .context import build_context
from .paths import find_repository_root from .paths import find_repository_root
from .render import build_envelope, emit from .render import build_envelope, emit
@@ -59,6 +59,18 @@ def _write(envelope: dict[str, Any], output: str) -> None:
emit(envelope, output) 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: def cmd_config(args: argparse.Namespace) -> int:
if args.config_action == "show": if args.config_action == "show":
data = config.load_config() data = config.load_config()
@@ -140,7 +152,7 @@ def cmd_init(args: argparse.Namespace) -> int:
if args.apply: if args.apply:
if not args.plan or not args.approve: if not args.plan or not args.approve:
raise CliError("--apply requires --plan and --approve", EXIT_INVALID_INPUT) 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) repo_path.mkdir(parents=True, exist_ok=True)
try: try:
written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve) 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 args.mode == "apply":
if not args.plan or not args.approve: if not args.plan or not args.approve:
raise CliError("--mode apply requires --plan and --approve", EXIT_INVALID_INPUT) 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: try:
written = adoption.apply_plan(repo_path, plan, args.approve) written = adoption.apply_plan(repo_path, plan, args.approve)
except ValueError as exc: except ValueError as exc:
@@ -231,7 +243,7 @@ def cmd_adopt(args: argparse.Namespace) -> int:
return EXIT_SUCCESS return EXIT_SUCCESS
if args.mode == "verify": 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) report = adoption.verify(repo_path, verify_plan)
outcome = "failure" if report["outcome"] == "fail" else "success" outcome = "failure" if report["outcome"] == "fail" else "success"
_write(build_envelope("adopt verify", outcome, report, []), args.output) _write(build_envelope("adopt verify", outcome, report, []), args.output)