"""`repoctl`: thin argparse CLI adapter over the stewardship library. Exit codes (specification.md 19.2): 0 success, 1 validation/operation failure, 2 invalid invocation/input, 3 repository not found, 4 stale/incomplete strict context, 5 approval required or denied. """ from __future__ import annotations import argparse import sys from pathlib import Path from typing import Any from . import adoption, bootstrap, config, discovery, io from .constants import CONTRACT_PATH from .context import build_context from .paths import find_repository_root from .render import build_envelope, emit from .schema_loader import validate_against_kind from .types import Finding from .validate import validate_repository EXIT_SUCCESS = 0 EXIT_VALIDATION_FAILURE = 1 EXIT_INVALID_INPUT = 2 EXIT_NOT_FOUND = 3 EXIT_STRICT_INCOMPLETE = 4 EXIT_APPROVAL = 5 class CliError(Exception): def __init__(self, message: str, exit_code: int = EXIT_INVALID_INPUT): super().__init__(message) self.exit_code = exit_code def _resolve_repo(repo_arg: str | None, roots: list[str] | None) -> Path: if repo_arg: candidate = Path(repo_arg).expanduser() if candidate.exists(): root = find_repository_root(candidate) if root is None: raise CliError(f"No .git ancestor found for {candidate}", EXIT_NOT_FOUND) return root found, _ = discovery.discover_repositories(config.resolve_roots(roots)) for repo in found: name = (repo.contract.get("metadata") or {}).get("name") if name == repo_arg: return repo.path raise CliError(f"Repository not found: {repo_arg}", EXIT_NOT_FOUND) root = find_repository_root(Path.cwd()) if root is None: raise CliError("No .git ancestor found from current directory", EXIT_NOT_FOUND) return root def _write(envelope: dict[str, Any], output: str) -> None: emit(envelope, output) def cmd_config(args: argparse.Namespace) -> int: if args.config_action == "show": data = config.load_config() _write(build_envelope("config show", "success", data, []), args.output) return EXIT_SUCCESS if args.config_action == "add-root": data = config.add_root(args.path) _write(build_envelope("config add-root", "success", data, []), args.output) return EXIT_SUCCESS if args.config_action == "remove-root": data = config.remove_root(args.path) _write(build_envelope("config remove-root", "success", data, []), args.output) return EXIT_SUCCESS raise CliError("Unknown config action") def cmd_validate(args: argparse.Namespace) -> int: root = _resolve_repo(args.repo, args.root) result = validate_repository(root) outcome = "success" if result.ok else "failure" data = {"repository": str(root), "valid": result.ok} _write(build_envelope("validate", outcome, data, result.findings), args.output) return EXIT_SUCCESS if result.ok else EXIT_VALIDATION_FAILURE def cmd_discover(args: argparse.Namespace) -> int: roots = config.resolve_roots(args.root) catalog, findings = discovery.build_catalog_index(roots) has_error = any(f.severity == "error" for f in findings) _write(build_envelope("discover", "failure" if has_error else "success", catalog, findings), args.output) return EXIT_VALIDATION_FAILURE if has_error else EXIT_SUCCESS def cmd_describe(args: argparse.Namespace) -> int: root = _resolve_repo(args.repo, args.root) contract_path = root / CONTRACT_PATH if not contract_path.exists(): raise CliError(f"{CONTRACT_PATH} not found under {root}", EXIT_NOT_FOUND) contract = io.load_yaml(contract_path) errors = validate_against_kind("RepositoryContract", contract) if isinstance(contract, dict) else ["not a mapping"] findings = [Finding("error", "CONTRACT_SCHEMA_INVALID", e) for e in errors] outcome = "failure" if findings else "success" _write(build_envelope("describe", outcome, contract, findings), args.output) return EXIT_VALIDATION_FAILURE if findings else EXIT_SUCCESS def cmd_context(args: argparse.Namespace) -> int: root = _resolve_repo(args.repo, args.root) result = build_context( root, args.intent, include_related=args.include_related, materialize=args.materialize, budget_bytes=args.budget_bytes, strict=args.strict, ) data = dict(result.bundle) if result.materialized: data["spec"] = dict(data["spec"]) data["spec"]["materializedContent"] = [ {"document": m.document_id, "path": m.path, "bytes": m.bytes_used, "content": m.content} for m in result.materialized ] findings = [ Finding(w.split(":", 2)[0], w.split(":", 2)[1], w.split(":", 2)[2]) for w in result.bundle["spec"]["warnings"] ] outcome = "success" exit_code = EXIT_SUCCESS if (result.truncated or result.incomplete) and args.strict: outcome = "failure" exit_code = EXIT_STRICT_INCOMPLETE _write(build_envelope("context", outcome, data, findings), args.output) return exit_code def cmd_init(args: argparse.Namespace) -> int: repo_path = Path(args.repo).expanduser() 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)) repo_path.mkdir(parents=True, exist_ok=True) try: written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve) except ValueError as exc: _write(build_envelope("init apply", "failure", None, [Finding("error", "APPROVAL_FAILED", str(exc))]), args.output) return EXIT_APPROVAL except FileExistsError as exc: _write(build_envelope("init apply", "failure", None, [Finding("error", "ADOPT_PATH_COLLISION", str(exc))]), args.output) return EXIT_VALIDATION_FAILURE _write(build_envelope("init apply", "success", {"written": written}, []), args.output) return EXIT_SUCCESS if args.answers: answers_data = io.load_yaml(Path(args.answers)) else: answers_data = {} if args.name: answers_data["name"] = args.name if args.type: answers_data["repositoryType"] = args.type if args.title: answers_data["title"] = args.title if args.owner: answers_data["owners"] = list(args.owner) if args.lifecycle: answers_data["lifecycle"] = args.lifecycle if args.git_init: answers_data["gitInit"] = True missing = [f for f in ("name", "repositoryType") if f not in answers_data] if missing: raise CliError(f"Missing required answers: {', '.join(missing)}", EXIT_INVALID_INPUT) answers = bootstrap.BootstrapAnswers.from_mapping(answers_data) plan = bootstrap.build_bootstrap_plan(answers) _write(build_envelope("init plan", "success", plan, []), args.output) return EXIT_SUCCESS def cmd_adopt(args: argparse.Namespace) -> int: repo_path = Path(args.repo).expanduser() if not repo_path.exists(): raise CliError(f"Path does not exist: {repo_path}", EXIT_NOT_FOUND) if args.mode == "assess": result = adoption.assess(repo_path) findings = [ Finding(f["severity"], f["code"], f.get("message", f["code"]), path=f.get("path")) for f in result["findings"] ] blocker = any(f.severity == "error" for f in findings) _write(build_envelope("adopt assess", "failure" if blocker else "success", result, findings), args.output) return EXIT_VALIDATION_FAILURE if blocker else EXIT_SUCCESS if args.mode == "plan": assessment = adoption.assess(repo_path) if args.answers: answers = io.load_yaml(Path(args.answers)) else: answers = {} name = answers.get("name") or repo_path.name.lower() plan = adoption.build_plan( repo_path, assessment, confirmed_name=name, confirmed_title=answers.get("title"), confirmed_owners=answers.get("owners"), confirmed_lifecycle=answers.get("lifecycle", "active"), strategy=args.strategy, ) _write(build_envelope("adopt plan", "success", plan, []), args.output) return EXIT_SUCCESS 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)) try: written = adoption.apply_plan(repo_path, plan, args.approve) except ValueError as exc: code = "APPROVAL_FAILED" if "Approval" in str(exc) or "hash" in str(exc) else "ADOPT_BASELINE_CHANGED" _write(build_envelope("adopt apply", "failure", None, [Finding("error", code, str(exc))]), args.output) return EXIT_APPROVAL except FileExistsError as exc: _write(build_envelope("adopt apply", "failure", None, [Finding("error", "ADOPT_PATH_COLLISION", str(exc))]), args.output) return EXIT_VALIDATION_FAILURE _write(build_envelope("adopt apply", "success", {"written": written}, []), args.output) return EXIT_SUCCESS if args.mode == "verify": verify_plan = io.load_yaml(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) return EXIT_VALIDATION_FAILURE if report["outcome"] == "fail" else EXIT_SUCCESS raise CliError(f"Unknown adopt mode: {args.mode}", EXIT_INVALID_INPUT) def build_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser(prog="repoctl", description="Repository Stewardship CLI") sub = parser.add_subparsers(dest="command", required=True) def add_common(p: argparse.ArgumentParser) -> None: p.add_argument("--output", choices=["human", "yaml", "json"], default="human") p_config = sub.add_parser("config") add_common(p_config) config_sub = p_config.add_subparsers(dest="config_action", required=True) config_sub.add_parser("show") p_add_root = config_sub.add_parser("add-root") p_add_root.add_argument("path") p_remove_root = config_sub.add_parser("remove-root") p_remove_root.add_argument("path") p_config.set_defaults(func=cmd_config) p_validate = sub.add_parser("validate") add_common(p_validate) p_validate.add_argument("--repo") p_validate.add_argument("--root", action="append") p_validate.set_defaults(func=cmd_validate) p_discover = sub.add_parser("discover") add_common(p_discover) p_discover.add_argument("--root", action="append") p_discover.set_defaults(func=cmd_discover) p_describe = sub.add_parser("describe") add_common(p_describe) p_describe.add_argument("--repo") p_describe.add_argument("--root", action="append") p_describe.set_defaults(func=cmd_describe) p_context = sub.add_parser("context") add_common(p_context) p_context.add_argument("--repo") p_context.add_argument("--root", action="append") p_context.add_argument("--intent", required=True) p_context.add_argument("--include-related", action="store_true") p_context.add_argument("--materialize", action="store_true") p_context.add_argument("--budget-bytes", type=int, default=None) p_context.add_argument("--strict", action="store_true") p_context.set_defaults(func=cmd_context) p_init = sub.add_parser("init") add_common(p_init) p_init.add_argument("--repo", required=True) p_init.add_argument("--answers") p_init.add_argument("--name") p_init.add_argument("--type", dest="type", choices=["infrastructure-config", "service-config", "software", "project"]) p_init.add_argument("--title") p_init.add_argument("--owner", action="append") p_init.add_argument("--lifecycle") p_init.add_argument("--git-init", action="store_true") p_init.add_argument("--no-git-init", dest="git_init", action="store_false") p_init.set_defaults(git_init=None) p_init.add_argument("--apply", action="store_true") p_init.add_argument("--plan") p_init.add_argument("--approve") p_init.set_defaults(func=cmd_init) p_adopt = sub.add_parser("adopt") add_common(p_adopt) p_adopt.add_argument("--repo", required=True) p_adopt.add_argument("--mode", required=True, choices=["assess", "plan", "apply", "verify"]) p_adopt.add_argument("--answers") p_adopt.add_argument("--strategy", default="overlay", choices=["overlay", "normalize"]) p_adopt.add_argument("--recipe") p_adopt.add_argument("--plan") p_adopt.add_argument("--approve") p_adopt.set_defaults(func=cmd_adopt) return parser def _force_utf8_streams() -> None: """Force UTF-8 stdout/stderr regardless of the host locale/console codepage. Machine output (YAML/JSON) must be reliably UTF-8 for downstream parsers; on Windows, sys.stdout otherwise defaults to the console codepage when not attached to a UTF-8 terminal, which can corrupt or fail to decode non-ASCII content. """ for stream in (sys.stdout, sys.stderr): reconfigure = getattr(stream, "reconfigure", None) if callable(reconfigure): try: reconfigure(encoding="utf-8") except (ValueError, OSError): pass def main(argv: list[str] | None = None) -> int: _force_utf8_streams() parser = build_parser() args = parser.parse_args(argv) try: result: int = args.func(args) return result except CliError as exc: print(f"ERROR: {exc}", file=sys.stderr) return exc.exit_code except Exception as exc: # noqa: BLE001 - top-level CLI safety net print(f"ERROR: {exc}", file=sys.stderr) return EXIT_VALIDATION_FAILURE if __name__ == "__main__": raise SystemExit(main())