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:
+5
-3
@@ -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
@@ -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)
|
||||||
|
|||||||
Reference in New Issue
Block a user